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

On Mon, Apr 22, 2013 at 3:59 PM, Mark Watson <watsonm@netflix.com> wrote:
>
>
> 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
> ...).

Mark, There's the ongoing request from Mike and Richard on supporting
short-names as a form of short-hand for specifying a name and
parameters. The translation from short names into a canonical set of
parameters that can be well understood and universally agreed is the
normalization process.

By splitting out Algorithm & Operation parameters, it simply means
that this concept has to be duplicated for both sets, since the use
case applies to both.

This seems like needless complexity.

> 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.

Hopefully you can see why that isn't sufficient.

>
> 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).

Your proposal equates to changing the name of a single type - it
doesn't change calling conventions at all, and just requires
duplicating even more boilerplate process definition for both
algorithms and operations.

As you acknowledged, it doesn't change the API at all, so I'm trying
to understand where and why you see it as adding clarity.

>
> ...Mark
>
>>
>>
>> Cheers,
>> Ryan
>
>

Received on Monday, 22 April 2013 23:08:41 UTC