Re: Editorial comments on Web Crypto API

On Mon, Aug 27, 2012 at 10:52 AM, Harry Halpin <hhalpin@w3.org> wrote:
> Just a quick review of the spec, but I agree its mature enough to go forward
> as a WG if the editors can check-in descriptions of the latest issues.
>
> 1. Remove Arun as co-editor.

Done.

> 2. "web browsers to give any web page" -> "web browsers to give any web page
> and native Javascript environments* "

I'm not sure I follow, but the naive read suggests this is a great
broadening of scope/effort.

While we've got an issue to consider native JS environments, it's
equally fair to point out that a number of operational models
necessarily borrow from "web only" specifications (eg: HTML, DOM,
DOM4, etc). Such concepts can be mapped by native JS environments (eg:
node.js), but I'm concerned that now we'd be trying to design an API
for two very, very different platforms - even if they use the same
underlying script language.

Have I missed something?

> 3. My preference is not to give use-cases in this document, but put them in
> a separate WG note.

I don't think our Wiki document is the best way to reflect our
potential use cases for the broader public, in part because they
derive a lot of context from discussions, and in part because they're
full of a lot of caveats (this "MAY" be in scope, this "MAY NOT" be,
etc)

The goal of the Use Cases in this document is to provide very brief,
very high-level overview of possible uses, and the necessary
functionality that they need from the API.

I'm fine with splitting it out, but someone needs to own an ACTION to
create a document suitable for wide consumption that reflects the
"core" API functionality (eg: minimizes the focus on the rather broad
secondary features, so as not to distract or monopolize the
discussions) in an easily consumable manner.

I don't have the bandwidth to do that presently.

> 4. "this specification does not dictate a mandatory set of algorithms that
> must be implemented. " -> "this specification does not dictate a mandatory
> set of algorithms that must be implemented, *although for the case of
> interoperability a number of algorithms are recommended."

> 5. Instead of "TBD", say "Open Issue". I'd also actually maybe link not to
> the issue tracker, but put the *text* of the issue directly in the spec. The
> point of this FPWD release is to get the broader community to think about
> these issue and give us input, and I'm worried they will be too lazy to
> click those links.

I'm concerned about the readability of the spec at that point. There's
a lot of information, and I expect that a number of people will be
taking a high-level glance first, to see what is possible. This is
what we would desire from an FPWD, I believe, to make sure this WG
work product is on track and not falling into pitfalls experienced by
other implementations.

> 6. Do you want to say "Fire an event called complete." after " Fire an event
> called progress." in "processData(ArrayBufferView buffer)

I'm not sure where you saw this. Currently, I only see this text in
the documentation of "The complete() method"

> 7. We need some text/IDL under "deriveKey", "importKey", and "exportKey"

Agreed.

Received on Tuesday, 28 August 2012 20:01:24 UTC