Various comments on the LC draft

A few of us at Microsoft read through the LC draft at http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/ and came up with the following comments. They are mostly editorial in nature, so I'm collecting them here in one place. I will go through bugzilla and file them over the next few days, but do feel free to let me know if any of these is controversial. Thanks!

(The following includes contributions by: Mike Jones, Brian LaMacchia, Anthony Nadalin, Israel Hilerio, John Simmons, Kilroy Hughes, and Karen Easterbrook.)

14.2. Data Types<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#subtlecrypto-interface-datatypes>
This says "jwk" "The key is represented as JSON according to the JSON Web Key format."  This will need to be reworded as part of Bug 24963<https://www.w3.org/Bugs/Public/show_bug.cgi?id=24963> to clarify the type of the returned object (whether ArrayBuffer or JWK).

14.3. Methods and Parameters<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#subtlecrypto-interface-methods>
In 14.3.1 through 14.3.12, we have statements like "If the name<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#dfn-Algorithm-name> member of normalizedAlgorithm does not identify a registered algorithm<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#algorithms> that supports the encrypt operation, then return an error<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#concept-return-an-error> named NotSupportedError<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#dfn-NotSupportedError>".  It seems possible that limited devices (such as embedded devices or implementations using hardware crypto modules) will not support the entire range of parameters or operations. Even with software implementations, not all parameter values will be supported - for example every RSA implementation in practice only supports a fixed set of key sizes. Therefore we believe these statements should be augmented in each occurrence to say something like: "If the name<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#dfn-Algorithm-name> member of normalizedAlgorithm does not identify a registered algorithm<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#algorithms> that supports the encrypt operation, or if the implementation does not support the encrypt operation with this algorithm using the specified parameters, then return an error<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#concept-return-an-error> named NotSupportedError<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#dfn-NotSupportedError>".

18.2. Recommended algorithms<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#recommended-algorithms>
Please add these algorithms:

*         RSASSA-PKCS1-v1_5 using SHA-256 (This is in the Recommended set for JOSE, and more secure than the SHA-1 variant in the spec.)

*         RSA-OAEP using SHA-1 and MGF1 with SHA-1 (This is the RFC 3447 default and the mostly widely deployed OAEP variant. It is also the variant used by JOSE)

18.8.7. ECDSA Operations<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#ecdsa-operations>
Section 18.8.4 specifies the valid values of NamedCurve, but curve-specific instructions are scattered through the Import Key and Export Key sections of Section 18.8.7. It seems better to collect curve-specific items in a table in Section 18.8.4, listing the DOMString value, the curve specification and the curve OID, and then to make the text describing the operations generic. This would allow for easy extensibility of the spec in the future and make the current version easier to read. For example, step 11 in the SPKI subsection of Import Key in Section 18.8.7 could say, "If params is equivalent to one of the object identifiers listed in Section 18.8.4, set the namedCurve attribute of algorithm to the corresponding DOMString value." Similar problems exist in 18.9.4. ECDH Operations<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#ecdh-operations>.

18.9.4. ECDH Operations<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#ecdh-operations>
As I've mentioned before, SP800-56A Section 5.7 prohibits exposing the DH / ECDH shared secret directly and instead requires that it be run through a KDF before being used. Many FIPS-validated implementations follow this restriction. Allowing the Derive Bits operation with DH or ECDH violates this prohibition.  We should recognize that at least some implementations will only expose deriveKey and not deriveBits with these algorithms, and make the latter optional.

20.1. Generate a signing key pair, sign some data<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#examples-signing>
Delete the comma from this example text:
hash: {
    name: "SHA-256",
  }

21.1. JSON Web Signature and Encryption Algorithms Registration<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#iana-section-jws-jwa>
The "HS1" algorithm could legally be used in a JWS object.  Therefore, change the "HS1" registration to read:

  *   Algorithm Name: "HS1"
  *   Algorithm Description: HMAC using SHA-1
  *   Algorithm Usage Location(s): "alg"
  *   JOSE Implementation Requirements: Deprecated
  *   Change Controller: W3C Web Cryptography Working Group
  *   Specification Document(s): [[ This Document ]]

The document failed to register the "RS1" algorithm identifier, which could legally be used in a JWS object.  Therefore, please add this registration:

  *   Algorithm Name: "RS1"
  *   Algorithm Description: RSASSA-PKCS-v1_5 using SHA-1
  *   Algorithm Usage Location(s): "alg"
  *   JOSE Implementation Requirements: Deprecated
  *   Change Controller: W3C Web Cryptography Working Group
  *   Specification Document(s): [[ This Document ]]

21.2. JSON Web Key Parameters Registry<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#iana-section-jwk>
Change word "Registry" to "Registration" in section title.

The registration is missing the required "Parameter Description" clause.  Please add this clause to the registration of "ext":

  *   Parameter Description: Extractable

23.1. Normative References<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#normative-references>
There are references throughout the spec to "ECMA262" and yet the reference in the References section is labelled "ECMAScript".  These names should be made consistent.

A.1. Algorithm mappings<http://www.w3.org/TR/2014/WD-WebCryptoAPI-20140325/#jwk-mapping-alg>
Add the curve names to the "EC" mappings.  For instance, this:
{ kty: "EC",
  alg: "ES256" }
should become this:
{ kty: "EC",
  crv: "P-256",
  alg: "ES256" }
(and do the same for P-384 and P-521).

Add this new mapping entry:
{ kty: "RSA",
  alg: "RSA-OAEP" }
to:
{ name: "RSA-OAEP",
  hash: {name: "SHA-1"}
}

Add this new mapping entry:
{ kty: "RSA",
  alg: "RS1" }
to:
{ name: " RSASSA-PKCS1-v1_5",
  hash: {name: "SHA-1"}
}

We would not suggest adding entries for RSA-PSS with SHA-1, ECDSA with SHA-1 or ECDSA where the curve is not aligned with the hash.