rfc9180

Main package and high-level HPKE interface. Constants (KEMID, KDFID, AEADID) are documented in Constants.

hpke package: Hybrid Public Key Encryption (RFC 9180) primitives and APIs.

class rfc9180.HPKE(kem_id, kdf_id, aead_id)[source]

Bases: object

High-level HPKE interface exposing setup and single-shot helpers.

This class provides a convenient interface for Hybrid Public Key Encryption (HPKE) operations as specified in RFC 9180. It supports all HPKE modes: Base, PSK, Auth, and AuthPSK.

Parameters:

kem_id (KEMID) – The Key Encapsulation Mechanism identifier.
kdf_id (KDFID) – The Key Derivation Function identifier.
aead_id (AEADID) – The Authenticated Encryption with Associated Data identifier.

kem_id

The Key Encapsulation Mechanism identifier.

Type:: KEMID

kdf_id

The Key Derivation Function identifier.

Type:: KDFID

aead_id

The Authenticated Encryption with Associated Data identifier.

Type:: AEADID

kem

The KEM instance for key encapsulation/decapsulation.

Type:: KEMBase

kdf

The KDF instance for key derivation.

Type:: KDFBase

aead

The AEAD instance for encryption/decryption.

Type:: AEADBase

setup

The HPKE setup instance for context creation.

Type:: HPKESetup

Raises:: ValueError – If the KEM ID is unsupported.

__init__(kem_id, kdf_id, aead_id)[source]

generate_key_pair()[source]

Generate a new key pair for the configured KEM.

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

derive_key_pair(seed)[source]

Derive a key pair from a seed using the configured KEM.

Parameters:: seed (bytes) – Input key material (IKM) for key derivation.
Returns:: Tuple of (private_key, public_key) as Key Objects from the cryptography library.
Return type:: tuple
Raises:: ValueError – If seed is too short for the KEM requirements.

serialize_public_key(pk)[source]

Serialize a public key to bytes.

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

serialize_private_key(sk)[source]

Serialize a private key to bytes.

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

seal_base(pkR, info, aad, pt)[source]

Seal (encrypt) a message using Base mode.

Parameters:

pkR (bytes or Key Object) – Recipient’s public key.
info (bytes) – Application-supplied information.
aad (bytes) – Additional authenticated data.
pt (bytes) – Plaintext to encrypt.

Returns:

Tuple of (encapsulated key, ciphertext).

Return type:

tuple

open_base(enc, skR, info, aad, ct)[source]

Open (decrypt) a message using Base mode.

Parameters:

enc (bytes) – Encapsulated public key.
skR (bytes or Key Object) – Recipient’s private key.
info (bytes) – Application-supplied information.
aad (bytes) – Additional authenticated data.
ct (bytes) – Ciphertext to decrypt.

Returns:

Decrypted plaintext.

Return type:

bytes

Raises:

OpenError – If decryption fails.

seal_psk(pkR, info, aad, pt, psk, psk_id)[source]

Seal (encrypt) a message using PSK mode.

Parameters:

pkR (bytes or Key Object) – Recipient’s public key.
info (bytes) – Application-supplied information.
aad (bytes) – Additional authenticated data.
pt (bytes) – Plaintext to encrypt.
psk (bytes) – Pre-shared key (must have at least 32 bytes of entropy).
psk_id (bytes) – Pre-shared key identifier.

Returns:

Tuple of (encapsulated key, ciphertext).

Return type:

tuple

Raises:

ValueError – If PSK has insufficient entropy.

open_psk(enc, skR, info, aad, ct, psk, psk_id)[source]

Open (decrypt) a message using PSK mode.

Parameters:

enc (bytes) – Encapsulated public key.
skR (bytes or Key Object) – Recipient’s private key.
info (bytes) – Application-supplied information.
aad (bytes) – Additional authenticated data.
ct (bytes) – Ciphertext to decrypt.
psk (bytes) – Pre-shared key (must have at least 32 bytes of entropy).
psk_id (bytes) – Pre-shared key identifier.

Returns:

Decrypted plaintext.

Return type:

bytes

Raises:

ValueError – If PSK has insufficient entropy.
OpenError – If decryption fails.

seal_auth(pkR, info, aad, pt, skS)[source]

Seal (encrypt) a message using Auth mode.

Parameters:

pkR (bytes or Key Object) – Recipient’s public key.
info (bytes) – Application-supplied information.
aad (bytes) – Additional authenticated data.
pt (bytes) – Plaintext to encrypt.
skS (bytes or Key Object) – Sender’s private key.

Returns:

