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:
Returns:

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

Return type:

bytes

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

Decrypt a message using HPKE.

Parameters:
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.

enc_length()

Added in version 49.0.0.

Returns:

The length in bytes of the encapsulated key (enc) produced by this KEM. The enc is the prefix of the value returned by Suite.encrypt(), so this can be used to split the result into enc and the AEAD ciphertext:

ciphertext = suite.encrypt(plaintext, public_key)
enc_len = KEM.X25519.enc_length()
enc, ct = ciphertext[:enc_len], ciphertext[enc_len:]

Return type:

int

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