Danger

This is a “Hazardous Materials” module. You should ONLY use it if you’re 100% absolutely sure that you know what you’re doing because this module is full of land mines, dragons, and dinosaurs with laser guns.

HPKE (Hybrid Public Key Encryption)

HPKE is a standard for public key encryption that combines a Key Encapsulation Mechanism (KEM), a Key Derivation Function (KDF), and an Authenticated Encryption with Associated Data (AEAD) scheme. It is defined in RFC 9180.

HPKE provides authenticated encryption: the recipient can be certain that the message was encrypted by someone who knows the recipient’s public key, but the sender is anonymous. Each call to Suite.encrypt() generates a fresh ephemeral key pair, so encrypting the same plaintext twice will produce different ciphertext.

The info parameter should be used to bind the encryption to a specific context (e.g., “MyApp-v1-UserMessages”). Per RFC 9180 Section 8.1, applications using single-shot APIs should use the info parameter for specifying auxiliary authenticated information.

from cryptography.hazmat.primitives.hpke import Suite, KEM, KDF, AEAD
from cryptography.hazmat.primitives.asymmetric import x25519

suite = Suite(KEM.X25519, KDF.HKDF_SHA256, AEAD.AES_128_GCM)

# Generate recipient key pair
private_key = x25519.X25519PrivateKey.generate()
public_key = private_key.public_key()

# Encrypt
ciphertext = suite.encrypt(b"secret message", public_key, info=b"app info")

# Decrypt
plaintext = suite.decrypt(ciphertext, private_key, info=b"app info")
class cryptography.hazmat.primitives.hpke.Suite(kem, kdf, aead)

An HPKE cipher suite combining a KEM, KDF, and AEAD.

Parameters:

  • kem (KEM) – The key encapsulation mechanism.

  • kdf (KDF) – The key derivation function.

  • aead (AEAD) – The authenticated encryption algorithm.

encrypt(plaintext, public_key, info=b'')

Encrypt a message using HPKE.

Parameters:

  • plaintext (bytes) – The message to encrypt.

  • public_key (X25519PublicKey) – The recipient’s public key.

  • info (bytes) – Application-specific context string for binding the encryption to a specific application or protocol.

Returns:

The encapsulated key concatenated with ciphertext (enc || ct).

Return type:

bytes

decrypt(ciphertext, private_key, info=b'')

Decrypt a message using HPKE.

Parameters:

  • ciphertext (bytes) – The enc || ct value from encrypt().

  • private_key (X25519PrivateKey) – The recipient’s private key.

  • info (bytes) – Application-specific context string (must match the value used during encryption).

Returns:

The decrypted plaintext.

Return type:

bytes

Raises:

cryptography.exceptions.InvalidTag – If decryption fails.

class cryptography.hazmat.primitives.hpke.KEM

An enumeration of key encapsulation mechanisms.

X25519

DHKEM(X25519, HKDF-SHA256)

P256

DHKEM(P-256, HKDF-SHA256)

P384

DHKEM(P-384, HKDF-SHA384)

P521

DHKEM(P-521, HKDF-SHA512)

MLKEM768

ML-KEM-768. Post-quantum secure. Only available on backends that support ML-KEM.

MLKEM1024

ML-KEM-1024. Post-quantum secure. Only available on backends that support ML-KEM.

MLKEM768_X25519

A hybrid KEM combining ML-KEM-768 with X25519 (also known as X-Wing). Post-quantum secure. Only available on backends that support ML-KEM. Public and private keys are MLKEM768X25519PublicKey and MLKEM768X25519PrivateKey.

MLKEM1024_P384

A hybrid KEM combining ML-KEM-1024 with P-384. Post-quantum secure. Only available on backends that support ML-KEM. Public and private keys are MLKEM1024P384PublicKey and MLKEM1024P384PrivateKey.

class cryptography.hazmat.primitives.hpke.MLKEM768X25519PrivateKey(mlkem_key, x25519_key)

Added in version 47.0.0.

A hybrid ML-KEM-768 / X25519 private key for use with KEM.MLKEM768_X25519. Combines an MLKEM768PrivateKey and an X25519PrivateKey into a single recipient key.

Parameters:
public_key()
Returns:

MLKEM768X25519PublicKey

class cryptography.hazmat.primitives.hpke.MLKEM768X25519PublicKey(mlkem_key, x25519_key)

Added in version 47.0.0.

A hybrid ML-KEM-768 / X25519 public key for use with KEM.MLKEM768_X25519. Combines an MLKEM768PublicKey and an X25519PublicKey into a single recipient key.

Parameters:
class cryptography.hazmat.primitives.hpke.MLKEM1024P384PrivateKey(mlkem_key, p384_key)

Added in version 47.0.0.

A hybrid ML-KEM-1024 / P-384 private key for use with KEM.MLKEM1024_P384. Combines an MLKEM1024PrivateKey and an EllipticCurvePrivateKey on the SECP384R1 curve into a single recipient key.

Parameters:
public_key()
Returns:

MLKEM1024P384PublicKey

class cryptography.hazmat.primitives.hpke.MLKEM1024P384PublicKey(mlkem_key, p384_key)

Added in version 47.0.0.

A hybrid ML-KEM-1024 / P-384 public key for use with KEM.MLKEM1024_P384. Combines an MLKEM1024PublicKey and an EllipticCurvePublicKey on the SECP384R1 curve into a single recipient key.

Parameters:
class cryptography.hazmat.primitives.hpke.KDF

An enumeration of key derivation functions.

HKDF_SHA256

HKDF-SHA256

HKDF_SHA384

HKDF-SHA384

HKDF_SHA512

HKDF-SHA512

SHAKE128

SHAKE-128

SHAKE256

SHAKE-256

class cryptography.hazmat.primitives.hpke.AEAD

An enumeration of authenticated encryption algorithms.

AES_128_GCM

AES-128-GCM

AES_256_GCM

AES-256-GCM

CHACHA20_POLY1305

ChaCha20Poly1305