API Reference

A Python implementation of HPKE. <https://pyhpke.readthedocs.io>

class pyhpke.AEADInterface

Bases: object

The AEAD (Authenticated Encapsulation with Additional Data) interface.

property id: AEADId

The AEAD identifier.

property key_size: int

The AEAD key size.

property nonce_size: int

The AEAD nonce size.

property tag_size: int

The AEAD tag size.

import_key(key: bytes) → AEADKeyInterface

Imports a byte string as an AEAD key.

class pyhpke.AEADKeyInterface

Bases: object

The AEAD key interface.

seal(pt: bytes, nonce: bytes, aad: bytes = b'') → bytes

Encrypts the specified message.

Parameters:

• pt (bytes) – A plain text to be encrypted.

• nonce (bytes) – A nonce for encryption.

• aad (bytes) – Additional authenticated data.

Returns:

The encrypted data.

Return type:

bytes

Raises:

• ValueError – Invalid arguments.

• SealError – Failed to encrypt the plain text.

open(ct: bytes, nonce: bytes, aad: bytes = b'') → bytes

Decrypts the specified message.

Parameters:

• ct (bytes) – A cipher text to be decrypted.

• nonce (bytes) – A nonce for encryption.

• aad (bytes) – Additional authenticated data.

Returns:

The decrypted data.

Return type:

bytes

Raises:

• ValueError – Invalid arguments.

• OpenError – Failed to decrypt the cipher text.

class pyhpke.CipherSuite(kem: KEMInterface, kdf: KDFInterface, aead: AEADInterface)

Bases: object

An HPKE cipher suite which consists of KEM, KDF and AEAD.

classmethod new(kem_id: KEMId, kdf_id: KDFId, aead_id: AEADId) → CipherSuite

Constructor of HPKE cipher suite.

Parameters:

• kem_id (KEMId) – A KEM (Key Encapsulation Mechanism) identifier.

• kdf_id (KDFId) – A KDF (Key Derivation Function) identifier.

• aead_id (AEADId) – An AEAD (Authenticated Encryption with Additional Data) identifier.

Returns:

A CipherSuite object.

Return type:

CipherSuite

property kem: KEMInterface

The KEM context in the cipher suite.

property kdf: KDFInterface

The KDF context in the cipher suite.

property aead: AEADInterface

The AEAD context in the cipher suite.

create_sender_context(pkr: KEMKeyInterface, info: bytes = b'', sks: KEMKeyInterface | None = None, psk: bytes = b'', psk_id: bytes = b'', eks: KEMKeyPair | None = None) → tuple[bytes, ContextInterface]

Creates a sender context.

create_recipient_context(enc: bytes, skr: KEMKeyInterface, info: bytes = b'', pks: KEMKeyInterface | None = None, psk: bytes = b'', psk_id: bytes = b'') → ContextInterface

Creates a recipient context.

seal(pkr: KEMKeyInterface, pt: bytes, info: bytes = b'', aad: bytes = b'', psk: bytes = b'', psk_id: bytes = b'', sks: KEMKeyInterface | None = None) → tuple[bytes, bytes]

Does a single-shot encryption.

open(enc: bytes, skr: KEMKeyInterface, ct: bytes, info: bytes = b'', aad: bytes = b'', psk: bytes = b'', psk_id: bytes = b'', pks: KEMKeyInterface | None = None) → bytes

Does a single-shot decryption.

class pyhpke.AEADId(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

AES128_GCM = 1

AES256_GCM = 2

CHACHA20_POLY1305 = 3

EXPORT_ONLY = 65535

class pyhpke.KDFId(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

HKDF_SHA256 = 1

HKDF_SHA384 = 2

HKDF_SHA512 = 3

class pyhpke.KEMId(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

DHKEM_P256_HKDF_SHA256 = 16

DHKEM_P384_HKDF_SHA384 = 17

DHKEM_P521_HKDF_SHA512 = 18

DHKEM_X25519_HKDF_SHA256 = 32

DHKEM_X448_HKDF_SHA512 = 33

class pyhpke.ContextInterface

Bases: object

seal(pt: bytes, aad: bytes = b'') → bytes

open(ct: bytes, aad: bytes = b'') → bytes

export(exporter_context: bytes, length: int) → bytes

exception pyhpke.NotSupportedError

Bases: PyHPKEError

An Exception occurred when the function is not supported.

exception pyhpke.OpenError

Bases: PyHPKEError

An Exception occurred when an decryption process failed.

exception pyhpke.PyHPKEError

Bases: Exception

Base class for all exceptions.

exception pyhpke.SealError

Bases: PyHPKEError

An Exception occurred when an encryption process failed.

class pyhpke.KDFInterface

Bases: object

The KDF (Key Derivation Function) interface.

property id: KDFId

The KDF identifier.

extract(salt: bytes, ikm: bytes) → bytes

expand(prk: bytes, info: bytes, length: int) → bytes

class pyhpke.KEMInterface

Bases: object

The KEM (Key Encapsulation Mechanism) interface.

property id: KEMId

The KEM identifier.

deserialize_private_key(key: bytes) → KEMKeyInterface

deserialize_public_key(key: bytes) → KEMKeyInterface

encap(pkr: KEMKeyInterface, sks: KEMKeyInterface | None = None, eks: KEMKeyPair | None = None) → tuple[bytes, bytes]

decap(enc: bytes, skr: KEMKeyInterface, pks: KEMKeyInterface | None = None) → bytes

derive_key_pair(ikm: bytes) → KEMKeyPair

class pyhpke.KEMKey

Bases: object

A KEMKeyInterface Builder.

classmethod from_pyca_cryptography_key(k: Any) → KEMKeyInterface

Creates an HPKE key from pyca/cryptography key object.

classmethod from_jwk(data: bytes | str | dict[str, Any]) → KEMKeyInterface

Creates an HPKE key from JWK (JSON Web Key).

classmethod from_pem(data: bytes | str) → KEMKeyInterface

Creates an HPKE key from PEM-formatted key data.

class pyhpke.KEMKeyPair(sk: KEMKeyInterface, pk: KEMKeyInterface)

Bases: object

property private_key: KEMKeyInterface

property public_key: KEMKeyInterface

class pyhpke.KEMKeyInterface(key: Any)

Bases: object

The KEM key interface.

property raw: Any

to_private_bytes() → bytes

Serializes the key to a byte string if it is private.

to_public_bytes() → bytes

Serializes the key to a byte string if it is public.