Experimental and unaudited. HIDE is hybrid post-quantum (X25519 + ML-KEM-768, Ed25519 + ML-DSA-65). See the security policy.
Python 3.10+ binding, through ctypes, to the same Rust core (crates/hide-ffi)
that the CLI and every other HIDE SDK use. This package contains no cryptography
of its own.
pip install hide-protocolThe wheel bundles the compiled core, so no toolchain is needed. Wheels are
published for three platforms: manylinux_2_28_x86_64, win_amd64 and
macosx_11_0_arm64. On any other platform, build the core yourself and point
the binding at it (see Native library).
import hide_protocol as hide
with hide.SecretKey.generate() as secret:
box = hide.encrypt(b"hello", [secret.public_key()], filename="note.txt")
opened = hide.decrypt(box, secret)
assert opened.data == b"hello" and opened.filename == "note.txt"
tampered = bytearray(box)
tampered[-1] ^= 0x01
try:
hide.decrypt(bytes(tampered), secret)
except hide.AuthenticationError as e:
print("refused:", e) # refused: authentication failed; the data was alteredencrypt takes 1..64 recipient public keys, each exactly PUBLIC_KEY_LEN
(1216) bytes, plus optional filename= and media_type=. decrypt returns a
Decrypted with .data, .filename and .media_type; nothing is returned
unless the whole payload authenticates. The filename is attacker-controlled:
never use it to choose an output path.
Keys on disk: secret.protect(passphrase) returns a sealed key file
(MIN_PASSPHRASE_LEN is 8, and there is no escrow); SecretKey.load(data, passphrase) opens one; inspect_key(data) reports "raw" or "protected"
without the passphrase. armor_public_key / dearmor_public_key give a public
key a pasteable text form.
Errors: every failure is a subclass of hide.HideError — AuthenticationError
(altered, or not a container), its subclass Malformed (did not decode at
all), WrongPassphrase, NoMatchingRecipient, NotAKeyFile,
ChallengeExpired, ChallengeReplayed. Arguments this binding rejects before
calling the core raise ValueError.
One seed backs both encryption and signing, so there is a single thing to back up.
sealed = hide.SigningIdentity.generate("correct horse battery") # store this
with hide.SigningIdentity.load(sealed, "correct horse battery") as signer:
context, message = b"myapp/v1 release", b"payload"
signature = signer.sign(context, message) # 3373 bytes
hide.verify(signer.public_key(), context, message, signature) # None, or raises
# Challenge/response: good once, here, now.
import time
now = int(time.time())
challenge = hide.new_challenge("app.example", now, 60)
answer = signer.answer(challenge)
with hide.SpentNonces() as spent: # must outlive one request
spent.accept(challenge, answer, signer.public_key(), now)
spent.accept(challenge, answer, signer.public_key(), now) # ChallengeReplayedcontext separates uses of one identity so a signature made for one purpose
cannot be replayed as another; never let a remote party choose it. verify
returns None and raises AuthenticationError on failure rather than
returning a boolean a caller could forget to check. A key file written before
signatures existed carries no signing seed and raises NotAKeyFile.
| Function | Returns |
|---|---|
verify_identity(log, recovery_key) |
int — how many devices the log trusts now |
identity_trusts_device(log, recovery_key, device_public_key) |
bool — membership, after verifying the log |
identity_head(log, recovery_key) |
32 bytes naming this exact history |
verify_epoch_chain(chain) |
int — how many epochs it holds |
epoch_public_key(chain, epoch) |
the public key to encrypt to for epoch |
verify_inclusion(leaf, index, size, path, root) |
None |
verify_consistency(old_size, new_size, path, old_root, new_root) |
None |
verify_identity_pinned(log, recovery_binding, pinned_root) |
int — devices trusted now, only if the log is the identity under the pinned 32-byte root |
verify_epoch_chain_bound(log, recovery_binding, pinned_root, chain, epoch_binding) |
int — epochs, only if a device the log trusts signed this chain |
verify_checkpoint(note, origin, log_public) |
(size, root) — tree size and 32-byte root from a signed checkpoint note |
A cryptographic verify raises on failure (Malformed if the bytes did not
decode, AuthenticationError if they decoded but did not verify) and never
returns False. The one boolean is identity_trusts_device: the log is
verified first, so False means "not a member", never "did not verify".
The pinned checks are what a relying party uses: pinned_root is obtained out
of band, and recovery_binding establishes the recovery key, so a log extended
by a Recover under a stranger's key raises AuthenticationError. A pinned root
that is not 32 bytes raises ValueError.
The core is located in this order:
HIDE_LIBRARY, if it names a file andHIDE_ALLOW_LIBRARY_OVERRIDE=1is also set;- the library bundled inside the package (
hide_ffi.dll,libhide_ffi.dyliborlibhide_ffi.sobeside_binding.py); - the system loader, by name.
HIDE_LIBRARY is a development override: it replaces the entire cryptographic
core, so a single settable environment variable must not be enough to redirect
it. Against a local build:
cargo build --release -p hide-ffi
export HIDE_LIBRARY="$PWD/target/release/libhide_ffi.so" # hide_ffi.dll / libhide_ffi.dylib
export HIDE_ALLOW_LIBRARY_OVERRIDE=1SecretKey and SigningIdentity are opaque handles. The seed bytes stay in the
native library and this SDK exposes no accessor for them; repr() shows only
whether the handle is open. Release a handle with close() or a with block
(it is also released on garbage collection, but that leaves key material in
memory for an unbounded time). A closed handle raises ValueError on use.
- Unaudited. Do not protect data you cannot afford to lose or expose.
- An identity is a key, not a person: a verified signature proves possession of a seed, nothing about who holds it.
- Full threat model: docs/threat-model.md.
- Repository: https://github.com/hide-protocol/hide
- Documentation: docs/
- Specification: spec/hide-1.md
- CHANGELOG