Tuple of (encapsulated key, ciphertext).

Return type:

tuple

open_auth(enc, skR, info, aad, ct, pkS)[source]

Open (decrypt) a message using Auth mode.

Parameters:

enc (bytes) – Encapsulated public key.
skR (bytes or Key Object) – Recipient’s private key.
info (bytes) – Application-supplied information.
aad (bytes) – Additional authenticated data.
ct (bytes) – Ciphertext to decrypt.
pkS (bytes or Key Object) – Sender’s public key.

Returns:

Decrypted plaintext.

Return type:

bytes

Raises:

OpenError – If decryption fails.

seal_auth_psk(pkR, info, aad, pt, psk, psk_id, skS)[source]

Seal (encrypt) a message using AuthPSK mode.

Parameters:

pkR (bytes or Key Object) – Recipient’s public key.
info (bytes) – Application-supplied information.
aad (bytes) – Additional authenticated data.
pt (bytes) – Plaintext to encrypt.
psk (bytes) – Pre-shared key (must have at least 32 bytes of entropy).
psk_id (bytes) – Pre-shared key identifier.
skS (bytes or Key Object) – Sender’s private key.

Returns:

Tuple of (encapsulated key, ciphertext).

Return type:

tuple

Raises:

ValueError – If PSK has insufficient entropy.

open_auth_psk(enc, skR, info, aad, ct, psk, psk_id, pkS)[source]

Open (decrypt) a message using AuthPSK mode.

Parameters:

enc (bytes) – Encapsulated public key.
skR (bytes or Key Object) – Recipient’s private key.
info (bytes) – Application-supplied information.
aad (bytes) – Additional authenticated data.
ct (bytes) – Ciphertext to decrypt.
psk (bytes) – Pre-shared key (must have at least 32 bytes of entropy).
psk_id (bytes) – Pre-shared key identifier.
pkS (bytes or Key Object) – Sender’s public key.

Returns:

Decrypted plaintext.

Return type:

bytes

Raises:

ValueError – If PSK has insufficient entropy.
OpenError – If decryption fails.

class rfc9180.KEMKey[source]

Bases: object

classmethod from_jwk(data)[source]

Return type:: KEMKeyInterface

classmethod from_pem(data)[source]

Return type:: KEMKeyInterface

classmethod from_pyca_cryptography_key(key)[source]

Return type:: KEMKeyInterface

class rfc9180.KEMKeyInterface(key)[source]

Bases: ABC

__init__(key)[source]

property raw: EllipticCurvePublicKey | X25519PublicKey | X448PublicKey | EllipticCurvePrivateKey | X25519PrivateKey | X448PrivateKey

abstractmethod to_private_bytes()[source]

Return type:: bytes

abstractmethod to_public_bytes()[source]

Return type:: bytes

rfc9180.create_hpke(kem_id=KEMID.DHKEM_X25519_HKDF_SHA256, kdf_id=KDFID.HKDF_SHA256, aead_id=AEADID.AES_128_GCM)[source]

Create an HPKE instance with default or specified algorithms.

Parameters:

kem_id (KEMID, optional) – Key Encapsulation Mechanism identifier. Defaults to DHKEM_X25519_HKDF_SHA256.
kdf_id (KDFID, optional) – Key Derivation Function identifier. Defaults to HKDF_SHA256.
aead_id (AEADID, optional) – Authenticated Encryption with Associated Data identifier. Defaults to AES_128_GCM.

Returns:

An HPKE instance configured with the specified algorithms.

Return type:

HPKE

Raises:

ValueError – If the KEM ID is unsupported.

rfc9180.append_header(enc, ct, kem_id, kdf_id, aead_id, mode)[source]

Encode an HPKE message with a self-describing header.

Parameters:

enc (bytes) – Encapsulated public key.
ct (bytes) – Ciphertext.
kem_id (int) – KEM algorithm identifier (2 bytes).
kdf_id (int) – KDF algorithm identifier (2 bytes).
aead_id (int) – AEAD algorithm identifier (2 bytes).
mode (int) – HPKE mode identifier (1 byte).

Returns:

Complete HPKE message with header.

Return type:

bytes

rfc9180.parse_header(msg, enc_len)[source]

Parse a self-describing HPKE message.

Parameters:

msg (bytes) – Complete HPKE message with header.
enc_len (int) – Length of the encapsulated public key (Nenc) for the specific KEM.

Returns:

Tuple of (kem_id, kdf_id, aead_id, mode, enc, ct).

Return type:

tuple

Raises:

ValueError – If message is too short or has invalid magic bytes.