Primitives

KEM, KDF, and AEAD primitives used by HPKE.

KEM (Key Encapsulation Mechanism)

class rfc9180.primitives.kem.KEMBase(kem_id)[source]

Bases: ABC

Base class for DHKEM implementations.

Provides Diffie-Hellman-based Key Encapsulation Mechanism operations as specified in RFC 9180 §7.1.

Parameters:: kem_id (KEMID) – KEM algorithm identifier.

kem_id

KEM algorithm identifier.

Type:: KEMID

kdf

Internal KDF instance for the KEM.

Type:: KDFBase

Nsecret

Shared secret length in bytes.

Type:: int

Nenc

Encapsulated key length in bytes.

Type:: int

Npk

Public key length in bytes.

Type:: int

Nsk

Private key length in bytes.

Type:: int

Ndh

DH shared secret length in bytes.

Type:: int

suite_id

KEM suite identifier.

Type:: bytes

__init__(kem_id)[source]

abstractmethod generate_key_pair()[source]

Generate a new key pair.

Returns:: Tuple of (private_key, public_key) as Key Objects.
Return type:: tuple

abstractmethod derive_key_pair(ikm)[source]

Derive a key pair from input key material.

Parameters:

ikm (bytes) – Input key material.

Returns:

Tuple of (private_key, public_key) as Key Objects.

Return type:

tuple

Raises:

ValueError – If IKM is too short.
DeriveKeyPairError – If derivation fails (e.g., rejection sampling exceeded).

abstractmethod serialize_public_key(pk)[source]

Serialize a public key to bytes.

Parameters:: pk (Key Object) – Public key.
Returns:: Serialized public key.
Return type:: bytes

abstractmethod deserialize_public_key(pkm)[source]

Deserialize a public key from bytes.

Parameters:: pkm (bytes) – Serialized public key.
Returns:: Public key.
Return type:: Key Object
Raises:: DeserializeError – If deserialization fails.

abstractmethod serialize_private_key(sk)[source]

Serialize a private key to bytes.

Parameters:: sk (Key Object) – Private key.
Returns:: Serialized private key.
Return type:: bytes

abstractmethod deserialize_private_key(skm)[source]

Deserialize a private key from bytes.

Parameters:: skm (bytes) – Serialized private key.
Returns:: Private key.
Return type:: Key Object
Raises:: DeserializeError – If deserialization fails.

abstractmethod dh(sk, pk)[source]

Perform Diffie-Hellman key exchange.

Parameters:

sk (Key Object) – Private key.
pk (Key Object) – Public key.

Returns:

Shared secret.

Return type:

bytes

Raises:

ValidationError – If DH operation fails or output is invalid.

extract_and_expand(dh_value, kem_context)[source]

RFC 9180 §4.1 - ExtractAndExpand.

Parameters:

dh_value (bytes) – Diffie-Hellman shared secret.
kem_context (bytes) – KEM context.

Returns:

Shared secret (Nsecret bytes).

Return type:

bytes

encap(pkR)[source]

Base/PSK encapsulation.

Parameters:: pkR (Key Object) – Recipient’s public key.
Returns:: Tuple of (shared_secret, encapsulated_key).
Return type:: tuple
Raises:: EncapError – If encapsulation fails.

decap(enc, skR)[source]

Base/PSK decapsulation.

Parameters:

enc (bytes) – Encapsulated public key.
skR (Key Object) – Recipient’s private key.

Returns:

Shared secret.

Return type:

bytes

Raises:

DecapError – If decapsulation fails.

auth_encap(pkR, skS)[source]

Authenticated encapsulation (Auth/AuthPSK).

Parameters:

pkR (Key Object) – Recipient’s public key.
skS (Key Object) – Sender’s private key.

Returns:

Tuple of (shared_secret, encapsulated_key).

Return type:

tuple

Raises:

EncapError – If encapsulation fails.

auth_decap(enc, skR, pkS)[source]

Authenticated decapsulation (Auth/AuthPSK).

Parameters:

enc (bytes) – Encapsulated public key.
skR (Key Object) – Recipient’s private key.
pkS (Key Object) – Sender’s public key.

Returns:

Shared secret.

Return type:

bytes

Raises:

DecapError – If decapsulation fails.

class rfc9180.primitives.kem.DHKEM_X25519[source]

Bases: KEMBase

DHKEM with X25519 and HKDF-SHA256.

Implements DHKEM using the X25519 elliptic curve Diffie-Hellman function and HKDF-SHA256 for key derivation.

__init__()[source]

generate_key_pair()[source]

Generate a new X25519 key pair.

Returns:: Tuple of (X25519PrivateKey, X25519PublicKey).
Return type:: tuple

derive_key_pair(ikm)[source]

RFC 9180 §7.1.3 - DeriveKeyPair for X25519.

Parameters:: ikm (bytes) – Input key material (must be at least Nsk bytes).
Returns:: Tuple of (X25519PrivateKey, X25519PublicKey).
Return type:: tuple
Raises:: ValueError – If IKM is too short.

