Files
dvs 0d69391aa9 Release v3.2.0: pure-Python cryptography library (English docs/comments/errors)
- Zero-dependency pure-Python cryptography: SHA-2 / SHA-3 / SHAKE / BLAKE2b,
  HMAC, PBKDF2 / HKDF / scrypt / Argon2id, AES (ECB/CBC/CTR/CFB/OFB/GCM),
  AES-GCM-SIV, ChaCha20-Poly1305 / XChaCha20-Poly1305, X25519, Ed25519,
  RSA (keygen / OAEP / PSS / PEM), ASN.1 DER
- Unified error system: PPYC_ERR fatal exception vs (code, message, suggestion)
  non-fatal 3-tuple return
- Interactive TUI (Chinese / English i18n) + non-interactive CLI
- v3.2.0 adds the encoding, rand and kdf2 modules
- Documentation, code comments and error messages fully in English;
  the interactive TUI keeps its Chinese interface
- Tests: RFC / FIPS / NIST test vectors, 639 passing
2026-09-27 09:40:12 +08:00

1589 lines
52 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API Reference
This file is the complete API reference for `purepycrypto v3.2.0`. The v1.0 public interfaces can be imported directly from the top-level package:
```python
from purepycrypto import sha256, AES, rsa_keygen
```
> **SHA-3 / SHAKE**, **Ed25519**, and **AES-GCM-SIV** can be imported both from their own submodules
> (e.g. `from purepycrypto.sha3 import sha3_256`) and from the top-level exports, see
> [§11](#11-sha3--sha3--keccak--shake), [§12](#12-ed25519--ed25519-digital-signatures), [§13](#13-aes_gcm_siv--aes-gcm-siv).
>
> ⚠️ As of v3.2.0 the library uses a **unified error system**: expected failures **return a 3-tuple** instead of raising, see [§0](#0-unified-error-system-new-in-v320).
The following sections are organized by module; each function gives its **signature, parameter table, return value, example, and notes**.
For an overview and tutorials, see [`../README.md`](../README.md) and [`quickstart.md`](quickstart.md).
---
## Table of Contents
- [0. Unified Error System (New in v3.2.0)](#0-unified-error-system-new-in-v320)
- [Module Overview](#module-overview)
- [1. common — Basic Utilities](#1-common--basic-utilities)
- [2. hash — Hashing](#2-hash--hashing)
- [3. kdf — Key Derivation and Message Authentication](#3-kdf--key-derivation-and-message-authentication)
- [4. aes — AES Symmetric Encryption](#4-aes--aes-symmetric-encryption)
- [5. chacha — ChaCha20 / Poly1305 / AEAD](#5-chacha--chacha20--poly1305--aead)
- [6. x25519 — X25519 Key Exchange](#6-x25519--x25519-key-exchange)
- [7. rsa — RSA Public-Key Cryptography](#7-rsa--rsa-public-key-cryptography)
- [8. der — ASN.1 DER / PEM Serialization](#8-der--asn1-der--pem-serialization)
- [9. parallel — Multiprocessing Acceleration](#9-parallel--multiprocessing-acceleration)
- [10. Command-Line Interface](#10-command-line-interface)
- [11. sha3 — SHA-3 / Keccak / SHAKE](#11-sha3--sha3--keccak--shake)
- [12. ed25519 — Ed25519 Digital Signatures](#12-ed25519--ed25519-digital-signatures)
- [13. aes_gcm_siv — AES-GCM-SIV](#13-aes_gcm_siv--aes-gcm-siv)
- [14. Exceptions and the Error System](#14-exceptions-and-the-error-system)
- [15. Top-Level Export List](#15-top-level-export-list)
- [16. kdf2 — Hardened Key Derivation (New in v3.2.0)](#16-kdf2--hardened-key-derivation-new-in-v320)
- [17. encoding — Encoding (New in v3.2.0)](#17-encoding--encoding-new-in-v320)
- [18. rand — CSPRNG Utilities (New in v3.2.0)](#18-rand--csprng-utilities-new-in-v320)
---
## 0. Unified Error System (New in v3.2.0)
As of v3.2.0, `purepycrypto` uses a unified error system library-wide; the authoritative reference is [`errors.md`](errors.md).
| Type | Handling | Applicable scenarios |
|------|----------|----------------------|
| **Fatal error** | **Raise `PPYC_ERR`** | Internal invariant broken (library bug), fatal environment problem, unable to construct an object during initialization |
| **Non-fatal error** | **Return a 3-tuple** `(error_code, error_message, suggestion)` | Invalid input, failed validation, authentication failure, missing file, parse failure |
```python
from purepycrypto import PPYC_ERR, err, ok, is_ok, is_err, OK_TUPLE, PPYC_ERR_INVALID_KEY_LEN
# fatal error
raise PPYC_ERR(PPYC_ERR_INTERNAL, "state machine inconsistent", "please file an issue")
# non-fatal error (returns a tuple)
return err(PPYC_ERR_INVALID_KEY_LEN, "AES key must be 16/24/32 bytes", "pass a correct length")
# -> ('PPYC_ERR_INVALID_KEY_LEN', 'AES key must be 16/24/32 bytes', 'pass a correct length')
# success (validation-style API)
return OK_TUPLE # (None, None, None)
```
| Helper / Name | Description |
|---------------|-------------|
| `PPYC_ERR(code, message, suggestion="")` | fatal-error exception (`PPYCError` is an alias), with `code` / `message` / `suggestion` attributes and `as_tuple()` |
| `CryptoError` / `DecryptionError` / `Ed25519Error` | legacy exception names (subclasses of `PPYC_ERR`; default codes are `PPYC_ERR_INTERNAL` / `PPYC_ERR_AUTH_FAILED` / `PPYC_ERR_INVALID_ARG`) |
| `err(code, message, suggestion="")` | construct a non-fatal error tuple (validates the `PPYC_ERR_` prefix) |
| `ok(value)` | semantically marks "success"; equivalent to returning `value` directly |
| `OK_TUPLE` | `(None, None, None)`, the success return of validation-style APIs |
| `is_ok(result)` / `is_err(result)` | determine whether the return value is a success / an error tuple |
| `raise_ppyc(code, message, suggestion="")` | convenience for raising `PPYC_ERR` |
| `PPYCResult` | type alias `Tuple[Optional[str], Optional[str], Optional[str]]` |
| `ALL_ERROR_CODES` | all 41 error code constants (tuple); a single constant can be imported via `from purepycrypto import PPYC_ERR_xxx` |
**Caller check**:
```python
result = some_api(...)
if is_err(result):
code, msg, hint = result
...
else:
value = result
```
---
## Module Overview
| Module | Responsibility | Key public interfaces |
|--------|----------------|-----------------------|
| `_ppyc_error` | **Unified error system** (v3.2.0): exceptions, error codes, tuple helpers | `PPYC_ERR`, `err`, `ok`, `is_ok`, `is_err`, `OK_TUPLE`, `ALL_ERROR_CODES` |
| `common` | constant-time comparison, secure random, padding, mask constants | `rand_bytes`, `rand_int`, `_consttime_eq` |
| `hash` | SHA-256 / SHA-512 / BLAKE2b | `sha256`, `sha512`, `blake2b` |
| `sha3` | SHA-3 / Keccak / SHAKE / HMAC-SHA3 | `sha3_256`, `shake128`, `hmac_sha3_256` |
| `kdf` | HMAC / PBKDF2 / HKDF / scrypt / Argon2id | `hmac_sha256`, `pbkdf2_hmac`, `hkdf`, `scrypt`, `argon2id` |
| `aes` | AES block cipher and operation modes | `AES` |
| `aes_gcm_siv` | AES-GCM-SIV (nonce-misuse resistant AEAD) | `aes_gcm_siv_encrypt`, `aes128_gcm_siv_encrypt`, `polyval` |
| `chacha` | ChaCha20-Poly1305 / XChaCha20-Poly1305 / Poly1305 | `chacha20poly1305_encrypt`, `xchacha20poly1305_encrypt`, `poly1305_mac` |
| `x25519` | X25519 key exchange | `x25519`, `x25519_base`, `x25519_shared`, `x25519_generate_keypair` |
| `rsa` | RSA key generation / OAEP / PSS | `rsa_keygen`, `rsa_oaep_encrypt`, `rsa_pss_sign`, `RSAPublicKey`, `RSAPrivateKey` |
| `ed25519` | Ed25519 digital signatures | `ed25519_keygen`, `ed25519_sign`, `ed25519_verify` |
| `der` | PKCS#1 / PKCS#8 / SPKI / PEM | `private_key_to_pem`, `public_key_to_pem`, `parse_private_pem` |
| `parallel` | process-pool reuse + SharedMemory | `_HAS_MP` (capability probe), internal process pool |
| `cli` | interactive TUI (CN/EN bilingual) | `python -m purepycrypto` (no arguments) |
| `cli_args` | command-line mode | `purepycrypto <subcommand>` (see [`cli.md`](cli.md)) |
---
## 1. common — Basic Utilities
The module `purepycrypto.common` provides low-level utilities and exception types.
### 1.1 `rand_bytes(n)`
```python
rand_bytes(n: int) -> bytes
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `n` | `int` | number of random bytes to generate |
**Return value**: `bytes`, `n` bytes of cryptographically secure random data.
**Example**
```python
from purepycrypto import rand_bytes
salt = rand_bytes(16)
print(len(salt)) # 16
```
**Notes**: internally calls `os.urandom(n)` directly (the OS CSPRNG), with no seedable state.
---
### 1.2 `rand_int(a, b)`
```python
rand_int(a: int, b: int) -> int
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `a` | `int` | lower bound (inclusive) |
| `b` | `int` | upper bound (inclusive) |
**Return value**: `int`, a uniformly distributed random integer in `[a, b]`.
**Example**
```python
from purepycrypto import rand_int
x = rand_int(1, 6) # simulate a die
```
**Notes**: when `a > b` it **returns an error tuple** (`PPYC_ERR_INVALID_ARG`); internally uses rejection sampling to avoid modulo bias.
---
### 1.3 Constant-Time Comparison (internal utilities)
| Function | Signature | Description |
|----------|-----------|-------------|
| `_consttime_eq` | `_consttime_eq(a: bytes, b: bytes) -> bool` | constant-time comparison of two byte strings |
| `_consttime_int_eq` | `_consttime_int_eq(a: int, b: int, bits: int) -> bool` | constant-time comparison of two integers (expanded over `bits` bits) |
| `_consttime_select` | `_consttime_select(cond: int, a: int, b: int, bits: int) -> int` | constant-time bitwise selection (`a` if `cond` is nonzero, otherwise `b`) |
**Notes**: names beginning with `_` are library-internal functions used by sensitive paths such as the GCM Tag, Poly1305 Tag, and X25519; ordinary users do not need to call them directly.
---
### 1.4 Padding Utilities (internal)
| Function | Signature | Description |
|----------|-----------|-------------|
| `_pad16` | `_pad16(data: bytes) -> bytes` | pad with 0x00 to a multiple of 16 |
| `_pad_pkcs7` | `_pad_pkcs7(data: bytes, bs: int = 16) -> bytes` | PKCS#7 padding |
| `_unpad_pkcs7` | `_unpad_pkcs7(data: bytes) -> bytes` | remove PKCS#7 padding (invalid padding **returns an error tuple** `PPYC_ERR_INVALID_PADDING`) |
---
### 1.5 Constants
| Name | Value | Description |
|------|-------|-------------|
| `MASK32` | `0xFFFFFFFF` | 32-bit mask |
| `MASK64` | `0xFFFFFFFFFFFFFFFF` | 64-bit mask |
| `MASK128` | `(1 << 128) - 1` | 128-bit mask |
| `POLY1305_P` | `(1 << 130) - 5` | Poly1305 prime `2^130 - 5` |
| `GHASH_R` | `0xE1000000000000000000000000000000` | GCM GHASH reduction constant |
| `R_CONST` | same as `GHASH_R` | alias |
---
## 2. hash — Hashing
### 2.1 `sha256`
```python
sha256(message: bytes) -> bytes
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `message` | `bytes` | data to hash |
**Return value**: `bytes`, a 32-byte digest (FIPS 180-4).
**Example**
```python
from purepycrypto import sha256
assert sha256(b"abc").hex() == (
"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
)
```
---
### 2.2 `sha512`
```python
sha512(message: bytes) -> bytes
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `message` | `bytes` | data to hash |
**Return value**: `bytes`, a 64-byte digest (FIPS 180-4).
**Example**
```python
from purepycrypto import sha512
assert len(sha512(b"abc")) == 64
```
---
### 2.3 `blake2b`
```python
blake2b(data: bytes, digest_size: int = 64) -> bytes
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `data` | `bytes` | — | data to hash |
| `digest_size` | `int` | `64` | digest length (1–64 bytes) |
**Return value**: `bytes`, a digest of length `digest_size` (RFC 7693).
**Example**
```python
from purepycrypto import blake2b
print(len(blake2b(b"abc"))) # 64
print(len(blake2b(b"abc", 32))) # 32
```
**Notes**: this library's BLAKE2b is also used as the underlying hash for Argon2id (H′ and H0 computation). When `digest_size` is outside 1–64 it **returns an error tuple** (`PPYC_ERR_INVALID_ARG`) instead of raising.
> v1.1 adds **SHA-3 / Keccak / SHAKE**, see [§11](#11-sha3--sha3--keccak--shake).
---
## 3. kdf — Key Derivation and Message Authentication
### 3.1 `hmac_sha256`
```python
hmac_sha256(key: bytes, message: bytes) -> bytes
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | `bytes` | key (any length; if longer than 64 bytes it is first compressed with SHA-256) |
| `message` | `bytes` | message |
**Return value**: `bytes`, a 32-byte HMAC value (RFC 2104).
**Example**
```python
from purepycrypto import hmac_sha256
key = b"\x0b" * 20
mac = hmac_sha256(key, b"Hi There")
assert mac.hex() == "b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7"
```
---
### 3.2 `hmac_sha512`
```python
hmac_sha512(key: bytes, message: bytes) -> bytes
```
As described for `hmac_sha256`, but returns a 64-byte HMAC value with a 128-byte block size.
---
### 3.3 `pbkdf2_hmac`
```python
pbkdf2_hmac(password: bytes, salt: bytes, iterations: int,
dklen: int, hash_name: str = "sha256") -> bytes
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `password` | `bytes` | — | password |
| `salt` | `bytes` | — | salt (recommended ≥ 16 bytes, unique per password) |
| `iterations` | `int` | — | iteration count, must be ≥ 1 |
| `dklen` | `int` | — | derived key length (bytes), must be ≥ 1 |
| `hash_name` | `str` | `"sha256"` | underlying hash, `"sha256"` or `"sha512"` |
**Return value**: `bytes`, a derived key of length `dklen` (RFC 8018).
**Example**
```python
from purepycrypto import pbkdf2_hmac
dk = pbkdf2_hmac(b"password", b"salt", iterations=1, dklen=32)
assert dk.hex() == "120fb6cffcf8b32c43e7225256c4f837a86548c92ccc35480805987cb70be17b"
```
**Notes**: when `hash_name` is neither `"sha256"` nor `"sha512"` it **returns an error tuple** (`PPYC_ERR_INVALID_ALGO`); `iterations < 1` returns `PPYC_ERR_INVALID_KDF_PARAM`.
---
### 3.4 `hkdf_extract`
```python
hkdf_extract(salt: bytes, ikm: bytes, hash_name: str = "sha256") -> bytes
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `salt` | `bytes` | — | salt (may be empty `b""`) |
| `ikm` | `bytes` | — | input keying material |
| `hash_name` | `str` | `"sha256"` | `"sha256"` or `"sha512"` |
**Return value**: `bytes`, the pseudorandom key PRK (HKDF-Extract, RFC 5869).
---
### 3.5 `hkdf_expand`
```python
hkdf_expand(prk: bytes, info: bytes, length: int, hash_name: str = "sha256") -> bytes
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prk` | `bytes` | — | the PRK obtained from `hkdf_extract` |
| `info` | `bytes` | — | context/purpose information (to distinguish different subkeys) |
| `length` | `int` | — | output length (bytes) |
| `hash_name` | `str` | `"sha256"` | `"sha256"` or `"sha512"` |
**Return value**: `bytes`, the output keying material OKM of length `length` (HKDF-Expand, RFC 5869).
---
### 3.6 `hkdf`
```python
hkdf(ikm: bytes, salt: bytes = b"", info: bytes = b"",
length: int = 32, hash_name: str = "sha256") -> bytes
```
A one-shot wrapper for `hkdf = hkdf_expand(hkdf_extract(salt, ikm, hash_name), info, length, hash_name)`.
**Example**
```python
from purepycrypto import hkdf
okm = hkdf(b"master", salt=b"salt", info=b"ctx", length=32)
```
---
### 3.7 `scrypt`
```python
scrypt(password, salt, N=4096, r=8, p=1, dklen=32) -> bytes
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `password` | `bytes` | — | password |
| `salt` | `bytes` | — | salt |
| `N` | `int` | `4096` | CPU/memory cost parameter, must be a **power of 2 and > 1** |
| `r` | `int` | `8` | block size parameter, must be ≥ 1 |
| `p` | `int` | `1` | parallelism parameter, must be ≥ 1 |
| `dklen` | `int` | `32` | derived key length (bytes) |
**Return value**: `bytes`, a derived key of length `dklen` (RFC 7914).
**Example**
```python
from purepycrypto import scrypt
dk = scrypt(b"password", b"NaCl", N=1024, r=8, p=16, dklen=64)
```
**Notes**: the implementation includes the Salsa20/8 core, BlockMix, and ROMix. When `N` is invalid (not a power of 2 or ≤ 1) it **returns an error tuple** (`PPYC_ERR_INVALID_KDF_PARAM`).
---
### 3.8 `argon2id`
```python
argon2id(password: bytes, salt: bytes, t: int = 1, m: int = 256, p: int = 1,
tag_length: int = 32, secret: bytes = b"", ad: bytes = b"",
version: int = 0x13) -> bytes
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `password` | `bytes` | — | password |
| `salt` | `bytes` | — | salt (recommended ≥ 16 bytes) |
| `t` | `int` | `1` | iteration (time) count, must be ≥ 1 |
| `m` | `int` | `256` | memory cost, in KiB, must be ≥ `8*p` |
| `p` | `int` | `1` | parallelism, must be ≥ 1 |
| `tag_length` | `int` | `32` | output length (bytes), must be ≥ 4 |
| `secret` | `bytes` | `b""` | optional key (pepper, not written to storage beyond the digest input) |
| `ad` | `bytes` | `b""` | optional associated data |
| `version` | `int` | `0x13` | Argon2 version number (`0x13` = 19) |
**Return value**: `bytes`, an Argon2id tag of length `tag_length` (RFC 9106).
**Example**
```python
from purepycrypto import argon2id
tag = argon2id(
password=b"password",
salt=b"saltsaltsaltsalt",
t=3, m=65536, p=4,
tag_length=32,
)
```
**Notes**: when a parameter is out of range (e.g. `t < 1`, `p < 1`, `m < 8*p`, `tag_length < 4`) it **returns an error tuple** (`PPYC_ERR_INVALID_KDF_PARAM`). This is a **memory-hard** function; a larger `m` is slower and safer.
---
### 3.9 `poly1305_mac`
See [§5.1](#51-poly1305_mac).
---
## 4. aes — AES Symmetric Encryption
### 4.1 The `AES` class
```python
AES(key: bytes)
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | `bytes` | 16 / 24 / 32 bytes → AES-128 / 192 / 256 |
**Example**
```python
from purepycrypto import AES
import os
aes = AES(os.urandom(32)) # AES-256
```
**Notes**: key expansion (T-table implementation) is performed at construction time. An invalid `key` length raises an exception.
---
### 4.2 `encrypt_ecb(data, n_workers=None)` / `decrypt_ecb(data, n_workers=None)`
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `data` | `bytes` | — | plaintext / ciphertext, length must be a multiple of 16 |
| `n_workers` | `int` | `None` | number of parallel workers (`None` = auto) |
**Return value**: `bytes`.
> ⚠️ ECB does not hide data patterns and is **not recommended for general encryption**; use it only for compatibility or deterministic scenarios.
---
### 4.3 `encrypt_cbc(data, iv)` / `decrypt_cbc(data, iv, n_workers=None)`
| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | `bytes` | length must be a multiple of 16 |
| `iv` | `bytes` | 16-byte initialization vector, **must be random and unpredictable** |
| `n_workers` | `int` | only `decrypt_cbc` supports parallelism |
**Example**
```python
iv = os.urandom(16)
ct = aes.encrypt_cbc(b"data" * 4, iv)
pt = aes.decrypt_cbc(ct, iv)
```
---
### 4.4 `encrypt_ctr(data, nonce, n_workers=None)` / `decrypt_ctr(data, nonce, n_workers=None)`
| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | `bytes` | any length |
| `nonce` | `bytes` | **8-byte** nonce (the counter starts at 0) |
| `n_workers` | `int` | supports parallelism |
> ⚠️ **Never repeat the nonce under the same key**, otherwise keystream reuse completely breaks confidentiality.
---
### 4.5 `encrypt_cfb(data, iv)` / `decrypt_cfb(data, iv)`
CFB mode; `iv` is 16 bytes.
### 4.6 `encrypt_ofb(data, iv)` / `decrypt_ofb(data, iv)`
OFB mode; `iv` is 16 bytes.
---
### 4.7 GCM (AEAD)
```python
gcm_encrypt(nonce, plaintext, aad=b"") -> (bytes, bytes) # (ciphertext, tag)
gcm_decrypt(nonce, ct, tag, aad=b"") -> bytes
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `nonce` | `bytes` | — | **12-byte** nonce |
| `plaintext` | `bytes` | — | plaintext (`gcm_encrypt`) |
| `ct` | `bytes` | — | ciphertext (`gcm_decrypt`) |
| `tag` | `bytes` | — | authentication tag (16 bytes) |
| `aad` | `bytes` | `b""` | additional authenticated data |
**Return value**: `gcm_encrypt` returns `(ciphertext, tag)`; `gcm_decrypt` returns the plaintext `bytes`.
**Example**
```python
nonce = os.urandom(12)
ct, tag = aes.gcm_encrypt(nonce, b"secret", aad=b"header")
pt = aes.gcm_decrypt(nonce, ct, tag, aad=b"header")
```
**Notes**: when authentication fails or the ciphertext is tampered with it **returns an error tuple** `(PPYC_ERR_AUTH_FAILED, msg, hint)` and **never returns unauthenticated plaintext** (the historical `DecryptionError` can still be caught). GCM's GHASH can process large messages in parallel (`n_workers`).
---
### 4.8 `encrypt_block(block)` / `decrypt_block(block)`
Encrypt/decrypt a single 16-byte block (the low-level primitive).
> v1.1 adds **AES-GCM-SIV** (nonce-misuse resistant AEAD), see [§13](#13-aes_gcm_siv--aes-gcm-siv).
---
## 5. chacha — ChaCha20 / Poly1305 / AEAD
### 5.1 `poly1305_mac`
```python
poly1305_mac(key32: bytes, msg: bytes) -> bytes
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `key32` | `bytes` | 32-byte one-time key (`r` = the first 16 bytes, `s` = the last 16 bytes) |
| `msg` | `bytes` | message to authenticate |
**Return value**: `bytes`, a 16-byte authenticator (RFC 8439).
**Notes**: `r` is clamped per the Poly1305 rules. **The one-time key must never be reused**.
---
### 5.2 `chacha20poly1305_encrypt` / `chacha20poly1305_decrypt`
```python
chacha20poly1305_encrypt(key: bytes, nonce: bytes, plaintext: bytes,
aad: bytes = b"") -> bytes
chacha20poly1305_decrypt(key: bytes, nonce: bytes, ct_with_tag: bytes,
aad: bytes = b"") -> bytes
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `key` | `bytes` | — | 32-byte key |
| `nonce` | `bytes` | — | **12-byte** nonce |
| `plaintext` | `bytes` | — | plaintext (encryption) |
| `ct_with_tag` | `bytes` | — | ciphertext || 16-byte Tag (decryption) |
| `aad` | `bytes` | `b""` | additional authenticated data |
**Return value**: encryption returns `ciphertext || Tag`; decryption returns the plaintext `bytes`.
**Example**
```python
from purepycrypto import chacha20poly1305_encrypt, chacha20poly1305_decrypt
import os
key, nonce = os.urandom(32), os.urandom(12)
blob = chacha20poly1305_encrypt(key, nonce, b"msg", aad=b"aad")
pt = chacha20poly1305_decrypt(key, nonce, blob, aad=b"aad")
```
**Notes**: authentication failure **returns an error tuple** `(PPYC_ERR_AUTH_FAILED, msg, hint)` (RFC 8439; equivalent to IETF ChaCha20-Poly1305).
---
### 5.3 `xchacha20poly1305_encrypt` / `xchacha20poly1305_decrypt`
```python
xchacha20poly1305_encrypt(key: bytes, nonce: bytes, plaintext: bytes,
aad: bytes = b"") -> bytes
xchacha20poly1305_decrypt(key: bytes, nonce: bytes, ct_with_tag: bytes,
aad: bytes = b"") -> bytes
```
Same as [§5.2](#52-chacha20poly1305_encrypt--chacha20poly1305_decrypt), except that `nonce` is **24 bytes (192-bit)**.
The large nonce space allows nonces to be generated safely at random, without counter management.
**Notes**: internally uses HChaCha20 to derive the subkey from the 24-byte nonce.
---
## 6. x25519 — X25519 Key Exchange
### 6.1 `x25519`
```python
x25519(k: bytes, u: bytes) -> bytes
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `k` | `bytes` | 32-byte scalar (private key) |
| `u` | `bytes` | 32-byte u-coordinate (public key) |
**Return value**: `bytes`, a 32-byte result (RFC 7748).
**Notes**: internally `k` is clamped and the top bit of `u` is cleared; scalar multiplication is constant-time (cswap implementation). When the length of `k` or `u` is not 32 it **returns an error tuple** (`PPYC_ERR_INVALID_LENGTH`).
---
### 6.2 `x25519_base`
```python
x25519_base(scalar: bytes) -> bytes
```
Equivalent to `x25519(scalar, (9).to_bytes(32, "little"))`, i.e. base-point multiplication, yielding the public key.
**Example**
```python
from purepycrypto import x25519_base
import os
priv = os.urandom(32)
pub = x25519_base(priv)
```
---
### 6.3 `x25519_shared`
```python
x25519_shared(priv: bytes, peer_pub: bytes) -> (bytes, bool)
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `priv` | `bytes` | own 32-byte private key |
| `peer_pub` | `bytes` | peer's 32-byte public key |
**Return value**: `(shared, is_zero)` — `shared` is the 32-byte shared secret; `is_zero` being `True` means the result is all zeros (low-order point / forged public key).
**Example**
```python
from purepycrypto import x25519_generate_keypair, x25519_shared
priv_a, pub_a = x25519_generate_keypair()
priv_b, pub_b = x25519_generate_keypair()
shared_a, zero_a = x25519_shared(priv_a, pub_b)
shared_b, zero_b = x25519_shared(priv_b, pub_a)
assert shared_a == shared_b
```
**Notes**: callers **must** check `is_zero` and reject an all-zero result (RFC 7748 §6.1).
---
### 6.4 `x25519_generate_keypair`
```python
x25519_generate_keypair() -> (bytes, bytes)
```
**Return value**: `(priv, pub)`, both 32 bytes. The private key is generated by `os.urandom(32)`.
---
## 7. rsa — RSA Public-Key Cryptography
### 7.1 `RSAPublicKey`
```python
RSAPublicKey(n: int, e: int)
```
| Attribute | Type | Description |
|-----------|------|-------------|
| `n` | `int` | modulus |
| `e` | `int` | public exponent |
| `k` | `int` (attribute) | modulus length in bytes |
| `hash_func` / `h_len` | — | the hash function automatically chosen from the modulus length and its length |
---
### 7.2 `RSAPrivateKey`
```python
RSAPrivateKey(n, e, d, p, q, verify=True)
```
| Attribute | Type | Description |
|-----------|------|-------------|
| `n, e, d, p, q` | `int` | modulus, public exponent, private exponent, the two large prime factors |
| `dp, dq, q_inv` | `int` | CRT parameters |
| `k` | `int` (attribute) | modulus length in bytes |
| `salt_len` | `int` (attribute) | the recommended/default PSS salt length for this key |
**Notes**: an optional self-verification is performed at construction time (`verify=True`); internally it includes **blinding** and CRT + Montgomery acceleration.
---
### 7.3 `rsa_keygen`
```python
rsa_keygen(bits: int = 2048, parallel: bool = True) -> (RSAPublicKey, RSAPrivateKey)
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `bits` | `int` | `2048` | modulus bit size, must be ≥ 521 |
| `parallel` | `bool` | `True` | whether to use multiprocessing to search for the two prime factors in parallel |
**Return value**: `(pub, priv)`.
**Example**
```python
from purepycrypto import rsa_keygen
pub, priv = rsa_keygen(bits=2048)
```
**Notes**: `bits < 521` immediately raises `PPYC_ERR(PPYC_ERR_INVALID_RSA_BITS, ...)` (unable to continue during construction → fatal error). Primality testing uses trial division + Miller-Rabin + strong Lucas (BPSW). A larger `bits` is slower to generate.
---
### 7.4 `rsa_oaep_encrypt` / `rsa_oaep_decrypt`
```python
rsa_oaep_encrypt(message: bytes, pub: RSAPublicKey, label: bytes = b"") -> bytes
rsa_oaep_decrypt(ciphertext: bytes, priv: RSAPrivateKey, label: bytes = b"") -> bytes
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `message` | `bytes` | — | plaintext (length-limited, approx. `k - 2*h_len - 2`) |
| `ciphertext` | `bytes` | — | ciphertext (length must equal `k`) |
| `pub` / `priv` | — | — | public key / private key |
| `label` | `bytes` | `b""` | OAEP label (participates in derivation) |
**Return value**: encryption returns a `k`-byte ciphertext; decryption returns the plaintext.
**Example**
```python
ct = rsa_oaep_encrypt(b"secret", pub, label=b"ctx")
pt = rsa_oaep_decrypt(ct, priv, label=b"ctx")
```
**Notes**: decryption failure (wrong length, label mismatch, invalid padding, etc.) **returns an error tuple** `(PPYC_ERR_DECRYPT_FAILED, msg, hint)` (without distinguishing the specific cause, keeping behavior constant).
---
### 7.5 `rsa_pss_sign` / `rsa_pss_verify`
```python
rsa_pss_sign(message: bytes, priv: RSAPrivateKey, salt_len: int = None) -> bytes
rsa_pss_verify(message: bytes, signature: bytes, pub: RSAPublicKey,
salt_len: int = None) -> bool
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `message` | `bytes` | — | message to sign |
| `signature` | `bytes` | — | signature (length must equal `k`) |
| `priv` / `pub` | — | — | private key / public key |
| `salt_len` | `int` | `None` | PSS salt length; `None` uses the key's default |
**Return value**: `rsa_pss_sign` returns a `k`-byte signature; `rsa_pss_verify` returns a `bool`.
**Example**
```python
sig = rsa_pss_sign(b"document", priv)
assert rsa_pss_verify(b"document", sig, pub) is True
assert rsa_pss_verify(b"tampered", sig, pub) is False
```
**Notes**: verification failure returns `False` (no exception).
---
## 8. der — ASN.1 DER / PEM Serialization
### 8.1 `private_key_to_pkcs1_der`
```python
private_key_to_pkcs1_der(priv: RSAPrivateKey) -> bytes
```
Returns the DER encoding of the PKCS#1 `RSAPrivateKey`.
### 8.2 `public_key_to_pkcs1_der`
```python
public_key_to_pkcs1_der(pub: RSAPublicKey) -> bytes
```
Returns the DER encoding of the PKCS#1 `RSAPublicKey` (`SEQUENCE { n, e }`).
### 8.3 `private_key_to_pkcs8_der`
```python
private_key_to_pkcs8_der(priv: RSAPrivateKey) -> bytes
```
Returns the DER encoding of the PKCS#8 `PrivateKeyInfo` (RFC 5958), with the algorithm identifier `rsaEncryption`.
### 8.4 `public_key_to_spki_der`
```python
public_key_to_spki_der(pub: RSAPublicKey) -> bytes
```
Returns the DER encoding of the SubjectPublicKeyInfo (RFC 5280).
### 8.5 `private_key_to_pem`
```python
private_key_to_pem(priv: RSAPrivateKey) -> str
```
Returns PEM text with the label `PRIVATE KEY` (PKCS#8).
### 8.6 `public_key_to_pem`
```python
public_key_to_pem(pub: RSAPublicKey) -> str
```
Returns PEM text with the label `PUBLIC KEY` (SPKI).
### 8.7 `parse_private_pem`
```python
parse_private_pem(pem: str) -> RSAPrivateKey
```
Parses a PKCS#8 PEM private key (containing PKCS#1) and returns an `RSAPrivateKey`.
**Example**
```python
from purepycrypto import rsa_keygen, private_key_to_pem, parse_private_pem
pub, priv = rsa_keygen(2048)
pem = private_key_to_pem(priv)
priv2 = parse_private_pem(pem)
assert priv2.n == priv.n
```
**Notes**: only RSA PKCS#8 private-key PEM is supported; the legacy PKCS#1 `RSA PRIVATE KEY` label is not supported, nor are algorithms such as EC.
---
## 9. parallel — Multiprocessing Acceleration
The module `purepycrypto.parallel` provides process-pool reuse and shared memory.
| Name | Description |
|------|-------------|
| `_HAS_MP` | `bool`, whether the platform supports `multiprocessing` and `SharedMemory` |
| `_get_pool(n)` | obtain/reuse a process pool of size `n` (internal) |
| `_alloc_shm(data)` / `_free_shm(shm)` | shared-memory allocation and release (internal) |
| `_cleanup_pool()` | registered via `atexit` to clean up the process pool at process exit |
**Notes**: when `_HAS_MP` is `False` or parallelism fails, the library automatically falls back to the serial implementation, with no functional change. It is used by AES's ECB/CBC/CTR/GCM and by RSA generation.
---
## 10. Command-Line Interface
A single command `purepycrypto`, whose behavior is dispatched automatically based on whether arguments are present:
```bash
purepycrypto # no arguments -> interactive TUI
purepycrypto hash --text abc --hex # with arguments -> command-line mode
purepycrypto --help # command-line help
```
When not installed, the equivalent is: `python -m purepycrypto [subcommand]`.
- Interactive TUI: you can select and perform hashing, KDF (PBKDF2/HKDF/scrypt/Argon2id), AES, ChaCha20-Poly1305, X25519, RSA, PEM/DER encoding and decoding, etc.; CN/EN switching is supported (default EN).
- Command-line mode: subcommands `hash` / `hmac` / `kdf` / `aes` / `chacha` / `x25519` / `rsa` / `rand` / `selftest` / `version`.
- CLI exit codes: `0` success / `1` other / `2` `PPYC_ERR` / `3` file not found / `4` argument error.
See [`cli.md`](cli.md) for details.
---
## 11. sha3 — SHA-3 / Keccak / SHAKE
The module `purepycrypto.sha3` implements the FIPS 202 SHA-3 fixed-length hashes, the SHAKE extendable-output functions (XOFs),
and HMAC-SHA3. All are imported through the `purepycrypto.sha3` submodule:
```python
from purepycrypto.sha3 import (
sha3_224, sha3_256, sha3_384, sha3_512,
shake128, shake256, hmac_sha3_256, hmac_sha3_512,
)
```
---
### 11.1 `sha3_224` / `sha3_256` / `sha3_384` / `sha3_512`
```python
sha3_224(data: bytes) -> bytes # 28 bytes
sha3_256(data: bytes) -> bytes # 32 bytes
sha3_384(data: bytes) -> bytes # 48 bytes
sha3_512(data: bytes) -> bytes # 64 bytes
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | `bytes` | data to hash |
**Return value**: `bytes`, a SHA-3 digest of the corresponding length (FIPS 202).
**Example**
```python
from purepycrypto.sha3 import sha3_256, sha3_512
assert sha3_256(b"abc").hex() == (
"3a985da74fe225b2045c172d6bd390bd855f086e3e9d525b46bfe24511431532"
)
assert len(sha3_512(b"abc")) == 64
```
**Notes**: fully compatible with `hashlib.sha3_256`, etc. (already cross-verified).
---
### 11.2 `shake128` / `shake256`
```python
shake128(data: bytes, outlen: int) -> bytes
shake256(data: bytes, outlen: int) -> bytes
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | `bytes` | input data |
| `outlen` | `int` | output length (bytes), must be `>= 0` |
**Return value**: `bytes`, an XOF output of exactly `outlen` bytes.
**Example**
```python
from purepycrypto.sha3 import shake128, shake256
assert shake128(b"abc", 32).hex() == (
"5881092dd818bf5cf8a3ddb793fbcba74097d5c526a6d35f97b83351940f2cc8"
)
assert len(shake256(b"abc", 100)) == 100
```
**Notes**: `outlen < 0` **returns an error tuple** (`PPYC_ERR_INVALID_ARG`); `outlen` may be 0. Compatible with `hashlib.shake_*`.
---
### 11.3 `hmac_sha3_256` / `hmac_sha3_512`
```python
hmac_sha3_256(key: bytes, message: bytes) -> bytes # 32 bytes
hmac_sha3_512(key: bytes, message: bytes) -> bytes # 64 bytes
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | `bytes` | key (any length; if longer than the block size it is first compressed with the corresponding SHA-3) |
| `message` | `bytes` | message |
**Return value**: `bytes`, a 32 / 64-byte HMAC-SHA3 value.
**Example**
```python
from purepycrypto.sha3 import hmac_sha3_256
mac = hmac_sha3_256(b"key", b"message") # 32 bytes
```
**Notes**: the block size `B` is the **rate `r`** of that SHA-3 variant (SHA3-256 → 136, SHA3-512 → 72), consistent with the OpenSSL / `hashlib` / `hmac` convention.
---
### 11.4 Convenient Hex Interfaces
| Function | Signature | Description |
|----------|-----------|-------------|
| `sha3_224_hex` / `sha3_256_hex` / `sha3_384_hex` / `sha3_512_hex` | `sha3_xxx_hex(data: bytes) -> str` | hex string of the corresponding SHA-3 digest |
| `shake128_hex` / `shake256_hex` | `shake_xxx_hex(data: bytes, outlen: int) -> str` | hex string of the XOF output |
---
### 11.5 Low-Level and Constants
| Name | Description |
|------|-------------|
| `keccak_f1600(state)` | Keccak-f[1600] permutation (modifies in place and returns a list of 25 64-bit lanes) |
| `RATE_SHA3_224` / `256` / `384` / `512`, `RATE_SHAKE128` / `256` | the rate `r` (bytes) of each variant |
| `SUFFIX_SHA3` (`0x06`), `SUFFIX_SHAKE` (`0x1F`) | domain-separation suffixes |
---
### 11.6 `sha3_batch` (New in v3.2.0)
```python
sha3_batch(items: list[bytes], algo: str = "sha3_256", n_workers: int = None) -> list[bytes]
```
Batch-hashes **multiple independent messages** (the SHA-3 sponge cannot split a single long message across blocks, so the parallel granularity is "multiple messages").
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `items` | `list[bytes]` | — | list of messages to hash |
| `algo` | `str` | `"sha3_256"` | `sha3_224` / `sha3_256` / `sha3_384` / `sha3_512` / `shake128` / `shake256` |
| `n_workers` | `int` | `None` | `None` auto-detects the CPU count; `1` forces serial |
**Return value**: a list of digests in the same order as `items`; when `algo` is invalid it **returns an error tuple** (`PPYC_ERR_INVALID_ALGO`).
```python
from purepycrypto import sha3_batch
digests = sha3_batch([b"a", b"b", b"c"], algo="sha3_256", n_workers=4)
```
> ⚠️ Multiprocessing on Windows requires the `if __name__ == "__main__":` guard; `sha3_batch` has a built-in fallback, so if multiprocessing fails to start it degenerates to serial automatically.
---
## 12. ed25519 — Ed25519 Digital Signatures
The module `purepycrypto.ed25519` implements **Pure Ed25519** (EdDSA) from RFC 8032.
All are imported through the `purepycrypto.ed25519` submodule:
```python
from purepycrypto.ed25519 import (
ed25519_keygen, ed25519_publickey, ed25519_sign, ed25519_verify,
)
```
---
### 12.1 `ed25519_keygen`
```python
ed25519_keygen() -> (bytes, bytes)
```
**Return value**: a `(seed32, pub32)` tuple. `seed32` is the 32-byte private-key seed (i.e. the RFC 8032 private key),
and `pub32` is the corresponding 32-byte public key (compressed point encoding).
**Example**
```python
from purepycrypto.ed25519 import ed25519_keygen
seed, pub = ed25519_keygen()
assert len(seed) == 32 and len(pub) == 32
```
**Notes**: the seed comes from `os.urandom(32)`; the private key is the seed, and `ed25519_sign` uses that seed directly.
---
### 12.2 `ed25519_publickey`
```python
ed25519_publickey(seed32: bytes) -> bytes
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `seed32` | `bytes` | 32-byte private-key seed |
**Return value**: `bytes`, the 32-byte public key.
**Example**
```python
from purepycrypto.ed25519 import ed25519_publickey
seed = bytes.fromhex(
"9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60")
assert ed25519_publickey(seed).hex() == (
"d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a")
```
---
### 12.3 `ed25519_sign`
```python
ed25519_sign(message: bytes, seed32: bytes) -> bytes
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `message` | `bytes` | message to sign (any length, bytes-like) |
| `seed32` | `bytes` | 32-byte private-key seed |
**Return value**: `bytes`, a 64-byte signature `R || S`.
**Example**
```python
from purepycrypto.ed25519 import ed25519_keygen, ed25519_sign
seed, pub = ed25519_keygen()
sig = ed25519_sign(b"hello", seed)
assert len(sig) == 64
```
**Notes**: Ed25519 is a **deterministic** signature (same seed + same message → same signature), requiring no external randomness source.
---
### 12.4 `ed25519_verify`
```python
ed25519_verify(signature64: bytes, message: bytes, pub32: bytes) -> bool
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `signature64` | `bytes` | 64-byte signature |
| `message` | `bytes` | message |
| `pub32` | `bytes` | 32-byte public key |
**Return value**: `bool`, `True` if verification passes, otherwise `False`.
**Example**
```python
from purepycrypto.ed25519 import ed25519_keygen, ed25519_sign, ed25519_verify
seed, pub = ed25519_keygen()
sig = ed25519_sign(b"hello", seed)
assert ed25519_verify(sig, b"hello", pub) is True
assert ed25519_verify(sig, b"hell0", pub) is False
```
**Notes**: any invalid input (wrong length, invalid point encoding, `S >= L`) or verification failure always returns `False`,
**without raising**; callers must check the return value explicitly.
---
### 12.5 Helper Interfaces and Exceptions
| Name | Signature / Description |
|------|-------------------------|
| `ed25519_scalarmult_base` | `ed25519_scalarmult_base(scalar) -> bytes`, computes `encode(s·B)` (`scalar` is an int or ≤32 bytes) |
| `ed25519_is_valid_publickey` | `ed25519_is_valid_publickey(pub32: bytes) -> bool`, determines whether the public-key encoding can be decoded |
| `Ed25519Error` | parameter / encoding / decoding error exception (a subclass of `PPYC_ERR`, default code `PPYC_ERR_INVALID_ARG`; `ed25519_verify` failure always returns `False`, never raises) |
---
### 12.6 Security Notes
Scalar multiplication uses a fixed 4-bit window + a **masked lookup table** and a 256-round fixed-length main loop, striving to eliminate
secret-dependent branches; but pure-Python big-integer arithmetic cannot guarantee true constant time. See the Ed25519 section of
[`security.md`](security.md) for details.
---
## 13. aes_gcm_siv — AES-GCM-SIV
The module `purepycrypto.aes_gcm_siv` implements the nonce-misuse resistant AEAD of RFC 8452:
`AEAD_AES_128_GCM_SIV` and `AEAD_AES_256_GCM_SIV`. All are imported through the `purepycrypto.aes_gcm_siv` submodule:
```python
from purepycrypto.aes_gcm_siv import (
aes128_gcm_siv_encrypt, aes128_gcm_siv_decrypt,
aes256_gcm_siv_encrypt, aes256_gcm_siv_decrypt,
aes_gcm_siv_encrypt, aes_gcm_siv_decrypt,
)
```
---
### 13.1 `aes128_gcm_siv_encrypt` / `aes128_gcm_siv_decrypt`
```python
aes128_gcm_siv_encrypt(key: bytes, nonce: bytes, plaintext: bytes,
aad: bytes = b"") -> (bytes, bytes)
aes128_gcm_siv_decrypt(key: bytes, nonce: bytes, ct: bytes, tag: bytes,
aad: bytes = b"") -> bytes
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `key` | `bytes` | — | **16-byte** key (key-generating key) |
| `nonce` | `bytes` | — | **12-byte** nonce |
| `plaintext` | `bytes` | — | plaintext (encryption) |
| `ct` | `bytes` | — | ciphertext (decryption) |
| `tag` | `bytes` | — | **16-byte** authentication tag (decryption) |
| `aad` | `bytes` | `b""` | additional authenticated data |
**Return value**: encryption returns `(ct, tag)`; decryption returns the plaintext `bytes`.
**Example**
```python
from purepycrypto.aes_gcm_siv import aes128_gcm_siv_encrypt, aes128_gcm_siv_decrypt
import os
key = os.urandom(16); nonce = os.urandom(12)
ct, tag = aes128_gcm_siv_encrypt(key, nonce, b"hello", aad=b"header")
pt = aes128_gcm_siv_decrypt(key, nonce, ct, tag, aad=b"header")
assert pt == b"hello"
```
**Notes**: when `key` is not 16 bytes or `nonce` is not 12 bytes it **returns an error tuple** (`PPYC_ERR_INVALID_KEY_LEN` / `PPYC_ERR_INVALID_NONCE_LEN`); authentication failure returns `(PPYC_ERR_AUTH_FAILED, msg, hint)`.
---
### 13.2 `aes256_gcm_siv_encrypt` / `aes256_gcm_siv_decrypt`
The signature is the same as §13.1, but `key` must be **32 bytes** (corresponding to `AEAD_AES_256_GCM_SIV`).
---
### 13.3 `aes_gcm_siv_encrypt` / `aes_gcm_siv_decrypt` (unified entry)
```python
aes_gcm_siv_encrypt(key: bytes, nonce: bytes, plaintext: bytes,
aad: bytes = b"") -> (bytes, bytes)
aes_gcm_siv_decrypt(key: bytes, nonce: bytes, ct: bytes, tag: bytes,
aad: bytes = b"") -> bytes
```
Dispatches automatically by `key` length: 16 bytes → AES-128-GCM-SIV; 32 bytes → AES-256-GCM-SIV; any other length **returns an error tuple** (`PPYC_ERR_INVALID_KEY_LEN`).
**Example**
```python
from purepycrypto.aes_gcm_siv import aes_gcm_siv_encrypt, aes_gcm_siv_decrypt
import os
key = os.urandom(32)
nonce = os.urandom(12)
ct, tag = aes_gcm_siv_encrypt(key, nonce, b"secret")
assert aes_gcm_siv_decrypt(key, nonce, ct, tag) == b"secret"
```
---
### 13.4 `polyval`
```python
polyval(h: bytes, data: bytes) -> bytes
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `h` | `bytes` | 16-byte POLYVAL key |
| `data` | `bytes` | length must be a multiple of 16 |
**Return value**: `bytes`, a 16-byte POLYVAL digest (RFC 8452 §3).
**Notes**: an independent public interface, convenient for unit tests / cross-verification; the AEAD internally reuses a precomputed lookup table.
---
### 13.5 Constants
| Name | Value | Description |
|------|-------|-------------|
| `TAG_LEN` | `16` | authentication tag length (bytes) |
| `NONCE_LEN` | `12` | nonce length (bytes) |
---
### 13.6 Security Notes
The principle of nonce-misuse resistance and the **repetition limit** are described in the AES-GCM-SIV section of [`security.md`](security.md).
---
### 13.7 Cache Control (New in v3.2.0)
```python
set_cache_enabled(enabled: bool) -> None
cache_enabled() -> bool
clear_caches() -> None
```
| Function | Description |
|----------|-------------|
| `set_cache_enabled(bool)` | enable / disable the derived-key and POLYVAL table caches (**enabled by default**, performance first) |
| `cache_enabled()` | returns the current cache switch state |
| `clear_caches()` | clears the cached derived keys / table contents |
> If the threat model disallows derived keys residing in memory, you can disable it by calling `set_cache_enabled(False)`;
> after disabling, large-message encryption/decryption no longer uses automatic multiprocessing, and performance drops.
```python
from purepycrypto import set_cache_enabled, cache_enabled, clear_caches
set_cache_enabled(False)
assert cache_enabled() is False
clear_caches()
```
---
## 14. Exceptions and the Error System
See [§0](#0-unified-error-system-new-in-v320) and [`errors.md`](errors.md).
| Name | Type | Description |
|------|------|-------------|
| `PPYC_ERR` / `PPYCError` | exception | **fatal-error** base class; carries `code` / `message` / `suggestion` and `as_tuple()` |
| `CryptoError` | exception | legacy name (subclass of `PPYC_ERR`, default code `PPYC_ERR_INTERNAL`) |
| `DecryptionError` | exception | legacy name (subclass of `PPYC_ERR`, default code `PPYC_ERR_AUTH_FAILED`) |
| `Ed25519Error` | exception | legacy name (subclass of `PPYC_ERR`, default code `PPYC_ERR_INVALID_ARG`) |
| `err` / `ok` / `is_ok` / `is_err` / `raise_ppyc` / `OK_TUPLE` | helpers | **non-fatal error** 3-tuple helpers |
| `ALL_ERROR_CODES` / `PPYC_ERR_PREFIX` | `tuple` / `str` | all error codes / the unified prefix `"PPYC_ERR_"` |
| `PPYC_ERR_*` | `str` | the 41 standard error code constants (general / arguments / key / authentication / encoding / file / environment / algorithm / CLI-TUI) |
| `MASK32 / MASK64 / MASK128` | `int` | bitmask constants |
| `POLY1305_P` | `int` | Poly1305 prime `2^130 - 5` |
| `GHASH_R / R_CONST` | `int` | GCM reduction constant |
---
## 15. Top-Level Export List
> As of v3.2.0, the **error-code constants, SHA-3 / SHAKE, Ed25519, and AES-GCM-SIV are all merged into the top-level exports**, so you can directly
> `from purepycrypto import sha3_256, ed25519_sign, aes_gcm_siv_encrypt, PPYC_ERR_INVALID_KEY_LEN`.
`purepycrypto.__all__`:
**Unified error system**
`PPYC_ERR`, `PPYCError`, `CryptoError`, `DecryptionError`, `Ed25519Error`,
`ok`, `err`, `is_ok`, `is_err`, `raise_ppyc`, `OK_TUPLE`, `PPYCResult`,
`ALL_ERROR_CODES`, `PPYC_ERR_PREFIX` and all `PPYC_ERR_*` error-code constants
**common**
`rand_int`, `rand_bytes`, `MASK32`, `MASK64`, `MASK128`, `POLY1305_P`, `GHASH_R`, `R_CONST`
**hash**
`sha256`, `sha512`, `blake2b`
**sha3**
`sha3_224`, `sha3_256`, `sha3_384`, `sha3_512`, `shake128`, `shake256`,
`hmac_sha3_256`, `hmac_sha3_512`, `sha3_batch`
**kdf**
`hmac_sha256`, `hmac_sha512`, `pbkdf2_hmac`, `hkdf`, `hkdf_extract`, `hkdf_expand`, `scrypt`, `argon2id`
**aes**
`AES`
**aes_gcm_siv**
`aes128_gcm_siv_encrypt`, `aes128_gcm_siv_decrypt`, `aes256_gcm_siv_encrypt`, `aes256_gcm_siv_decrypt`,
`aes_gcm_siv_encrypt`, `aes_gcm_siv_decrypt`, `set_cache_enabled`, `cache_enabled`, `clear_caches`
**chacha**
`poly1305_mac`, `chacha20poly1305_encrypt`, `chacha20poly1305_decrypt`, `xchacha20poly1305_encrypt`, `xchacha20poly1305_decrypt`
**x25519**
`x25519`, `x25519_base`, `x25519_shared`, `x25519_generate_keypair`
**ed25519**
`ed25519_keygen`, `ed25519_publickey`, `ed25519_sign`, `ed25519_verify`
**rsa**
`RSAPublicKey`, `RSAPrivateKey`, `rsa_keygen`, `rsa_oaep_encrypt`, `rsa_oaep_decrypt`, `rsa_pss_sign`, `rsa_pss_verify`
**der**
`private_key_to_pkcs1_der`, `public_key_to_pkcs1_der`, `private_key_to_pkcs8_der`, `public_key_to_spki_der`,
`private_key_to_pem`, `public_key_to_pem`, `parse_private_pem`
**Entry / meta**
`run_tui`, `run_cli`, `main`, `__version__`, `__author__`, `__license__`
```python
import purepycrypto
print(purepycrypto.__version__) # 3.2.0
print(purepycrypto.__author__) # Dvs(DvsXT)
print(purepycrypto.__license__) # MIT
```
---
## 16. kdf2 — Hardened Key Derivation (New in v3.2.0)
The module `purepycrypto.kdf2` provides **more strictly validated** key-derivation interfaces on top of the existing `kdf` (such as a minimum salt
length and Argon2 encoded strings).
| Function | Signature / Description |
|----------|-------------------------|
| `pbkdf2` / `pbkdf2_hmac` | `(password, salt, iterations, dklen, hash_name="sha256", min_salt_len=8) -> bytes` |
| `argon2id_hash` / `argon2i_hash` / `argon2d_hash` | `(password, salt, t=3, m=65536, p=4, tag_length=32, secret=b"", ad=b"", version=19) -> bytes` |
| `argon2id_verify` / `argon2i_verify` / `argon2d_verify` | `(password, salt, tag, ...) -> bool` |
| `argon2id_hash_encoded` / `argon2_verify_encoded` | generate / verify a standard `$argon2id$...` encoded string |
| `scrypt_simple` | `(password, salt, n=16384, r=8, p=1, dklen=32, min_salt_len=8) -> bytes` |
| `hkdf_expand_multi` | `(prk, infos_lengths, hash_name="sha256") -> bytes` |
```python
# example
from purepycrypto import argon2id_hash_encoded, argon2_verify_encoded
enc = argon2id_hash_encoded(b"password", b"salt0123456789ab")
assert argon2_verify_encoded(b"password", enc) is True
```
---
## 17. encoding — Encoding (New in v3.2.0)
The module `purepycrypto.encoding` provides **pure-Python encoding** implementations (byte-for-byte identical to the standard library):
| Function | Description |
|----------|-------------|
| `b64encode` / `b64decode` | Base64 (`altchars` may be passed; `validate` for validation) |
| `b64encode_urlsafe` / `b64decode_urlsafe` | Base64 URL-safe |
| `b64encode_nopad` / `b64decode_nopad` | Base64 without padding |
| `b32encode` / `b32decode` (`b32encode_hex` / `b32decode_hex`) | Base32 |
| `hex_encode` / `hex_decode` (`hex_encode_sep` / `hex_decode_sep`) | Base16 / Hex |
| `b58encode` / `b58decode` | Base58 (Bitcoin alphabet) |
| `b64_encode_bigint` / `b64_decode_bigint` | big-integer base64url |
```python
# example
from purepycrypto import b64encode, b58encode, hex_encode
assert b64encode(b"abc") == b"YWJj"
assert hex_encode(b"\x01\x02") == "0102"
```
---
## 18. rand — CSPRNG Utilities (New in v3.2.0)
The module `purepycrypto.rand` provides **cryptographically secure random (CSPRNG)** utilities, all based on `os.urandom` / `secrets`:
| Function | Description |
|----------|-------------|
| `random_bytes(n)` | `n` bytes of random data |
| `random_int(a, b)` / `random_below(n)` | uniformly random integer in an interval / in `[0, n)` |
| `random_bit()` / `random_bits(k)` | 1 random bit / `k` random bits |
| `token_bytes` / `token_hex` / `token_urlsafe` | token bytes / hex / URL-safe string |
| `random_string(length, alphabet)` | random string over the specified alphabet |
| `random_password(length=16, upper=True, lower=True, digits=True, special=False, exclude="")` | random password |
| `random_uuid4()` | random UUID v4 |
| `random_choice(seq)` / `random_sample(seq, k)` | random choice / sampling |
```python
# example
from purepycrypto import token_hex, random_password, random_uuid4
print(token_hex(4))
print(random_password(16))
print(random_uuid4())
```
---
## ⚠️ Windows Multiprocessing Notes (Important)
Some APIs of this library use a `multiprocessing` process pool for acceleration in **large-input** or **batch** scenarios:
| API | Condition that triggers multiprocessing |
|-----|-----------------------------------------|
| `sha3_batch(items, algo, n_workers)` | `n_workers > 1` and message count ≥ `n_workers × 4` |
| `aes128/256_gcm_siv_encrypt(...)` | input ≥ 128 KB and `n_workers` is `None` (auto) or `> 1` |
**Windows starts child processes via `spawn` (which re-imports the main module), so caller scripts must be wrapped in
`if __name__ == "__main__":`.** Otherwise it raises:
```
RuntimeError: An attempt has been made to start a new process before the
current process has finished its bootstrapping phase.
This probably means that you are not using fork to start your child processes
and you have forgotten to use the proper idiom in the main module:
if __name__ == '__main__':
freeze_support()
...
```
### ✅ Correct pattern
```python
# my_script.py
from purepycrypto import sha3_batch, aes256_gcm_siv_encrypt
def main():
# batch hashing (multiprocessing)
digests = sha3_batch([b"a", b"b", ...], "sha3_256", n_workers=4)
# large-file encryption (automatic multiprocessing)
ct, tag = aes256_gcm_siv_encrypt(key, nonce, big_data)
if __name__ == "__main__": # <- mandatory on Windows
main()
```
### ⛔ Incorrect pattern (raises an error or silently slows down)
```python
from purepycrypto import sha3_batch, aes256_gcm_siv_encrypt
# called directly at module level -- on Windows the child process re-executes this module, causing a RuntimeError
digests = sha3_batch(messages, "sha3_256", n_workers=4)
ct, tag = aes256_gcm_siv_encrypt(key, nonce, big_data)
```
### 🛡️ Two ways to avoid it
1. **Add the `if __name__ == "__main__":` guard** (recommended; you keep the parallel speedup)
2. **Explicitly pass `n_workers=1` to force serial** (no startup overhead; actually faster for small data)
> **Fault tolerance note**: `sha3_batch` has a built-in fallback — if multiprocessing fails to start it automatically degenerates to
> serial computation and returns the correct result, without crashing (but loses the speedup).
> The AES-GCM-SIV multiprocessing branch, however, raises the `RuntimeError` above in the same situation,
> **so be sure to add the guard**.
> **Linux / macOS**: default to `fork` and usually have no such limitation; but for cross-platform consistency,
> it is still strongly recommended to add the `if __name__ == "__main__":` guard uniformly.