[W3C Web Crypto WG] - Comments on Draft API v21

Thanks to the editors for putting together the draft API document.

Here are some comments on the Draft API, I looked at version 21 from Aug 23rd. Some are editorial while other may require some discussion.

General, sample code:
It will be good if some sample source code can be included to help developers better understand the API. Perhaps we create an action item for this?

Section 4, Scope:
I suggest that an overview of the API and its capabilities could be included in the scope section.
Here is one suggestion :
"The Web Crypto API allows applications to generate keys with usual characteristics such as algorithm, usage, etc. However, some additional attributes can also be associated with keys, thereby allowing applications to do thing such as: indicate the origin(s) permitted to use the key (under definition); the rights for application to extract the key value; the key validity period; the duration of the key (is it temporary or does it exist across browser session). The API will also be offering the capabilities to query keys (under definition), to clone keys, to neuter keys, to import or expert keys. Those last features are under discussion in the Web Crypto Working Group."
I think this was also mentioned earlier in one of Virginie's mails to improve wording for defining in-scope and out-of-scope http://lists.w3.org/Archives/Public/public-webcrypto/2012Aug/0134.html

Section 5.1, security considerations:
This section has the following text in the third paragraph,

"Such mitigations may include restricting a generic key ("tainting") once it has been used with a specific algorithm or operation, and only permit applications to use that key with that same algorithm or operation in the future."

This mitigation suggestion is misleading. The reader may understand that the tainting could be made by the user agent. If it were the case, it would introduce fragmentation in application behavior. The tainting should be under the control of the application itself and should not fall in the scope of user agent initiative.

Suggestion : Move the sentence to 5.2 (security considerations for developers) section where it seems to be more relevant.

In section 5.2, security considerations:
This section talks about key security from a developer's perspective, but does not mention that key can be stored securely in a secure element such as a smart card. While developers have no guarantee that keys residing in local storage, or indexed DB are safe, secure element storage does offer this assurance. This scenario should be pointed out here.

Suggestion : raise an issue, so that correct working can be agreed on.

Section 6, privacy consideration:
In this section the definition of 'origin associated with a key' is missing.

Suggestion : Perhaps include an overview of the different characteristics of the API in the section 4 related to the scope. Also see the comment related to section 4 above.

Section 18, method naming:
This section defines the  crypto interface, some method names may be confusing to developers. For example, createEncryptor() returns a CryptoOperation object which is then used to actually do the encryption. This is logical. However, generateKey() actually returns a key generator object. The caller then invokes generate() on this object to actually generate the key. We need to review the method naming and make it consistent, e.g. perhaps calling this method createKeyGenerator().

Section 18.1.3, typo:
In this section the first hyperlink to CryptoOperation is broken. It is missing a # tag. [Just a note for the editors]

Section 18.1.6,  generateKey() method:
ISSUE-26 : About the origin definition, I think we should have an origin associated with a Key, which will be read only. In case multiple origins are associated with the Key, then specific key usage should be specified for each origin.

Section 18.1.10 , keys attribute:
It is not clear what granted access mean in the sentence : "The keys attribute provides access to the persistent key storage for a particular origin. Keys that have been generated by, imported into, or otherwise had access granted to a particular origin will be available via this attribute."

Does the granted access include the mutual authentication before accessing smart card content for example ?

Best regards,
--- asad