serialize_public_key(pk)[source]

Serialize a public key to bytes.

Parameters:: pk (Key Object) – Public key.
Returns:: Serialized public key.
Return type:: bytes

deserialize_public_key(pkm)[source]

Deserialize a public key from bytes.

Parameters:: pkm (bytes) – Serialized public key.
Returns:: Public key.
Return type:: Key Object
Raises:: DeserializeError – If deserialization fails.

serialize_private_key(sk)[source]

Serialize a private key to bytes.

Parameters:: sk (Key Object) – Private key.
Returns:: Serialized private key.
Return type:: bytes

deserialize_private_key(skm)[source]

Deserialize a private key from bytes.

Parameters:: skm (bytes) – Serialized private key.
Returns:: Private key.
Return type:: Key Object
Raises:: DeserializeError – If deserialization fails.

dh(sk, pk)[source]

Perform Diffie-Hellman key exchange.

Parameters:

sk (Key Object) – Private key.
pk (Key Object) – Public key.

Returns:

Shared secret.

Return type:

bytes

Raises:

ValidationError – If DH operation fails or output is invalid.

class rfc9180.primitives.kem.DHKEM_X448[source]

Bases: KEMBase

DHKEM with X448 and HKDF-SHA512.

Implements DHKEM using the X448 elliptic curve Diffie-Hellman function and HKDF-SHA512 for key derivation.

__init__()[source]

generate_key_pair()[source]

Generate a new key pair.

Returns:: Tuple of (private_key, public_key) as Key Objects.
Return type:: tuple

derive_key_pair(ikm)[source]

Derive a key pair from input key material.

Parameters:

ikm (bytes) – Input key material.

Returns:

Tuple of (private_key, public_key) as Key Objects.

Return type:

tuple

Raises:

ValueError – If IKM is too short.
DeriveKeyPairError – If derivation fails (e.g., rejection sampling exceeded).

serialize_public_key(pk)[source]

Serialize a public key to bytes.

Parameters:: pk (Key Object) – Public key.
Returns:: Serialized public key.
Return type:: bytes

deserialize_public_key(pkm)[source]

Deserialize a public key from bytes.

Parameters:: pkm (bytes) – Serialized public key.
Returns:: Public key.
Return type:: Key Object
Raises:: DeserializeError – If deserialization fails.

serialize_private_key(sk)[source]

Serialize a private key to bytes.

Parameters:: sk (Key Object) – Private key.
Returns:: Serialized private key.
Return type:: bytes

deserialize_private_key(skm)[source]

Deserialize a private key from bytes.

Parameters:: skm (bytes) – Serialized private key.
Returns:: Private key.
Return type:: Key Object
Raises:: DeserializeError – If deserialization fails.

dh(sk, pk)[source]

Perform Diffie-Hellman key exchange.

Parameters:

sk (Key Object) – Private key.
pk (Key Object) – Public key.

Returns:

Shared secret.

Return type:

bytes

Raises:

ValidationError – If DH operation fails or output is invalid.

class rfc9180.primitives.kem.DHKEM_NIST(kem_id, curve, order, mask=255)[source]

Bases: KEMBase

Base for NIST P-curves (P-256, P-384, P-521).

Implements DHKEM using NIST elliptic curves with ECDH and rejection sampling for key derivation.

Parameters:

kem_id (KEMID) – KEM algorithm identifier.
curve (EllipticCurve) – Elliptic curve instance.
order (int) – Curve order for rejection sampling.

__init__(kem_id, curve, order, mask=255)[source]

generate_key_pair()[source]

Generate a new key pair.

Returns:: Tuple of (private_key, public_key) as Key Objects.
Return type:: tuple

derive_key_pair(ikm)[source]

Derive a key pair from input key material.

Parameters:

ikm (bytes) – Input key material.

Returns:

Tuple of (private_key, public_key) as Key Objects.

Return type:

tuple

Raises:

ValueError – If IKM is too short.
DeriveKeyPairError – If derivation fails (e.g., rejection sampling exceeded).

serialize_public_key(pk)[source]

Serialize a public key to bytes.

Parameters:: pk (Key Object) – Public key.
Returns:: Serialized public key.
Return type:: bytes

deserialize_public_key(pkm)[source]

Deserialize a public key from bytes.

Parameters:: pkm (bytes) – Serialized public key.
Returns:: Public key.
Return type:: Key Object
Raises:: DeserializeError – If deserialization fails.

serialize_private_key(sk)[source]

Serialize a private key to bytes.

Parameters:: sk (Key Object) – Private key.
Returns:: Serialized private key.
Return type:: bytes

deserialize_private_key(skm)[source]

Deserialize a private key from bytes.

Parameters:: skm (bytes) – Serialized private key.
Returns:: Private key.
Return type:: Key Object
Raises:: DeserializeError – If deserialization fails.

dh(sk, pk)[source]

