WebCrypto roadmap

[lucacasonato]

Spec: https://w3c.github.io/webcrypto

This is the global tracking issue for WebCrypto API implementation.

See the status of the entire API surface:

• Enable non-extractable keys: Enable non-extractable keys for Web Crypto #11481
• SubtleCrypto.encrypt
  • RSA-OAEP
  • AES-CTR feat(ext/crypto) - support encrypt/decrypt with AES-CTR #13177
  • AES-CBC
  • AES-GCM
• SubtleCrypto.decrypt
  • RSA-OAEP
  • AES-CTR feat(ext/crypto) - support encrypt/decrypt with AES-CTR #13177
  • AES-CBC
  • AES-GCM
• SubtleCrypto.sign
  • RSASSA-PKCS1-v1_5
  • RSA-PSS (all hashes)
  • RSA-PSS (all hashes)
  • ECDSA
    • P256
    • P384
    • P521
  • HMAC
• SubtleCrypto.verify
  • RSASSA-PKCS1-v1_5
  • RSA-PSS (all hashes)
  • RSA-PSS (all hashes)
  • ECDSA
    • P256
    • P384
    • P521
  • HMAC
• SubtleCrypto.digest
  • SHA-1
  • SHA-256
  • SHA-384
  • SHA-512
• SubtleCrypto.generateKey
  • RSASSA-PKCS1-v1_5
  • RSA-PSS
  • RSA-PSS
  • RSA-OAEP
  • ECDSA
    • P256
    • P384
    • P521
  • ECDH feat(ext/crypto): generate ECDH keys #11870
    • P256
    • P384
    • P521
  • AES-CTR feat(ext/crypto): AES key generation #11869
  • AES-CBC feat(ext/crypto): AES key generation #11869
  • AES-GCM feat(ext/crypto): AES key generation #11869
  • AES-KW feat(ext/crypto): AES key generation #11869
  • HMAC
• SubtleCrypto.deriveKey
  • ECDH
  • HKDF
  • PBKDF2
• SubtleCrypto.deriveBits
  • ECDH
  • HKDF
  • PBKDF2
• SubtleCrypto.importKey
  • RSASSA-PKCS1-v1_5
    • spki
    • pkcs8
    • jwk
  • RSA-PSS
    • spki
    • pkcs8
    • jwk
  • RSA-OAEP
    • spki
    • pkcs8
    • jwk
  • ECDSA (missing p512 curve)
    • spki
    • pkcs8
    • jwk
    • raw
  • ECDH (missing p512 curve)
    • spki
    • pkcs8
    • jwk
    • raw
  • AES-CTR
    • jwk
    • raw
  • AES-CBC
    • jwk
    • raw
  • AES-GCM
    • jwk
    • raw
  • AES-KW
    • jwk
    • raw
  • HMAC
    • jwk
    • raw
  • HKDF
    • raw
  • PBKDF2
    • raw
• SubtleCrypto.exportKey
  • RSASSA-PKCS1-v1_5
    • spki
    • pkcs8
    • jwk
  • RSA-PSS
    • spki
    • pkcs8
    • jwk
  • RSA-OAEP
    • spki
    • pkcs8
    • jwk
  • ECDSA (missing p512 curve)
    • spki
    • pkcs8
    • jwk
    • raw
  • ECDH (missing p512 curve)
    • spki
    • pkcs8
    • jwk
    • raw
  • AES-CTR
    • raw
    • jwk
  • AES-CBC
    • raw
    • jwk
  • AES-GCM
    • raw
    • jwk
  • AES-KW
    • raw
    • jwk
  • HMAC
• SubtleCrypto.wrapKey
  • RSA-OAEP
  • AES-CTR
  • AES-CBC
  • AES-GCM
  • AES-KW
• SubtleCrypto.unwrapKey
  • RSA-OAEP
  • AES-CTR
  • AES-CBC
  • AES-GCM
  • AES-KW

[johnspurlock]

Please consider adding ED25519 to this list.

Cloudflare Workers recently added this non-yet-standard algorithm since it was requested so often by developers writing Discord integrations.

The operations they support are sign, verify, generateKey, exportKey, and importKey.

Support for this would be nice for folks wanting to write cross-worker-platform code with similar crypto support and performance characteristics.

[lucacasonato]

I will bring this up with the webcrypto working group at W3C. It seems like a logical addition. We won't act prior to standardization though.

[panva]

I applaud this overview. Thank you

[panva]

As far as urgency goes, given my wishful target of supporting JWS formatted JWTs first the most important missing piece is SubtleCrypto.importKey jwk, spki, and pkcs8 format support for RSASSA-PKCS1-v1_5, RSA-PSS, and ECDSA keys. Immediately followed by ECDSA verification, then encryption (AES-GCM, AES-CBC).

I would also like to note that importKey for HMAC is only partially complete as the jwk format is not supported yet, only raw.

[panva]

@littledivy I'm working on a deno-specific publish and build process for jose - that is pure TS export and autopublish to https://deno.land/x/jose.

