keybraid 3.0.0

KeyBraid — cross-platform master-secret encryption (XChaCha20-Poly1305)

KeyBraid for Python

Cross-platform master-secret encryption. Encrypt on Python, decrypt on Node.js, Flutter, or Java — and vice versa.

• Cipher: XChaCha20-Poly1305 (AES-256-GCM fallback)
• Key derivation: HKDF-SHA3-512 → SHA3-512 final key
• Spec: ../spec/SPEC-v3.md

Requirements

• Python 3.10+
• uv (recommended) or pip

Installation

cd python
uv sync --extra dev

Quick start

from keybraid import decrypt, encrypt, derive_key1, derive_key2, key_fingerprint

package, master_secret = encrypt("secret message")
plain = decrypt(package, master_secret)

key1 = derive_key1(master_secret)
key2 = derive_key2(master_secret)
fp = key_fingerprint(master_secret)

Optional password protection

from keybraid import protect_master_secret

protected, salt = protect_master_secret(master_secret, "user-password")
package, _ = encrypt("data", protected)

API reference

Function	Description
generate_master_secret()	Random 256-char Base62 master secret
derive_key1(master_secret)	Deterministic Key1
derive_key2(master_secret)	Deterministic Key2
encrypt(plain_text, master_secret=None)	Returns (EncryptedPackage, master_secret)
decrypt(package, master_secret)	Returns plaintext
key_fingerprint(master_secret)	SHA3-256 fingerprint (Base64)
protect_master_secret(master_secret, password)	Argon2id-protected master secret

Encrypted package

{
  "version": "v3",
  "algorithm": "XChaCha20-Poly1305",
  "nonce": "...",
  "ciphertext": "...",
  "tag": "..."
}

Tests

uv run pytest -q
uv run python scripts/vectors_v3.py

Cross-platform vectors: ../spec/test-vectors-v3.json

Security

• Store master_secret separately from the encrypted package.
• Each encrypt() without a master secret generates a new random master secret.