hpqc (Python)

A Python port of selected primitives from katzenpost/hpqc, the hybrid post-quantum cryptography library used by the Katzenpost mix network. The Go implementation is the reference; this Python package covers BACAP, MKEM, and the NIKE primitives those depend on, so Python applications and tooling can perform these operations directly. The shared JSON test vectors under testvectors/ keep the Python and Go ports byte-identical.

For the rationale behind BACAP and a short overview of the construction, see the BACAP section of the main README. For a fuller treatment, see §4 of the Echomix paper. For the full catalogue of NIKE, KEM, and signature schemes that hpqc implements in Go, see the main repository README.

What is ported

• BACAP (hpqc.bacap): blinding-and-capability scheme. Positions (ReadPosition, WritePosition) and the stateless API (immutable MessageBoxIndex, WriteCap, ReadCap). Encrypt, decrypt, sign, verify, and tombstones are all covered.
• MKEM (hpqc.protocols.mkem): multi-recipient KEM construction over any NIKE.
• Sealed box (hpqc.protocols.sealedbox): anonymous public-key encryption to one recipient over any NIKE.
• NIKE abstractions (hpqc.nike.scheme): Scheme, PublicKey, PrivateKey base classes mirroring the Go interfaces.
• NIKE primitives: X25519 (hpqc.nike.x25519), CTIDH at field sizes 511, 512, 1024, and 2048 (hpqc.nike.ctidh{511,512,1024,2048}, via the upstream highctidh package), and a generic HybridNIKE combiner (hpqc.nike.hybrid).
• Ed25519 signature verification (hpqc.sign.ed25519): the blinded Ed25519 variant on which BACAP relies, plus an Ed25519Scheme verify-only wrapper for plain Ed25519.
• Falcon-padded-512 signature verification (hpqc.sign.falcon.FalconPadded512Scheme), backed by the pqcrypto runtime dependency, which vendors the same PQClean reference C used by the Go side.
• Hybrid signature verification (hpqc.sign.hybrid): generic two-component combiner plus a pre-registered FalconPadded512Ed25519 instance.

The Python and Go test suites read the same JSON vector files: the Python side reads copies under tests/.../vectors/, which tests/test_vector_copies.py keeps identical to the canonical files, so any byte-level divergence between the two ports trips a failing assertion on whichever side runs first.

Installation

pip install hpqc

Runtime dependencies (pynacl, cryptography, cbor2, highctidh, pqcrypto) are pulled in automatically.

To install from a source checkout instead (for example to test an unreleased change):

pip install -e /path/to/hpqc/py

Quick start

A BACAP round-trip:

from hpqc.bacap import WriteCap

writer = WriteCap.generate()
reader = writer.read_cap()
ctx = b"my-application/v1"

mbi = writer.message_box_index
box_id, ciphertext, signature = mbi.encrypt_for_context(
    writer, ctx, b"hello, pigeonhole"
)

# Anyone holding the read cap can verify and decrypt:
plaintext = mbi.decrypt_for_context(box_id, ctx, ciphertext, signature)
assert plaintext == b"hello, pigeonhole"

Encapsulating a payload to multiple recipients with MKEM:

from hpqc.protocols.mkem import MKEMScheme
from hpqc.nike.x25519 import X25519

mkem = MKEMScheme(X25519())
alice_pk, alice_sk = mkem.generate_keypair()
bob_pk,   bob_sk   = mkem.generate_keypair()

eph_priv, ct = mkem.encapsulate([alice_pk, bob_pk], b"secret payload")
assert mkem.decapsulate(alice_sk, ct) == b"secret payload"
assert mkem.decapsulate(bob_sk,   ct) == b"secret payload"

Sealing a payload to one recipient:

from hpqc.protocols.sealedbox import SealedBoxScheme
from hpqc.nike.x25519 import X25519

nike = X25519()
box = SealedBoxScheme(nike)
pk, sk = nike.generate_keypair()

ct = box.seal(pk, b"secret payload")
assert box.open(sk, pk, ct) == b"secret payload"

Running the tests

cd hpqc/py
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"
pytest

Cross-language vector tests live under tests/bacap/, tests/protocols/, and tests/sign/. They read copies of the canonical JSON vectors under ../testvectors/, which the Go test suite also consumes. The copies are real files so that the sdist carries them; after regenerating the vectors, refresh them with the cp command that tests/test_vector_copies.py prints for each stale copy.

License

AGPL-3.0-only. See LICENSE.

See also

• Main repository README — full Go reference, design notes, and tables of every NIKE, KEM, and signature scheme that hpqc implements.
• Echomix paper — the design of BACAP (§4) and Pigeonhole (§5).
• Katzenpost mix network — the system this library serves.