pyhpke

library0.6.5pypypi✓ verified 27d ago

PyHPKE is a Python implementation of HPKE (Hybrid Public Key Encryption), providing mechanisms for authenticated encryption with associated data. It supports all HPKE modes and cipher suites defined in RFC9180. The library is currently at version 0.6.4 and maintains a regular release cadence with frequent minor updates and dependency bumps.

auth-security serialization

pip install pyhpke

github ↗package ↗

INSTALL

IMPORT

SIG · PYHPKE

pyhpke

auth-securitypythonv0.6.5

Install

2.6s avg

Import

94ms

Disk

33MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.6.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.098s · 35.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.6s · import 0.090s · 36MB

33MB installed

● package 33MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CipherSuite

✓ from pyhpke import CipherSuite

KEMKey

✓ from pyhpke import KEMKey

KEMId

✓ from pyhpke import KEMId

KDFId

✓ from pyhpke import KDFId

AEADId

✓ from pyhpke import AEADId

This example demonstrates a basic HPKE 'Base' mode encryption and decryption flow. A sender creates a context using the recipient's public key, encapsulates a symmetric key, and seals a plaintext message. The recipient uses the encapsulated key and their private key to open the ciphertext.

from pyhpke import CipherSuite, KEMKey, KEMId, KDFId, AEADId # --- Sender Side --- # Define the HPKE cipher suite suite_s = CipherSuite.new( KEMId.DHKEM_X25519_HKDF_SHA256, KDFId.HKDF_SHA256, AEADId.AES128_GCM ) # Recipient's public key (example PEM format) public_key_pem = b"""-----BEGIN PUBLIC KEY----- MCowBQYDK2VuAyEAoMfvlI5DN08JRFP2fhWvZ6vBEl28yFeS9O9YQUjNyCY= -----END PUBLIC KEY-----""" pkr = KEMKey.from_pem(public_key_pem) # Create sender context and encapsulate key enc, sender = suite_s.create_sender_context(pkr) # Seal the message plaintext = b"Hello world!" ciphertext = sender.seal(plaintext) print(f"Encapsulated Key: {enc.hex()}") print(f"Ciphertext: {ciphertext.hex()}") # --- Recipient Side --- # Define the same HPKE cipher suite suite_r = CipherSuite.new( KEMId.DHKEM_X25519_HKDF_SHA256, KDFId.HKDF_SHA256, AEADId.AES128_GCM ) # Recipient's private key (example PEM format, corresponding to public_key_pem) private_key_pem = b"""-----BEGIN PRIVATE KEY----- MC4CAQAwBQYDK2VuBCIEIMAXvyHjAeXy9x4MXF6rwGbDKw7crgDriFTFXO+XsS1F -----END PRIVATE KEY-----""" skr = KEMKey.from_pem(private_key_pem) # Create recipient context and decapsulate key (using 'enc' from sender) recipient = suite_r.create_recipient_context(enc, skr) # Open the message decrypted_text = recipient.open(ciphertext) print(f"Decrypted Text: {decrypted_text.decode()}") assert decrypted_text == plaintext

Debug

Known issues

gotchaThe PyHPKE library has not undergone a formal security audit. Users should perform their own risk assessment before deploying it in production environments, especially for sensitive data.

fix

Thoroughly review the codebase and cryptographic primitives or seek independent security audits for critical applications.

affects: All versions

breakingSupport for Python 3.8 was dropped in PyHPKE version 0.6.0. Users on Python 3.8 or older must upgrade their Python environment or use an earlier PyHPKE version (e.g., <0.6.0).

fix

Upgrade Python to 3.10 or newer (the current minimum supported version is 3.10) or pin pyhpke to a version prior to 0.6.0.

affects: >=0.6.0

gotchaCryptographic libraries require careful key management. Ensure private keys are stored securely, never hardcoded, and access is strictly controlled. Avoid nonce reuse for AEAD modes, as it can lead to severe security vulnerabilities.

fix

Implement robust key management practices, securely generate and store keys, and use unique nonces for each encryption operation (e.g., using a secure random number generator).

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pyhpke'

The 'pyhpke' package is not installed in the Python environment you are using, or there is a typo in the import statement.

fix

Install the package using pip: `pip install pyhpke`.

ValueError: Invalid arguments

This error typically occurs when one or more arguments passed to a pyhpke function (like `seal` or `open`) do not meet the expected type, format, or length requirements for the chosen HPKE cipher suite.

fix

Ensure all arguments (e.g., plaintext/ciphertext, nonce, AAD) conform to the expected types and lengths for the selected `CipherSuite` and method. Refer to the `pyhpke` API documentation for specific parameter requirements.

pyhpke.exceptions.SealError: Failed to encrypt the plain text.

An internal error occurred during the encryption process, often indicating an invalid state in the sender context, incorrect cryptographic parameters, or issues with the provided keys or data.

fix

Review the setup of the `CipherSuite` and the `sender_context`, ensuring that valid KEM, KDF, and AEAD identifiers are used, and that the recipient's public key is correctly formatted. Verify the plaintext and associated authenticated data (AAD) for any non-conformant values.

pyhpke.exceptions.OpenError: Failed to decrypt the cipher text.

The provided ciphertext could not be successfully decrypted, likely due to a mismatch in cryptographic parameters, an incorrect private key, an invalid `enc` value, an incorrect nonce, or if the ciphertext or associated authenticated data (AAD) has been tampered with.

fix

Verify that the recipient's private key, the `enc` value obtained from the sender, the `nonce`, and the `aad` used during decryption exactly match those used during the original encryption. Ensure the correct `CipherSuite` is being used.

Upgrade

Version history

0.6.5latest on PyPI · released Jul 16, 2026

Audit

Dependencies

cryptographyrequiredProvides underlying cryptographic primitives.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dajiaji/pyhpke ↗

packagehttps://pypi.org/project/pyhpke/ ↗