Perform Diffie-Hellman key exchange.

Parameters:

sk (Key Object) – Private key.
pk (Key Object) – Public key.

Returns:

Shared secret.

Return type:

bytes

Raises:

ValidationError – If DH operation fails or output is invalid.

class rfc9180.primitives.kem.DHKEM_P256[source]

Bases: DHKEM_NIST

DHKEM with P-256 and HKDF-SHA256.

Implements DHKEM using the NIST P-256 curve (secp256r1) and HKDF-SHA256 for key derivation.

__init__()[source]

class rfc9180.primitives.kem.DHKEM_P384[source]

Bases: DHKEM_NIST

DHKEM with P-384 and HKDF-SHA384.

Implements DHKEM using the NIST P-384 curve (secp384r1) and HKDF-SHA384 for key derivation.

__init__()[source]

class rfc9180.primitives.kem.DHKEM_P521[source]

Bases: DHKEM_NIST

DHKEM with P-521 and HKDF-SHA512.

Implements DHKEM using the NIST P-521 curve (secp521r1) and HKDF-SHA512 for key derivation.

__init__()[source]

KDF (Key Derivation Function)

class rfc9180.primitives.kdf.KDFBase(kdf_id)[source]

Bases: object

Base class for KDF implementations (HKDF variants).

Provides key derivation functions based on HKDF (RFC 5869) with HPKE-specific labeled operations (RFC 9180 §4).

Parameters:: kdf_id (KDFID) – KDF algorithm identifier.

kdf_id

KDF algorithm identifier.

Type:: KDFID

Nh

Hash output length in bytes.

Type:: int

hash_algorithm: Hash algorithm instance.

__init__(kdf_id)[source]

extract(salt, ikm)[source]

HKDF-Extract (RFC 5869).

Parameters:

salt (bytes) – Salt value (empty salt is replaced with zero bytes).
ikm (bytes) – Input key material.

Returns:

Pseudorandom key (PRK).

Return type:

bytes

expand(prk, info, L)[source]

HKDF-Expand (RFC 5869).

Parameters:

prk (bytes) – Pseudorandom key.
info (bytes) – Application-specific information.
L (int) – Desired output length in bytes.

Returns:

Output keying material.

Return type:

bytes

Raises:

ValueError – If requested length exceeds maximum (255 * Nh).

labeled_extract(salt, label, ikm, suite_id)[source]

LabeledExtract from RFC 9180 §4.

Parameters:

salt (bytes) – Salt value.
label (str) – Label string.
ikm (bytes) – Input key material.
suite_id (bytes) – HPKE suite identifier.

Returns:

Pseudorandom key (PRK).

Return type:

bytes

labeled_expand(prk, label, info, L, suite_id)[source]

LabeledExpand from RFC 9180 §4.

Parameters:

prk (bytes) – Pseudorandom key.
label (str) – Label string.
info (bytes) – Application-specific information.
L (int) – Desired output length in bytes.
suite_id (bytes) – HPKE suite identifier.

Returns:

Output keying material.

Return type:

bytes

Raises:

ValueError – If requested length exceeds maximum (255 * Nh).

AEAD

class rfc9180.primitives.aead.AEADBase(aead_id)[source]

Bases: object

Base class for AEAD wrappers.

Provides authenticated encryption with associated data (AEAD) operations for HPKE. Supports AES-GCM and ChaCha20-Poly1305.

Parameters:: aead_id (AEADID) – AEAD algorithm identifier.

aead_id

AEAD algorithm identifier.

Type:: AEADID

Nk

Key length in bytes.

Type:: int

Nn

Nonce length in bytes.

Type:: int

Nt

Tag length in bytes.

Type:: int

cipher

Cipher factory function.

Type:: callable or None

max_seq

Maximum sequence number before overflow.

Type:: int

__init__(aead_id)[source]

seal(key, nonce, aad, pt)[source]

Seal (encrypt and authenticate) a message.

Parameters:

key (bytes) – Encryption key (must be Nk bytes).
nonce (bytes) – Nonce (must be Nn bytes).
aad (bytes) – Additional authenticated data.
pt (bytes) – Plaintext to encrypt.

Returns:

Ciphertext (includes authentication tag).

Return type:

bytes

Raises:

ValueError – If AEAD is EXPORT_ONLY, or if key/nonce lengths are invalid.
MessageLimitReachedError – If nonce reuse or limits exceeded.

open(key, nonce, aad, ct)[source]

Open (decrypt and verify) a message.

Parameters:

key (bytes) – Encryption key (must be Nk bytes).
nonce (bytes) – Nonce (must be Nn bytes).
aad (bytes) – Additional authenticated data.
ct (bytes) – Ciphertext to decrypt (includes authentication tag).

Returns:

Decrypted plaintext.

Return type:

bytes

Raises:

ValueError – If AEAD is EXPORT_ONLY, or if key/nonce lengths are invalid.
OpenError – If decryption or authentication fails.