wbamberg/web-crypto-docs-plan.md Secret

## web-crypto-docs-plan.md

      
    Raw
  

              web-crypto-docs-plan.md
            
          
    SubtleCrypto

Current scope


Web Crypto API main page
Crypto interface main page
SubtleCrypto interface main page
11 methods of SubtleCrypto (encrypt(), sign() etc.)
Supported algorithms guide
Checking authenticity with password guide (very incomplete draft)

Problems

From https://discourse.mozilla.org/t/webcrypto-api-badly-documented/31451:


It’s hard to understand, sometimes and misses information about intended usage/constraints/limitations/suggestions. E.g. the wrapKey method. It’s as it is intended in “unsecure environments”. So, what? It does not even mention taht it basically just encrypts the key, it does not mention whether and why you should/could not just use the encrypt() API (or could you?), and so on and so forth…
The documentation is really minimal and that may easily lead to security problems.


It does not give any recommendations or warnings., It does not warn about problematic constructions/cipher modes. It does not state what values should be random etc. and so on… It’s just gives you the tools and you can shoot yourself in the foot.


But worst, it gives actually bad examples. E.g. the deriveKey one: It uses PBKDF2-SHA256 with 100 iterations! Seriously just 100 ones – you can literally just skip that key stretching. That’s just way too less 2.
It even adds a great and totally (not) useful comment there:
don’t get too ambitious, or at least remember that low-power phones will access your app


Seriously that’s bad advice.
Similarly, it often uses CBC mode or something like that instead of the usually recommend ones like GCM 2…

Looking at the docs this is generally well-warranted criticism. To flesh it out a bit, I'd add:


Methods often don't have a clear description of what they do, when you should use them and how they differ from other methods. The comment above a calls out wrapKey here but there are others. We should ensure all methods have a good overview section.


The algorithm parameter is complex in this API, and its documentation here is sometimes wrong, incomplete, or unclear. We should have a clear and consistent way to document all the 17 dictionary objects that are used for all the different algorithms and methods. This needs to include documentation of constraints that apply to these parameters (e.g. ranges they must fall within) and basic security considerations (e.g. don't reuse IVs).


Missing pages: CryptoKeyPair and deriveBits() are all the missing pages I found so far.


Some examples are missing completely, some won't work, some will work but enshrine poor security practices. We should ensure that all methods have examples (one example for each recommended algorithm), that they work and that they follow good security practices.


Incomplete overview pages:


The Web Crypto API main page is incomplete and not very helpful (it says things like "import and export, the ability to import a key or export a key"). It should be finished.


The Supported algorithms guide is incomplete. It should be revised and finished. It should also give some basic advice about algorithms that have known security issues.


The Checking authenticity with password guide is incomplete. We should either finish or delete it. Finishing it (and writing other guides on similar use cases) would expand the scope of this work quite a lot.


Security considerations: there's a lot of criticism of this API from the security community, in terms of (1) details (the spec including questionable algorithms), (2) lack of normative advice about how to use algorithms, and (3) the whole question of whether browser JS is a suitable space for doing crypto. I think it would be good for MDN docs to provide some guidance here, and write something about:

what kind of use cases the Web Crypto API is/is not suitable for and why
for suitable use cases, how the algorithms should be used in accordance with best current practices.


Security review: we should have a review from the security team of all this material. The exception I think is the previous item "Security considerations" - this I think should be written in collaboration with the security team: we should start with an outline of what to cover and revise drafts together.