1. Usage
2. Features
3. Installation
4. Development
5. Related Projects

The Sender Context and Receiver Context APIs allow for setting up a context for repeated encryptions and decryptions. It's recommended whenever you intend to perform several encryptions or decryptions in quick succession.

info = b"quotes from your favorite aphorists"
aads = [
  b"Szasz",
  b"Nietzsche",
  b"Morandotti",
  b"Brudzinski",
  b"Hubbard",
]

# ============== Sender ==============

messages = [
    b"Two wrongs don't make a right, but they make a good excuse.",
    b"Become who you are!",
    b"Only those who aren't hungry are able to judge the quality of a meal.",
    b"Under certain circumstances a wanted poster is a letter of recommendation.",
    b"Nobody ever forgets where he buried the hatchet.",
]
encap, sender_context = hpke.setup_sender(public_key_r, info)

ciphertexts = []
for aad, msg in zip(aads, messages):
    ciphertext = sender_context.seal(aad, msg)
    ciphertexts.append(ciphertext)

# ============= Receiver =============

receiver_context = hpke.setup_receiver(encap, secret_key_r, info)
plaintexts = []
for aad, ctxt in zip(aads, ciphertexts):
    plaintext = receiver_context.open(aad, ctxt)
    plaintexts.append(plaintext)

print(f"\"{plaintexts[0].decode()}\" - {aad[0].decode()}")
print(f"\"{plaintexts[1].decode()}\" - {aad[1].decode()}")
# >> "Two wrongs don't make a right, but they make a good excuse." - Szasz
# >> "Become who you are!" - Nietzsche

Auth mode allows for signing and verifying encryptions with a previously authenticated sender key-pair.

hpke = hybrid_pke.default(mode=hybrid_pke.Mode.AUTH)
secret_key_r, public_key_r = hpke.generate_key_pair()  # receiver keys
secret_key_s, public_key_s = hpke.generate_key_pair()  # sender keys, pre-authenticated

# ============== Sender ==============

# sign with sender's secret key
encap, ciphertext = hpke.seal(public_key_r, info, aad, message, sk_s=secret_key_s)

# ============= Receiver =============

# verify with sender's public key
plaintext = hpke.open(encap, secret_key_r, info, aad, ciphertext, pk_s=public_key_s)

PSK mode allows for signing and verifying encryptions with a previously shared key held by both the sender and recipient.

hpke = hybrid_pke.default(mode=hybrid_pke.Mode.PSK)
# pre-shared key + ID
psk = bytes.fromhex("0247fd33b913760fa1fa51e1892d9f307fbe65eb171e8132c2af18555a738b82")
psk_id = bytes.fromhex("456e6e796e20447572696e206172616e204d6f726961")

# ============== Sender ==============

# sign with pre-shared key
encap, ciphertext = hpke.seal(public_key_r, info, aad, message, psk=psk, psk_id=psk_id)

# ============= Receiver =============

# verify with pre-shared key
plaintext = hpke.open(encap, secret_key_r, info, aad, ciphertext, psk=psk, psk_id=psk_id)

PSK mode allows for signing and verifying encryptions with a previously shared key held by both the sender and recipient.

hpke = hybrid_pke.default(mode=hybrid_pke.Mode.PSK)
secret_key_r, public_key_r = hpke.generate_key_pair()  # receiver keys
secret_key_s, public_key_s = hpke.generate_key_pair()  # sender keys, pre-authenticated
# pre-shared key + ID
psk = bytes.fromhex("0247fd33b913760fa1fa51e1892d9f307fbe65eb171e8132c2af18555a738b82")
psk_id = bytes.fromhex("456e6e796e20447572696e206172616e204d6f726961")

# ============== Sender ==============

# sign with both pre-shared key and sender's secret key
encap, ciphertext = hpke.seal(
    public_key_r, info, aad, message,
    psk=psk, psk_id=psk_id, sk_s=secret_key_s,
)

# ============= Receiver =============

# verify with both pre-shared key and sender's public key
plaintext = hpke.open(
    encap, secret_key_r, info, aad, ciphertext,
    psk=psk, psk_id=psk_id, pk_s=public_key_s,
)

• mode_base
• mode_psk
• mode_auth
• mode_auth_psk

• DHKEM(P-256, HKDF-SHA256)
• DHKEM(P-384, HKDF-SHA384)
• DHKEM(P-521, HKDF-SHA512)
• DHKEM(X25519, HKDF-SHA256)
• DHKEM(X448, HKDF-SHA512)

• HKDF-SHA256
• HKDF-SHA384
• HKDF-SHA512

• AES-128-GCM
• AES-256-GCM
• ChaCha20Poly1305
• Export only

• maturin develop builds & installs the Python package into your Python environment (venv or conda recommended)
• pytest . tests the resulting Python package.
• pytest -n auto . runs the full test suite in parallel.
• maturin build --release -o dist --sdist builds the extension module in release-mode and produces a wheel for your environment's OS and architecture.
• The -i/--interpreter flag for maturin can be used to swap out different Python interpreters, if you have multiple Python installations.

$ git checkout main
$ cargo release patch --execute
Upgrading hybrid_pke from X.X.X-dev0 to X.X.X
   Replacing in pyproject.toml
--- pyproject.toml      original
+++ pyproject.toml      replaced
@@ -8 +8 @@
-version = "X.X.X-dev0"  # NOTE: auto-updated during release
+version = "X.X.X"  # NOTE: auto-updated during release
$ cargo release X.X.Y-dev0 --no-tag
Upgrading hybrid_pke from X.X.X to X.X.Y-dev0
   Replacing in pyproject.toml
--- pyproject.toml      original
+++ pyproject.toml      replaced
@@ -8 +8 @@
-version = "X.X.X"  # NOTE: auto-updated during release
+version = "X.X.Y-dev0"  # NOTE: auto-updated during release
$ git push origin main
$ git push origin vX.X.X  # triggers automatic release steps in CI