Skip to content

README.md

Latest commit

 

History

History
121 lines (95 loc) · 6.59 KB

README.md

File metadata and controls

121 lines (95 loc) · 6.59 KB
Raw

hpke

Hybrid Public Key Encryption (HPKE) implementation for JavaScript runtimes.

Implements an authenticated encryption encapsulation format that combines a semi-static asymmetric key exchange with a symmetric cipher. This was originally defined in an Informational document on the IRTF stream as RFC 9180 and is now being republished as a Standards Track document of the IETF as draft-ietf-hpke-hpke.

HPKE provides a variant of public key encryption for arbitrary-sized plaintexts using a recipient public key.

Example

Getting started with CipherSuite

import * as HPKE from 'hpke'

// 1. Choose a cipher suite
const suite = new HPKE.CipherSuite(
  HPKE.KEM_DHKEM_P256_HKDF_SHA256,
  HPKE.KDF_HKDF_SHA256,
  HPKE.AEAD_AES_128_GCM,
)

// 2. Generate recipient key pair
const recipient = await suite.GenerateKeyPair()

// 3. Encrypt a message
const plaintext = new TextEncoder().encode('Hello, World!')
const { encapsulatedSecret, ciphertext } = await suite.Seal(recipient.publicKey, plaintext)

// 4. Decrypt the message
const decrypted = await suite.Open(recipient.privateKey, encapsulatedSecret, ciphertext)
console.log(new TextDecoder().decode(decrypted)) // "Hello, World!"

Core

Name Description
CipherSuite Hybrid Public Key Encryption (HPKE) suite combining a KEM, KDF, and AEAD.
RecipientContext Context for decrypting multiple messages and exporting secrets on the recipient side.
SenderContext Context for encrypting multiple messages and exporting secrets on the sender side.

KEM Algorithms

Variable Description
KEM_DHKEM_P256_HKDF_SHA256 Diffie-Hellman Key Encapsulation Mechanism using NIST P-256 curve and HKDF-SHA256.
KEM_DHKEM_P384_HKDF_SHA384 Diffie-Hellman Key Encapsulation Mechanism using NIST P-384 curve and HKDF-SHA384.
KEM_DHKEM_P521_HKDF_SHA512 Diffie-Hellman Key Encapsulation Mechanism using NIST P-521 curve and HKDF-SHA512.
KEM_DHKEM_X25519_HKDF_SHA256 Diffie-Hellman Key Encapsulation Mechanism using Curve25519 and HKDF-SHA256.
KEM_DHKEM_X448_HKDF_SHA512 Diffie-Hellman Key Encapsulation Mechanism using Curve448 and HKDF-SHA512.
KEM_ML_KEM_1024 Module-Lattice-Based Key Encapsulation Mechanism (ML-KEM-1024).
KEM_ML_KEM_512 Module-Lattice-Based Key Encapsulation Mechanism (ML-KEM-512).
KEM_ML_KEM_768 Module-Lattice-Based Key Encapsulation Mechanism (ML-KEM-768).
KEM_MLKEM1024_P384 Hybrid KEM combining ML-KEM-1024 with P-384 (MLKEM1024-P384).
KEM_MLKEM768_P256 Hybrid KEM combining ML-KEM-768 with P-256 (MLKEM768-P256).
KEM_MLKEM768_X25519 Hybrid KEM combining ML-KEM-768 with X25519 (MLKEM768-X25519).

KDF Algorithms

Variable Description
KDF_HKDF_SHA256 HKDF-SHA256 key derivation function.
KDF_HKDF_SHA384 HKDF-SHA384 key derivation function.
KDF_HKDF_SHA512 HKDF-SHA512 key derivation function.
KDF_SHAKE128 SHAKE128 key derivation function.
KDF_SHAKE256 SHAKE256 key derivation function.
KDF_TurboSHAKE128 TurboSHAKE128 key derivation function.
KDF_TurboSHAKE256 TurboSHAKE256 key derivation function.

AEAD Algorithms

Variable Description
AEAD_AES_128_GCM AES-128-GCM Authenticated Encryption with Associated Data (AEAD).
AEAD_AES_256_GCM AES-256-GCM Authenticated Encryption with Associated Data (AEAD).
AEAD_ChaCha20Poly1305 ChaCha20-Poly1305 Authenticated Encryption with Associated Data (AEAD).
AEAD_EXPORT_ONLY Export-only AEAD mode.

Interfaces

Interface Description
AEAD Authenticated Encryption with Associated Data (AEAD) implementation interface.
KDF Key Derivation Function (KDF) implementation interface.
KEM Key Encapsulation Mechanism (KEM) implementation interface.
Key A minimal key representation interface.
KeyPair Represents a cryptographic key pair consisting of a public key and private key.

Type Aliases

Type Alias Description
AEADFactory Factory function that returns an AEAD implementation.
CryptoKey A Web Cryptography key as declared by the host runtime.
KDFFactory Factory function that returns a KDF implementation.
KEMFactory Factory function that returns a KEM implementation.
Mode Mode supported by this implementation.

Utilities

Function Description
concat Concatenates multiple Uint8Array buffers into a single Uint8Array. It's exported for use in custom KEM, KDF, or AEAD implementations.
encode Encodes an ASCII string into a Uint8Array.
I2OSP Integer to Octet String Primitive (I2OSP) as defined in RFC 8017. Converts a non-negative integer into a byte string of specified length. It's exported for use in custom KEM, KDF, or AEAD implementations.
LabeledDerive Performs labeled key derivation for one-stage KDFs.
LabeledExpand Performs labeled expansion for two-stage KDFs.
LabeledExtract Performs labeled extraction for two-stage KDFs.

Variables

Variable Description
MODE_BASE Mode identifier for Base mode (0x00).
MODE_PSK Mode identifier for PSK mode (0x01).