Re: PROPOSAL for ISSUE-12: Should the API distinguish between algorithm and operation parameters?

On Mon, Apr 22, 2013 at 3:45 PM, Ryan Sleevi <sleevi@google.com> wrote:

> On Mon, Apr 22, 2013 at 2:06 PM, Mark Watson <watsonm@netflix.com> wrote:
> > http://www.w3.org/2012/webcrypto/track/issues/12
> >
> > Based on the discussion and assuming the acceptance of the proposal in
> > ISSUE-42 (http://www.w3.org/2012/webcrypto/track/issues/42), I propose
> the
> > following:
> >
> > 1) Define a new dictionary, OperationParameters:
> >
> > dictionary OperationParameters {
> > };
> >
> > 2) Change the first parameter of encrypt(), decrypt(), sign(), verify()
> to
> > be of type OperationParameters
> >
> > 3) Change the base class of the following dictionaries to be
> > OperationParameters
> >
> > RsaSsaParams
> > RsaPssParams
> > RsaOaepParams
> > EcdsaParams
> > AesCtrParams
> > AesCbcParams
> > AesGcmParams
> >
> > 4) Decide whether the hash is a property of a HMAC Key or an operation
> > parameter and then either
> > 4.1) (hash is a property of the HMAC Key): remove HmacParams from the
> > sign/verify rows of the table in 19.12.2, or
> > 4.2) (hash is an operation parameter): change the base class of
> HmacParams
> > to be OperationParameters and define new HmacKeyGenParams as follows:
> >
> > dictionary HmacKeyGenParams : Algorithm {
> >   // The length, in bits, of the key.
> >   [EnforceRange] unsigned short length;
> > };
> >
> >
> > ...Mark
>
> Mark,
>
> It seems wrong to couple the HMAC discussion into the discussion about
> naming.
>

Ok - I assumed the HMAC thing was straightforward. We can define both
HmacParams and HmacKeyGenParams (and then discuss whether they should be
the same).


>
> Am I correct in stating that this proposal is done purely on cosmetic
> grounds - that is, there is no technical basis or reason for this
> change?
>

Well, it depends whether you consider clarity a "technical" reason. But,
no, there is no change to sample code, for example, just to how we describe
the API.


>
> This does introduce further complexity in defining if and how
> normalization occurs for operation params - requiring a definition of
> a second set of processing functions - so I would like to understand
> what benefits (if any) this proposal has.
>

I would actually consider that a reduction in complexity because it
separates out things that should be separated, rather than munging them
into a single procedure, with the resulting confusion.

There should not be any need to "normalize" operation parameters except
where there is a parameter which is an AlgorithmIdentifier (unless you
consider filling in missing parameters with defaults as normalization - but
I'd guess you'd consider that a moot point, since we don't have defaults
...). It should take only a single line to say that operation parameters of
type Algorithm must be normalized according to the normalization rules for
AlgorithmIdentifiers.

The fact that the current procedures mix normalization of algorithm
parameters and operation parameters is another reason why they should be
separate. It's really terribly confusing right now (at least for anyone who
hasn't already lived with it for 6 months).

...Mark


>
> Cheers,
> Ryan
>