RE: crypto-ISSUE-12: Should the API distinguish between algorithm and operation parameters? [Web Cryptography API]

I want to support Vijay's point that the algorithm identifier should be a "constant", whereas data input values supplied to the algorithms (such as initialization vector values, additional authenticated data parameters, and of course the plaintext) should be distinct.  Note that I *do* consider behavioral algorithm parameters, such as the hash function used with an HMAC (e.g. HMAC-SHA-256), or the padding mode used with an encryption algorithm (such as PKCS #1 Padding) to be part of the "constant" algorithm identifier.

The distinction is between behavioral algorithm parameter values, which should be part of the algorithm, and data input values used by the algorithm, which should not be.

				-- Mike

-----Original Message-----
From: Vijay Bharadwaj [] 
Sent: Monday, August 27, 2012 2:59 AM
To: Ryan Sleevi
Cc: Web Cryptography Working Group
Subject: RE: crypto-ISSUE-12: Should the API distinguish between algorithm and operation parameters? [Web Cryptography API]

Actually, having had time to think about this and read the current Editor's draft, I wonder if the Key member of CryptoOperation shouldn't be replaced with an OperationParameters structure.

IMO one of the problems of the CryptoOperation as currently specified is that while it tries to cover cases where there are:
- 0 keys (e.g. hash)
- 1 key (e.g. encryption, signature)
- 2 keys (e.g. secret agreement)

And does so with exactly one key in the structure. This leads to hacks like saying that the Key must be null for hashing, and whatever other hack we might want to do for secret agreement algorithms (which are not specified yet).

Instead, how about:

