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 Friday, 17 August 2012 21:36:39 UTC