HPKE

[panva]

Could Hybrid Public Key Encryption (HPKE) [RFC9180] API design be included? Single-Shot for sure, possibly Multi-Shot too?

[twiss]

I think @davidben and @beurdouche were potentially interested in sketching something up for HPKE?

I'd be happy to host that in this spec if it makes sense, especially if it ends up being transferred to the WICG. Or it could also live in a separate spec, of course.

[beurdouche]

Yes, I still think HPKE would be a good addition to webcrypto... : )

[davidben]

HPKE would be a fine addition to the web platform. However, it would not be a good addition to the current WebCrypto API. WebCrypto was designed around condensing everything into a jumble of verbs, which has mostly lead to a very error-prone and dangerous API. (For example, WebCrypto thinks that HKDF and ECDH are both "derive" operations, even though they mean completely different things.) The asynchronicity also does not make much sense for CPU-bound operations.

In addition to just being a bad design, it doesn't fit HPKE in the first place, where you setup a context object, which can then be used for multiple en/decryption operations or an exporter. If we're doing HPKE, we should just design it as a more natural JavaScript API, and set a better pattern for cryptography APIs in the web platform. (From there, I think we should go back and re-expose other cryptographic primitives under the safer API and just abandon the old one.)

[beurdouche]

(From there, I think we should go back and re-expose other cryptographic primitives under the safer API and just abandon the old one.)

As we discussed in the past, I agree with that.

[twiss]

I think everybody would agree that HPKE shouldn't be added to the existing crypto.subtle.* functions. But the WebCrypto API is the entire crypto namespace, and (at least to me) it would make sense to add HPKE under crypto.hpke, for example. Then it doesn't need to share any of the design or anything else with SubtleCrypto.

Also, I agree with your criticisms of Web Crypto, but I don't think we should conflate adding HPKE and overhauling SubtleCrypto. In particular, I think it would be unfortunate if we end up in a situation where certain algorithms are only available via HPKE but not under SubtleCrypto (or an equivalently low-level API), because that would mean developers might reach for HPKE where really they just need ChaCha20-Poly1305 (for example).

In other words, we might still want to overhaul SubtleCrypto but that should be an entirely orthogonal discussion, IMHO (and even that can still be done within the confines of the WebCrypto API, pedantically speaking).

[panva]

@twiss are the decapsulateKey/Bits and encapsulateKey/Bits capable of supporting HPKE?

[twiss]

They could potentially be used as a building block for an implementation in JS. But if we want to include a native implementation, I still think it'd be better to create a high-level API under crypto.hpke, something modeled after section 5 and/or 6 of RFC9180.

[panva]

Having it in subtle (either own apis or part of encap/decap) would make its integration with supports simpler. Unless it would have its own.

[twiss]

I think it'll need its own algorithm suite support detection mechanism. For sure encap/decap are not sufficient for an HPKE API, HPKE does a lot more than that.

Btw, https://github.com/dajiaji/hpke-js is a thing that exists, perhaps its API could serve as inspiration if we want to add a native API.