enum OperationType {

dictionary OperationParameters {

interface CryptoOperation : EventTarget {
  void init();
  void processData(ArrayBufferView buffer);
  void complete();
  void abort();

  readonly attribute Algorithm algorithm;
  readonly attribute OperationParameters opParams;
  readonly attribute any result;

  [TreatNonCallableasNull] attribute Function? onabort;
  [TreatNonCallableAsNull] attribute Function? onerror;
  [TreatNonCallableAsNull] attribute Function? oninit;
  [TreatNonCallableAsNull] attribute Function? onprogress;
  [TreatNonCallableAsNull] attribute Function? oncomplete; };
And instead of createEncrypter, createDecrypter, etc., you just have

interface Crypto {
  CryptoOperation createOperation(OperationType operation, AlgorithmIdentifier algorithm, OperationParameters opParams);
  ... other stuff ...

Then, for encryption, decryption, etc. the OperationParameters would have an element:

Key key;

And for key agreement it would have something like:

Key ourPrivateKey;
Key theirPublicKey;

One last thing - I recognize that this is isomorphic to an API in which OperationParameters is also part of AlgorithmIdentifier; if you want to advocate for that path, I'm okay with it as well (as mentioned earlier, my objections there are primarily aesthetic).

-----Original Message-----
From: Ryan Sleevi []
Sent: Friday, August 17, 2012 2:36 PM
To: Vijay Bharadwaj
Cc: Web Cryptography Working Group
Subject: Re: crypto-ISSUE-12: Should the API distinguish between algorithm and operation parameters? [Web Cryptography API]

On Mon, Aug 13, 2012 at 8:13 AM, Vijay Bharadwaj <> wrote:
> There are two reasons I prefer to separate these two kinds of parameters.
> First, I think it is natural for a programmer to think of algorithm objects as "constants". In other words, I could see a programmer creating a single algorithm object and reusing it across operations, or storing an algorithm object in a configuration file somewhere for use with future operations (e.g. encAlg = config.myEncryptionMethod). I think lumping in operation-specific parameters would create a potential for cryptographic misuse here.

Well, yes, but there's lots of opportunity for cryptographic misuse with a low-level API.

My general concern with separating them out is now you have to worry about what algorithm parameters are compatible with what operation parameters, adding more dimensions to the processing rules and, I think, making it harder to validate.

> The second reason is that sometimes we have operation-specific parameters that are not related to the algorithm but to the data. For instance, AAD in authenticated encryption schemes, or (in a hash-in signature API) the hash OID for a PKCS#1 v1.5 signing operation. If we don't provide a natural container for these, they will have to go with the algorithm object, which seems incongruous to me.

In my experience, these are legitimately defined as inputs for the 'algorithm' when the algorithm is spec'd (eg: PKCS#1 or SP800-38D for GCM). There isn't typically a distinction between 'algorithm' and 'individual operation' here in the definitions of the algorithms. It also matches what many of the APIs themselves expose (eg: PKCS#11), in which all of the inputs for the algorithm are specified when creating the PKCS#11 operation.

> Aesthetically, I prefer APIs with multiple easily-defined simple parameters to those with a single complex structure that just aggregates all the parameters. A former colleague used to joke that we only need one C API in the world: void *doIt(void *param) - the point being that such APIs become rapidly more complicated as they are extended to cover newer use cases.

Well, sure, but I think this goes back to the very early discussions about window.crypto.AES vs window.crypto.encrypt().

With window.crypto.AES, you could do things like "CryptoOperation window.crypto.AES.CTR.encrypt(IV, Key)" or "CryptoOperation window.crypto.AES.GCM(IV, AAD, tagLength, Key)". This has the benefit that all the parameters are specified, but also all of the downsides discussed early on when contemplating this.

If you'd prefer such an API, I think we can raise it as an ISSUE.
Having originally proposed such an API, I can certainly see its benefits, and perhaps with creative and aggressive uses of function currying, we might be able to get the same semantics as today.

> Does that help explain the objection?

Thanks, yes.

> -----Original Message-----
> From: Ryan Sleevi []
> Sent: Sunday, August 5, 2012 7:19 PM
> To: Web Cryptography Working Group
> Cc: Vijay Bharadwaj
> Subject: Re: crypto-ISSUE-12: Should the API distinguish between 
> algorithm and operation parameters? [Web Cryptography API]
> On Sun, Aug 5, 2012 at 7:08 PM, Web Cryptography Working Group Issue Tracker <> wrote:
>> crypto-ISSUE-12: Should the API distinguish between algorithm and 
>> operation parameters? [Web Cryptography API]
>> Raised by: Ryan Sleevi
>> On product: Web Cryptography API
>> During the July Face-to-Face, concern was raised about the fact that, 
>> as currently specified in the 1.10 draft, the AlgorithmParams does 
>> not make a distinction between algorithm-specific parameters and 
>> operation-specific parameters.
>> An example of this is seen by examining the AES-CTR definition. The 
>> initial value of the counter ('counter') is something that is 
>> operation-specific, whereas the length of the counter ('length') is 
>> seen to be algorithm-specific. For a given protocol that uses 
>> AES-CTR, the counter length is expected to remain constant for all 
>> operations, while the actual value of the counter is expected to 
>> change (such as from message to message)
>> Similarly, for RSA-OAEP, the hash ('hash') and mask generation 
>> function
>> ('mgf') may be constant for multiple operations, whereas the 
>> authenticated data ('label') may change from operation to operation.
>> The question was raised as to whether the methods on the Crypto 
>> interface should take a separate dictionary of parameters.
> Vijay,
> You raised this issue during the Face-to-Face on the 24th [1], so I was hoping you could explain this more.
> It's not clear to me what the specific value is for splitting these out. As currently spec'd, AlgorithmParams contains all of the inputs for a given algorithm/operation combination in a single dictionary.
> My hesitation towards separating out the dictionary is that it would mean that, in general, an algorithm would need to keep track of dictionaries for:
> - Algorithm parameters
> - Operation parameters
> - Key generation parameters
> Is there a use-case you see for adding this?
> [1] , "vgb: As refered in email,"

Received on Monday, 27 August 2012 19:31:53 UTC