ZKAC/docs/PYTHON_API.md

ZKAC Python API Reference

Version 0.1. Cryptographic stack: BBS+ on BLS12-381 (credentials), X25519 + ChaCha20-Poly1305 (transport), BLAKE2b (role IDs).

import zkac

Constants

MAX_BBS_AUTH_PROOF_BYTES

Upper bound on BBS+ proof size in an encrypted auth packet (256 KiB). Larger proofs are rejected.

Transport identity (Ristretto255)

Keypair()

Generates a new random keypair.

Keypair.public_key() -> PublicKey

Raises ValueError if consumed by Node(...).

PublicKey

• to_bytes() -> bytes — 32 bytes
• from_bytes(bytes) -> PublicKey
• Equality, hash, repr supported

BBS+ credentials

role_id(name: str) -> bytes

32-byte opaque role id from a human-readable name.

BbsIssuer()

New random issuer. from_secret_key(bytes) restores from 32-byte secret.

• public_key() -> BbsPublicKey
• secret_key_bytes() -> bytes (confidential)
• issue_blind(commitment_with_proof, role_id, epoch) -> bytes — role_id must be 32 bytes

BbsPublicKey

• to_bytes() / from_bytes

prepare_blind_request() -> BlindRequest

• commitment_with_proof(), member_secret(), prover_blind() — all return bytes

Credential.finalize(blind_sig, member_secret, prover_blind, role_id, epoch, pk) -> Credential

• present(nonce) -> bytes
• role_id() -> bytes, epoch() -> int

Server registry

RoleRegistry

• register_role(role_id, pk, epoch) — role_id 32 bytes
• set_epoch(role_id, epoch)
• verify_presentation(role_id, proof_bytes, nonce) -> bool
• has_role(role_id) -> bool

Node and session

Node(keypair) — consumes Keypair

• public_key() -> PublicKey
• connect() -> (PendingConnect, bytes) — 32-byte init message
• accept(init_msg) -> (Session, bytes) — init_msg 32 bytes
• complete_connect(pending, response_msg, credential) -> (Session, bytes) — response_msg 32 bytes
• verify_auth(session, encrypted_auth, registry) -> bytes — returns 32-byte role_id

Session

• transcript_hash() -> bytes — use as nonce for Credential.present
• encrypt(plaintext) -> bytes
• decrypt(packet) -> bytes

Typical flow

1. Issuer creates BbsIssuer(); server register_role(role_id, issuer.public_key(), epoch).
2. Member: prepare_blind_request → issuer issue_blind → Credential.finalize.
3. Client: connect → server accept → client complete_connect → server verify_auth.
4. Use Session.encrypt / decrypt for data.

Errors

Raises ValueError with descriptive messages for crypto failures, replay, and bad inputs.

Further reading

Security model and assumptions