And, in the meantime I think it would be a good intermediary step to implement the algorithms required/used by HPKE (that haven't been already), such that the JS implementation can become leaner.

[panva]

I've implemented both the revised HPKE (draft-ietf-hpke-hpke) and HPKE-PQ (draft-ietf-hpke-pq) using only base w3c/webcrypto and algorithms from WICG/webcrypto-modern-algos, see https://github.com/panva/hpke

The motivation for me was HPKE being included in the JOSE JWE suite. It is submitted to IESG for publication and the JOSE WG is now going to turn to define the code points for PQ and PQ/T Hybrid KEMs likely combined with SHAKE256 and AES-GCM or ChaCha20Poly1305

Algorithms and SubtleCrypto methods used

From w3c/webcrypto:

Algorithm	Methods
ECDH (P-256, P-384, P-521)	generateKey, importKey (jwk, raw), exportKey (raw), deriveBits
HMAC (SHA-256, SHA-384, SHA-512)	importKey, sign (used to implement HKDF1)
AES-GCM (128, 256)	importKey (raw), encrypt, decrypt
X25519	generateKey, importKey (pkcs8, raw), exportKey (raw), deriveBits

From Secure Curves (w3c/webcrypto#425):

Algorithm	Methods
X448	generateKey, importKey (pkcs8, raw), exportKey (raw), deriveBits

From WICG/webcrypto-modern-algos:

Algorithm	Methods
ML-KEM (5122, 768, 1024)	generateKey, importKey (raw-seed, raw-public), exportKey (raw-public), encapsulateBits, decapsulateBits
ChaCha20-Poly1305	importKey (raw-secret), encrypt, decrypt
cSHAKE128, cSHAKE256 (without customization = SHAKE)	digest (with variable outputLength)
SHA3-256	digest
-	getPublicKey

TurboSHAKE is the only algorithm gap for HPKE-PQ

HPKE-PQ's one-stage KDFs define TurboSHAKE128 and TurboSHAKE256 in addition to SHAKE128 and SHAK256. TurboSHAKE (PR #41) is currently the only algorithm not yet covered by webcrypto-modern-algos that is needed for a complete HPKE-PQ implementation.

getPublicKey is critical for DHKEM Decap with non-extractable keys

During DHKEM Decap, the recipient may provide only their private key (skR). The public key (pkR) is needed to construct the KEM context for the shared secret derivation. getPublicKey is the only efficient way to obtain the public key from a non-extractable private key. Without it, the private key must be as extractable just to export/re-import the public portion, that is not ideal and makes getPublicKey an important method to maybe push to w3c/webcrypto sooner.

Browser bugs

For HPKE-PQ Hybrid Key Derivation (MLKEM768-P256, MLKEM1024-P384), NIST curve private keys are derived from seeds. Importing a raw private scalar for NIST curves ideally uses PKCS#8 import (as it works for X25519/X448), but this is broken in:

• WebKit: https://bugs.webkit.org/show_bug.cgi?id=302707 cc @annevk
• Firefox: https://bugzilla.mozilla.org/show_bug.cgi?id=2000795 cc @Frosne

As a workaround, the implementation includes its own EC point scalar multiplication (d × G) to compute the public key coordinates (x, y) needed for JWK import. This is non-trivial, non-constant-time JS code that should not be necessary if PKCS#8 import for ECDH worked correctly across browsers.

That covers all HPKE and HPKE-PQ

==KEM==
DHKEM(P-256, HKDF-SHA256)
DHKEM(P-384, HKDF-SHA384)
DHKEM(P-521, HKDF-SHA512)
DHKEM(X25519, HKDF-SHA256)
DHKEM(X448, HKDF-SHA512)
MLKEM768-P256
MLKEM768-X25519
MLKEM1024-P384
ML-KEM-512
ML-KEM-768
ML-KEM-1024

==KDF==
HKDF-SHA256
HKDF-SHA384
HKDF-SHA512
SHAKE128
SHAKE256
TurboSHAKE128
TurboSHAKE256

==AEAD==
AES-128-GCM
AES-256-GCM
ChaCha20Poly1305

Footnotes

1. The built-in HKDF algorithm cannot be used because it only exposes a combined Extract-and-Expand operation via deriveBits/deriveKey. HPKE requires independent access to the Extract and Expand stages (e.g. LabeledExtract and LabeledExpand are called separately throughout the key schedule). The implementation therefore uses HMAC importKey + sign to implement HKDF-Extract and HKDF-Expand individually. ↩

2. Included in the interest of completeness. ↩

[twiss]

Thanks, looks great!

TurboSHAKE (PR #41) is currently the only algorithm not yet covered by webcrypto-modern-algos that is needed for a complete HPKE-PQ implementation.

IMO that's a strong argument for including TurboSHAKE.