web3-social / hpke-framework

a plugable hpke framework monorepo

HKPE Framework

HPKE stands for Hybrid Public Key Encryption.

Warning

This project is experimental and all APIs are not stable.

DO NOT use in production.

Suggestions

If you are going to use standard HPKE components, check hpke-js instead.

See Standard HPKE Components Identifiers to check if standard components are enough for you.

Backgrounds

A HPKE cipher suite is a combination of:

• Key Derivation Function (HKDF)
• Key Encapsulation Mechanism (KEM)
• AEAD encryption algorithm

The framework provides abstraction for all subcomponents:

• KdfContext for general KDF
• KemContext for general KEM
  • DhKemContext for DH-Based KEM
• AeadContext for general AEAD algorithm

To create a HPKE cipher suite, just pass a valid combination:

new CipherSuite({
    kem: new YourKemImplementation(),
    kdfFactory: YourKdfFactory,
    aead: new YourAeadImplementation(),
}),

Existing Implementations

Standard

KDF-ID	KDF	Package
0x0001	HKDF-SHA256	@web3-social/hpke-hkdf
0x0002	HKDF-SHA384	@web3-social/hpke-hkdf
0x0003	HKDF-SHA512	@web3-social/hpke-hkdf

AEAD-ID	AEAD	Package
0x0001	AES-128-GCM	@web3-social/hpke-aes-gcm
0x0002	AES-256-GCM	@web3-social/hpke-aes-gcm

Non-standard / Experimental

Notice: The ids are chosen arbitrarily, but implementations that use the same algorithm should use the same ids to ensure compatibility

KDF-ID	KDF	Package
0xffff	HKDF-BLAKE3	@web3-social/hpke-hkdf-blake3

KEM-ID	KEM	Package
0x6b31	DHKEM(secp256k1, HKDF-BLAKE3)	@web3-social/hpke-secp256k1-blake3
0x6b32	DHKEM(secp256k1, HKDF-SHA-256)	@web3-social/hpke-secp256k1-sha256

Broken

AEAD-ID	AEAD	Package
0x0003	ChaCha20Poly1305	@web3-social/hpke-chacha20poly1305

Standard HPKE Components Identifiers

KDF

Value	KDF	Nh	Reference
0x0000	Reserved	N/A	RFC 9180
0x0001	HKDF-SHA256	32	[RFC5869]
0x0002	HKDF-SHA384	48	[RFC5869]
0x0003	HKDF-SHA512	64	[RFC5869]

KEM

Value	KEM	Nsecret	Nenc	Npk	Nsk	Auth	Reference
0x0000	Reserved	N/A	N/A	N/A	N/A	yes	RFC 9180
0x0010	DHKEM(P-256, HKDF-SHA256)	32	65	65	32	yes	[NISTCurves], [RFC5869]
0x0011	DHKEM(P-384, HKDF-SHA384)	48	97	97	48	yes	[NISTCurves], [RFC5869]
0x0012	DHKEM(P-521, HKDF-SHA512)	64	133	133	66	yes	[NISTCurves], [RFC5869]
0x0020	DHKEM(X25519, HKDF-SHA256)	32	32	32	32	yes	[RFC5869], [RFC7748]
0x0021	DHKEM(X448, HKDF-SHA512)	64	56	56	56	yes	[RFC5869], [RFC7748]

AEAD

Value	AEAD	Nk	Nn	Nt	Reference
0x0000	Reserved	N/A	N/A	N/A	RFC 9180
0x0001	AES-128-GCM	16	12	16	[GCM]
0x0002	AES-256-GCM	32	12	16	[GCM]
0x0003	ChaCha20Poly1305	32	12	16	[RFC8439]
0xFFFF	Export-only	N/A	N/A	N/A	[RFC9180]