97 lines
2.6 KiB
Markdown
97 lines
2.6 KiB
Markdown
# ZKAC Python API Reference
|
|
|
|
Version 0.1. Cryptographic stack: **BBS+** on BLS12-381 (credentials), **X25519** + **ChaCha20-Poly1305** (transport), **BLAKE2b** (role IDs).
|
|
|
|
```python
|
|
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](./SECURITY.md)
|