While the implementation is incomplete it is not possible to use the package without --no-check due to the missing types.

Would it be possible to make it so that the WebCrypto interface would be complete and type-defined whilst the actual missing implementations simply throwing throw new DOMException("Not implemented", "NotSupportedError")?

It's global type interfaces such as HmacKeyAlgorithm, RsaKeyAlgorithm, EcKeyAlgorithm, RsaHashedImportParams, AesKeyGenParams completely missing as well as importKey being hardcoded to format "raw" at the moment rather than the KeyFormat enum that's making my universal bundled module not work when default type checking is enabled in deno.

In order for an implementation to be portable the types should follow lib.dom.d.ts from TS.

[littledivy]

@panva Yeah missing types can be annoying but I think that they should match reality. cc @lucacasonato

btw HmacKeyAlgorithm, RsaKeyAlgorithm and EcKeyAlgorithm should be fixed in #11738

also lib.dom.d.ts too has harcoded "raw" in importKey while KeyFormat is declared but not used in the decl

deno/cli/dts/lib.dom.d.ts

Line 15258 in 9105104

importKey(format: "raw" | "pkcs8" | "spki", keyData: Int8Array | Int16Array | Int32Array | Uint8Array | Uint16Array | Uint32Array | Uint8ClampedArray | Float32Array | Float64Array | DataView | ArrayBuffer, algorithm: AlgorithmIdentifier | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | DhImportKeyParams | AesKeyAlgorithm, extractable: boolean, keyUsages: KeyUsage[]): Promise<CryptoKey>;

[panva]

I would very much prefer the types to be complete to allow for portable implementations, that went out of their way to be fully built using TS and prepared to be consumed in Deno in through deno.land/x, to be used without having to instruct users to disable their precious type checking.

[panva]

ad importKey, that would appear to be a mistake on lib.dom.d.ts part, see https://www.w3.org/TR/WebCryptoAPI/#subtlecrypto-interface

it has little impact tho since they have an overload for each of the enum values.

[cryptographix]

@seanwykes let me know if you need a tester, as there's likely not much else I can help with when it comes to crypto, but I have at least have become a sponsor of the project 👍

@oles thanks for the offer, it'll be great if you can test #13013 - the PR includes JWK for EC and RSA - you can find the source branch here if you're ok with building deno, otherwise, let me know.

I've done some preliminary testing of RSA-PSS JWK and signed JWT using jose.

[panva]

@seanwykes @oles needs P-256 ECDSA to sign an ES256 JWT. I already know the sign/verify operations work fine in jose, its just the key material imports that are missing for JWS/JWT to kick in and be usable.

[cryptographix]

@seanwykes @oles needs P-256 ECDSA to sign an ES256 JWT. I already know the sign/verify operations work fine in jose, its just the key material imports that are missing for JWS/JWT to kick in and be usable.

So should be ready to go, the JWK key imports are already implemented in #13013.

[panva]

@seanwykes nice. In case you want to run the full suite of jose tests under Deno, this is how you might do that.

git clone --depth 1 --branch v4.3.7 https://github.com/panva/jose.git
cd jose
deno test --reload --jobs --allow-net --allow-read test-deno # replace deno with your local build

At the moment, with deno 1.16.4, the results look like this: test result: FAILED. 73 passed; 73 failed

[lucacasonato]

@lucacasonato the table is lacking SubtleCrypto.importKey breakdown by format value. It would appear importKey is almost done when that's not the case.

Updated :-)

[oles]

@panva success over at #13013 with both key import and signing!

Thank you for the pointers and the library, and thank you @seanwykes for your work on this - let me know if there's something more you'd like for me to test or help out with 👍

[lucacasonato]

@panva JOSE test suite on current main branch: test result: FAILED. 100 passed; 46 failed.

ECDSA & ECDH imports / exports are coming very soon.

[panva]

@lucacasonato I was checking that yesterday, great progress! much props to yourself, @seanwykes, @littledivy and anyone else participating in the effort.

I'd like to think the jose test suite is a good interoperability resource in addition to the web platform tests.

[littledivy]

~98.1% of the WebCrypto APIs are now part of Deno v1.18.0 🎉

Thank you to @seanwykes and everyone involved in this nearly 6 month long effort!
Let's open new issue trackers for pending features (like p512 curve and non 96 bit ivs). Closing :-)

[panva]

Let me join in the congratulations. @littledivy @seanwykes @lucacasonato thank you for these amazing efforts!

---

From a pending features perspective (JOSE completeness-wise) I'm looking at general P-521 support, P-384 ECDH. It'd be great to plan for Curve25519 and Curve448, either through adding this draft support or following Node.js and CF Workers in adding the NODE- prefixed versions until said draft is adopted as an official extension.

[cryptographix]

And here's my personal thank you to @littledivy, @lucacasonato and @bartlomieju for your patience and technical guidance for a Deno / Rust newbie. I've learnt a lot from you guys!

[diachedelic]

I have created an issue for P-521 support (#14766) and another for deriveBits which fails with P-384 key (#14765).