Re: [W3C Web Crypto WG] about extensions to Web Crypto specification

Ryan,

Could you elaborate on the problems with Mike's proposal. The examples
given by Anne in http://annevankesteren.nl/2014/02/monkey-patch say things
like:

"Specifications may define cloning steps for all or some nodes. The
algorithm is passed copy, node, document, and optionally a clone children
flag, as indicated in the clonealgorithm."

and, in the procedures,

"Run any cloning steps defined for node in other applicable specifications
and pass copy, node, document and the clone children flag if set, as
parameters.
"

This does not seem far from what Mike proposed - it's just a little more
explicit about where in the procedures the steps defined by extension
specifications can occur and what the inputs and outputs are expected to
be. If we follow that approach, does it address your concern ?

...Mark


On Tue, Sep 2, 2014 at 4:21 PM, Ryan Sleevi <sleevi@google.com> wrote:

> Mike's proposed language for Solution 2 notwithstanding (c.f. every other
> Web API with respect to extensibility), I certainly agree that (2), (3),
> (1) is the right approach.
>
>
> On Tue, Sep 2, 2014 at 4:12 PM, Mark Watson <watsonm@netflix.com> wrote:
>
>> My order of preference (most to least) is (2), (3), (1).
>>
>> (3) is in my mind the least-worst fallback for the eventuality that we
>> cannot get consensus on what constitutes a reasonable extensibility
>> mechanism for algorithm parameters. Mike's proposal seems reasonable to me.
>>
>> ...Mark
>>
>>
>> On Tue, Sep 2, 2014 at 3:47 PM, Mike Jones <Michael.Jones@microsoft.com>
>> wrote:
>>
>>>  These are my preferences in order:
>>>
>>>
>>>
>>> -          Scenario 2 : We work harder on the extension mechanism.
>>>
>>> This is the right solution.  In addition, I’d previously proposed
>>> specific language to accomplish this.  At each extension point, we should
>>> include language something like “Other values may be defined by other
>>> specifications and used.”
>>>
>>>
>>>
>>> -          Scenario 3 : We fragment the specification into several
>>> specifications, by algorithm family. This scenario looks like scenario 1,
>>> but makes updates easier on specific portions of the specification.
>>>
>>> This makes the whole of the WebCrypto unnecessarily hard to understand.
>>> And adding algorithms and algorithm parameters should not require updating
>>> specs – just writing new ones.
>>>
>>>
>>>
>>> -          Scenario 1 : We update the entire specification each time we
>>> have a new algorithm (bug requiring extensibility mechanism is WONTFIX)
>>>
>>> This would make WebCrypto as hard to update as specs like XMLDSIG and
>>> XMLENC.  The W3C’s negative experience in this regard should clearly steer
>>> us away from this path.
>>>
>>>
>>>
>>>                                                                 -- Mike
>>>
>>>
>>>
>>> *From:* GALINDO Virginie [mailto:Virginie.Galindo@gemalto.com]
>>> *Sent:* Tuesday, September 02, 2014 2:16 PM
>>> *To:* public-webcrypto@w3.org
>>> *Cc:* Harry Halpin; Wendy Seltzer
>>> *Subject:* [W3C Web Crypto WG] about extensions to Web Crypto
>>> specification
>>>
>>>
>>>
>>> Hi all,
>>>
>>>
>>>
>>> Thanks Mark for trying hard to make progress on that discussion. Lets
>>> measure motivation for the different scenario you mentioned for updating
>>> the web crypto API when a new algorithm needs to be added.
>>>
>>>
>>>
>>> -          Scenario 1 : We update the entire specification each time we
>>> have a new algorithm (bug requiring extensibility mechanism is WONTFIX)
>>>
>>> -          Scenario 2 : We work harder on the extension mechanism.
>>>
>>> -          Scenario 3 : We fragment the specification into several
>>> specifications, by algorithm family. This scenario looks like scenario 1,
>>> but makes updates easier on specific portions of the specification.
>>>
>>>
>>>
>>> Please state your preference order among those scenario from 1 to 3 (1:
>>> your preferred scenario, 2 : the medium attractive one, 3 : the one
>>> gathering lower support from you, but you could live with it).
>>>
>>> Please state scenario you object to.
>>>
>>>
>>>
>>> Note that we target to exit Last Call for Web Crytpo API mid-sept. As
>>> such, I would appreciate that constructive discussions happens here, as
>>> this bug is the last one preventing us from reaching that goal.
>>>
>>>
>>>
>>> Regards,
>>>
>>> Virginie Galindo
>>>
>>> chair of web crypto wg
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>> *From:* Mark Watson [mailto:watsonm@netflix.com <watsonm@netflix.com>]
>>> *Sent:* jeudi 28 août 2014 23:37
>>> *To:* Ryan Sleevi
>>> *Cc:* Mike Jones; GALINDO Virginie; public-webcrypto@w3.org
>>> *Subject:* Re: [W3C Web Crypto WG] about extensions to Web Crypto
>>> specification
>>>
>>>
>>>
>>>
>>>
>>> Sent from my iPhone
>>>
>>>
>>> On Aug 28, 2014, at 2:23 PM, Ryan Sleevi <sleevi@google.com> wrote:
>>>
>>>
>>>
>>>
>>>
>>> On Thu, Aug 28, 2014 at 2:21 PM, Mike Jones <Michael.Jones@microsoft.com>
>>> wrote:
>>>
>>> Thanks for listing these three options, Mark.  That’s clarifying.  What
>>> surprised me is that there’s a fourth option which wasn’t listed (which I
>>> thought was being considered) that I believe is superior to the three you
>>> listed:
>>>
>>>
>>>
>>> 4) Specification written in a way that it can be extended without
>>> requiring it to be revised.
>>>
>>>
>>>
>>> This is easy to do.  Every place that there’s a fixed list of choices in
>>> the spec, explicitly make it clear that the values listed are only the
>>> initial set defined, and that other values can be defined by other
>>> specifications and used.
>>>
>>>
>>>
>>> As a specific example, EcKeyGenParams in
>>> https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#EcKeyGenParams-dictionary
>>> defines NamedCurve as:
>>>
>>> The *NamedCurve* type represents named elliptic curves, which are a
>>> convenient way to specify the domain parameters of well-known elliptic
>>> curves. The following values are recognized:
>>>
>>> "P-256"
>>>
>>> NIST recommended curve P-256, also known as secp256r1.
>>>
>>> "P-384"
>>>
>>> NIST recommended curve P-384, also known as secp384r1.
>>>
>>> "P-521"
>>>
>>> NIST recommended curve P-521, also known as secp521r1.
>>>
>>>
>>>
>>> After that, I would suggest adding the sentence “Other NamedCurve values
>>> MAY also be defined by other specifications and used.”
>>>
>>>
>>>
>>> This is just Mark's proposal 3, and I've already explained the issues
>>> with this at such length that I'm losing the energy or desire to continue
>>> the discussion, because it's clear we're just circling in the same thing.
>>>
>>>
>>>
>>> Actually, what Mike said is an *example* of an extension mechanism,
>>> whereas option 3 doesn't imply a specific extension mechanism: that option
>>> was intended to cover all paths where we embed more extensibility into the
>>> base spec than we have today.
>>>
>>>
>>>
>>> Ryan - I hope your comment above applies to Mike's suggestion
>>> specifically and not to extension mechanisms generally.
>>>
>>>
>>>
>>> Anyway, despite the long discussions, it's not clear to me why Mike's
>>> proposal doesn't work. Developers really just need to know where they
>>> should expect changes / additions to appear in future so they can design
>>> code that is future-proof, to some extent. But we all know that trying to
>>> hard to be future-proof is a fools errand since none of us are too good at
>>> predicting the future.
>>>
>>>
>>>
>>> ...Mark
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>> Likewise, in the SHA description at
>>> https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#sha,
>>> after listing the current SHA algorithm names, I would add “Other names for
>>> additional SHA algorithms MAY be defined by other specifications and used.”
>>>
>>>
>>>
>>> Etc.
>>>
>>>
>>>
>>> This is really easy to do, editorially, and solves the extensibility
>>> problem.
>>>
>>>
>>>
>>> As an existence proof, the JOSE specs use this technique to good effect
>>> and are therefore extensible without requiring modifications to them.  In
>>> fact, the WebCrypto spec extends the JOSE specs in
>>> https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#iana-section-jws-jwa
>>> without modifying them.  Note that even if we don’t have registries, we can
>>> still enable new specs to extend the base spec without having to modify it.
>>>
>>>
>>>
>>> JOSE is not an API. As I've said repeatedly. How JOSE solves problems is
>>> great for JOSE, but neither responsible nor appropriate for API.
>>>
>>>
>>>
>>> I realize you don't think this is an API, and so we'll continue to have
>>> this conversation over and over, but it just wouldn't be a thread if I
>>> didn't say the exact same thing I've been saying for two and a half years
>>> now.
>>>
>>>
>>>
>>>
>>>
>>> I would ask everyone to consider this more flexible approach.  It lets
>>> us keep all the existing algorithms in the core spec, while being clear
>>> that new algorithms and parameters can be defined by other specs, as the
>>> need arises.
>>>
>>>
>>>
>>> This note is intended to provide a constructive, actionable way forward
>>> to enable extensibility and let us move on to addressing other issues to
>>> finish the spec.
>>>
>>>
>>>
>>>                                                                 Cheers,
>>>
>>>                                                                 -- Mike
>>>
>>>
>>>
>>> *From:* Mark Watson [mailto:watsonm@netflix.com]
>>> *Sent:* Thursday, August 28, 2014 12:53 PM
>>> *To:* Mike Jones
>>> *Cc:* GALINDO Virginie; Ryan Sleevi; public-webcrypto@w3.org
>>>
>>>
>>> *Subject:* Re: [W3C Web Crypto WG] about extensions to Web Crypto
>>> specification
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>> On Thu, Aug 28, 2014 at 12:37 PM, Mike Jones <
>>> Michael.Jones@microsoft.com> wrote:
>>>
>>> What I don't understand is this: If you know how to express algorithms
>>> in extension specs, then why not just express them exactly the same way in
>>> the main spec?  I don't see carving up the spec into little pieces as
>>> adding any value.
>>>
>>>
>>>
>>> ​The difference is that with separate specifications, it's reasonable to
>>> do future extensions by revising those specifications​. Our extensibility
>>> story would be that we have component specs that are easy to update.
>>>
>>>
>>>
>>> With a monolithic specification - and no extensibility mechanism - every
>>> extension involves a revision of the whole thing (or monkey-patching).
>>>
>>>
>>>
>>> So the other option is a monolithic specification with a good
>>> extensibility mechanism. We are close, IMO, as the ability to add whole new
>>> algorithms is a universal extensibility mechanism. It's just quite blunt in
>>> some cases: if you use that mechanism to, say, add a new hash algorithm to
>>> RSA-OAEP, you end up with RSA-OAEP-2 and Ryan, at least, objects to that.
>>>
>>>
>>>
>>> As I see it, there are three options:
>>>
>>> 1) Monolithic specification as is (Ryan, at least, does not like the
>>> RSA-OAEP-2 consequence)
>>>
>>> 2) Multiple distinct, easily revisable, algorithm specs (Mike, at least,
>>> does not like this)
>>>
>>> 3) Monolithic specification with fancier extension mechanism (Ryan, at
>>> least, does not like the proposals so far)
>>>
>>>
>>>
>>> ...Mark
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>   ------------------------------
>>>
>>> *From: *Mark Watson <watsonm@netflix.com>
>>> *Sent: *‎8/‎28/‎2014 12:28 PM
>>> *To: *GALINDO Virginie <Virginie.Galindo@gemalto.com>
>>> *Cc: *Mike Jones <Michael.Jones@microsoft.com>; Ryan Sleevi
>>> <sleevi@google.com>; public-webcrypto@w3.org
>>>
>>>
>>> *Subject: *Re: [W3C Web Crypto WG] about extensions to Web Crypto
>>> specification
>>>
>>> If it was going to unblock us on extensibility and EC then I could
>>> justify prioritizing work on that and have significant time to spend on it
>>> in the next week. I would expect it's largely a question of cloning the
>>> spec five times and then deleting all-but-the-bit-we-want from each one,
>>> adding some common bollerplate and pruning the references.
>>>
>>>
>>>
>>> ...Mark
>>>
>>>
>>>
>>> On Thu, Aug 28, 2014 at 12:03 PM, GALINDO Virginie <
>>> Virginie.Galindo@gemalto.com> wrote:
>>>
>>> Ryan,  Mark,
>>>
>>> what would be the realistic delay for you as editors to actually execute that split?
>>>
>>> Virginie
>>>
>>>
>>>
>>> ---- Ryan Sleevi a écrit ----
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>> On Thu, Aug 28, 2014 at 11:19 AM, Mike Jones <
>>> Michael.Jones@microsoft.com> wrote:
>>>
>>> You wrote “Perhaps this is the solution: pull out *all the algorithms*
>>> into, say, five extension specifications:
>>>
>>> - RSA
>>>
>>> - AES
>>>
>>> - EC
>>>
>>> - Hash algorithms
>>>
>>> - Key Derivation
>>>
>>> ”
>>>
>>>
>>>
>>> That would just make things needlessly harder on developers.  As a
>>> working group, we owe it to developers to make the core spec as easy to use
>>> as possible, while still enabling extension in a timely manner.  Yes,
>>> obtaining consensus in the working group may be painful, but that’s not an
>>> excuse for us to inflict enduring pain on developers using our specs as a
>>> result.
>>>
>>>
>>>
>>> I strongly oppose removing any of the existing algorithms from the core
>>> spec.
>>>
>>>
>>>
>>>                                                                 -- Mike
>>>
>>>
>>>
>>>
>>>
>>> Mike,
>>>
>>>
>>>
>>> The above proposal is entirely reasonable, and reflects the approach
>>> other WGs have done, whether it be for treating elements like CSS, treating
>>> features of the Web such as Service Workers, DOM events, gamepads, or File
>>> access, or in handling elements like WebGL.
>>>
>>>
>>>
>>> Despite your concerns, developers have not only succeeded, they've
>>> thrived AND benefitted from clear and digestable specifications, compared
>>> to the 'traditional' hundreds-of-pages-of-boilerplate.
>>>
>>>
>>>
>>> I would again encourage you to reconsider your position, and also
>>> helpfully clarify whether this is a personal concern or if you have
>>> discussed it within the broader space of your colleagues at Microsoft
>>> (including the IE team), so that we can be clearer both what the concerns
>>> are, and how to solve it.
>>>
>>>
>>>
>>> You can see that Mark and I are both trying to expend significant energy
>>> to find solutions to deal with real and ongoing problems that this WG is
>>> facing. It would be helpful for dialog if you would further explain your
>>> objections and, when possible, provide alternatives you feel meet these
>>> concerns.
>>>
>>>
>>>
>>> I, again, remind you that these specifications, as with the
>>> specifications for things like HTML or XMLHttpRequest, do not and have not
>>> targetted developers. They target, primarily, implementors, to ensure that
>>> implementors can correctly create interoperable implementations. The W3C
>>> has a venue for Developer-facing documentation and guidance, and it's not
>>> the specification.
>>>
>>>
>>>
>>> Thus, your first and foremost objective when evaluating the
>>> specification is not, should not, and cannot be "Is this hard for
>>> developers to understand", but "Is this easy for implementors to understand
>>> and reach interoperable implementations"
>>>
>>>
>>>
>>> To that end, Mark's proposal, which I've said for some time, absolutely
>>> gives greater ability and flexibility to do just that.
>>>      ------------------------------
>>>
>>>
>>>
>>> *This message and any attachments are intended solely for the addressees
>>> and may contain confidential information. Any unauthorized use or
>>> disclosure, either whole or partial, is prohibited. E-mails are susceptible
>>> to alteration. Our company shall not be liable for the message if altered,
>>> changed or falsified. If you are not the intended recipient of this
>>> message, please delete it and notify the sender. Although all reasonable
>>> efforts have been made to keep this transmission free from viruses, the
>>> sender will not be liable for damages caused by a transmitted virus.*
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>  ------------------------------
>>>
>>>
>>>
>>> *This message and any attachments are intended solely for the addressees
>>> and may contain confidential information. Any unauthorized use or
>>> disclosure, either whole or partial, is prohibited. E-mails are susceptible
>>> to alteration. Our company shall not be liable for the message if altered,
>>> changed or falsified. If you are not the intended recipient of this
>>> message, please delete it and notify the sender. Although all reasonable
>>> efforts have been made to keep this transmission free from viruses, the
>>> sender will not be liable for damages caused by a transmitted virus.*
>>>
>>
>>
>