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. PyPI carries
exactly three wheels per release, each tagged py3-none-<platform>, and no
source distribution:
| Wheel platform tag | Machine |
|---|---|
manylinux_2_28_x86_64 |
Linux x86-64 with glibc |
win_amd64 |
Windows x86-64 |
macosx_11_0_arm64 |
macOS 11 or newer on Apple silicon |
The Linux wheel's core is compiled on Ubuntu 24.04 and then given the
manylinux_2_28 tag; the tag is not checked against the binary. If it fails
to load on an older distribution, build the core there.
On anything else (Linux arm64, musl distributions such as Alpine, Intel
macOS, Windows on Arm) pip install hide-protocol finds nothing to install.
There, install the binding from a checkout (pip install ./sdk/python), 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.
A filename must be one portable file name, and encryption refuses anything
else: at most 255 bytes, not . or .., no control characters, none of
< > : " / \ | ? *, no trailing dot or space, and not a Windows device name
such as CON or COM1.
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, ChallengeAudience. Arguments this
binding rejects before calling the core raise ValueError, or TypeError when
the argument is the wrong type (text that is not a str, a decrypt key that
is not a SecretKey).
Text arguments must not contain a NUL character. Passphrases, filenames,
media types, audiences, origins and armored keys cross into the core as C
strings, which end at the first NUL: "longenough\0rest" would otherwise seal
a key under "longenough". Such text raises ValueError instead.
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("app.example") as spent: # must outlive one request
spent.accept(challenge, answer, signer.public_key(), now)
spent.accept(challenge, answer, signer.public_key(), now) # ChallengeReplayedA record must be built with the name this verifier answers to, exactly the
audience the challenge was issued for: an answer minted for another audience —
a challenge relayed from another service — is refused with
ChallengeAudience, and a record built with an empty audience accepts nothing.
context separates uses of one identity so a signature made for one purpose
cannot be replayed as another; never let a remote party choose it. Contexts
beginning with HIDE/ are reserved for the protocol: sign refuses them with
ValueError, while verify accepts any context. 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.
SpentNoncesmay be shared between threads.accepttakes a per-object lock around the native call, which changes the record;ctypesreleases the GIL during that call, so without the lock two threads could both accept the same answer. Keep one record per verifier, not one per thread: a replay is only caught by the record that saw the first answer.SecretKeyandSigningIdentitymay be used from several threads at once; the native calls only read them. Do notclose()one while another thread is still inside a call on it.- Module-level functions hold no shared state.
| 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 loaded from one of two places, always by absolute path:
HIDE_LIBRARY, if it names a file andHIDE_ALLOW_LIBRARY_OVERRIDE=1is also set. Once opted in it is the only candidate: if it cannot be loaded, the import fails rather than falling back to another copy;- otherwise the library bundled inside the package (
hide_ffi.dll,libhide_ffi.dyliborlibhide_ffi.sobeside_binding.py).
The system loader is never asked to search by name, so a library placed in
the working directory, on PATH or on LD_LIBRARY_PATH is not picked up. If
neither place has the library, import hide_protocol raises ImportError
naming the platform and what to install.
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=1The core and the binding must be the same release. At import the binding
compares the core's major.minor.patch with its own and raises ImportError
on any difference: the core enforces checks this binding only documents, so
an older core beside a newer binding would silently lose them.
The binding reads its own version from the installed package's metadata, so
an application that freezes or vendors the package must carry that metadata
with it (PyInstaller: --copy-metadata hide-protocol).
SecretKey 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.
A handle cannot be copied: copy.copy, copy.deepcopy and pickling a
SecretKey, SigningIdentity or SpentNonces raise TypeError. A copy
would share the native object, and releasing either one would free it under
the other. To use a key in a second place, pass the same object, or load the
key file again.
- 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