Skip to main content

Crate hide_ffi

Crate hide_ffi 

Source
Expand description

C ABI for HIDE. Every language binding calls this; none reimplements the cryptography, so there is exactly one implementation to review.

Rules this boundary keeps:

  • Nothing crossing the boundary is trusted: every pointer is checked for null and every length is validated before use.
  • Secret keys never leave Rust. Callers hold an opaque handle; there is no function that exports key material.
  • Buffers allocated here are freed here (hide_buffer_free), because a caller freeing Rust memory with libc free is undefined behaviour.
  • No function unwinds across the boundary. A panic in Rust crossing into C is undefined behaviour, so every entry point catches it.

Structs§

HideBuffer
An owned buffer handed to the caller. Free it with hide_buffer_free.
HideSecretKey
An opaque secret key. The caller only ever holds this pointer; there is no accessor that returns the underlying bytes.
HideSigningIdentity
An opaque signing identity. As with secret keys, no function exports the seed: a binding can sign, and cannot leak.
HideSpentNonces
The verifier’s record of answered challenges. Replay can only be detected by the verifier, so this must outlive a single request.

Constants§

HIDE_ERR_AUTHENTICATION
HIDE_ERR_CHALLENGE_AUDIENCE
The challenge names an audience this verifier does not answer to, or the verifier was built without an audience and so accepts nothing.
HIDE_ERR_CHALLENGE_EXPIRED
Reasons a challenge answer was refused, beyond the generic codes above.
HIDE_ERR_CHALLENGE_REPLAYED
HIDE_ERR_INTERNAL
HIDE_ERR_INVALID_ARGUMENT
HIDE_ERR_MALFORMED
HIDE_ERR_NOT_A_KEY
HIDE_ERR_NO_MATCHING_RECIPIENT
HIDE_ERR_PANIC
HIDE_ERR_TOO_LARGE
HIDE_ERR_UNSUPPORTED
The input uses a version, suite or feature this build does not implement. Distinct from HIDE_ERR_MALFORMED: the bytes are well-formed, just newer.
HIDE_ERR_WRONG_PASSPHRASE
HIDE_KEY_PROTECTED
HIDE_KEY_RAW
Key file kinds reported by hide_inspect_key.
HIDE_MIN_PASSPHRASE_LEN
HIDE_NONCE_LEN
A challenge nonce.
HIDE_OK
Status codes. Zero is success; everything else is a failure the caller must handle. Values are stable across versions: bindings switch on them.
HIDE_PUBLIC_KEY_LEN
HIDE_SIGNATURE_LEN
A hybrid signature: Ed25519 followed by ML-DSA-65.
HIDE_VERIFYING_KEY_LEN
A hybrid verifying key.

Functions§

hide_buffer_empty
An empty buffer, for initialising a local before passing its address in. Callers must start from this rather than from uninitialised memory, because hide_buffer_free reads the pointer it is given.
hide_buffer_free⚠
Frees a buffer produced by this library.
hide_challenge_accept⚠
Accepts a challenge answer exactly once. A valid signature replayed a second time returns HIDE_ERR_CHALLENGE_REPLAYED, which is the entire reason this call takes a spent record rather than being a pure function.
hide_challenge_answer⚠
Answers a challenge, producing a signature over it.
hide_challenge_new⚠
Creates a challenge for a prover to answer. The encoded challenge is not secret and is handed to the prover as-is.
hide_checkpoint_verify⚠
Verifies a signed checkpoint note (spec §16.2) from the log named origin under log_public (1984 bytes). On success writes the tree size and the 32-byte root. Witness cosignatures are ignored here; use the Rust API to demand a witness threshold.
hide_decrypt⚠
Decrypts a container. Nothing is written to out unless the whole payload authenticates, so a caller cannot act on unverified plaintext.
hide_encrypt⚠
Encrypts a buffer for one or more recipients.
hide_epoch_public_key⚠
The public key a sender should encrypt to for a given epoch.
hide_epoch_verify⚠
Verifies a published epoch history and reports how many epochs it holds.
hide_epoch_verify_bound⚠
Verifies that an epoch chain belongs to a pinned identity: the log through its recovery binding, then the epoch binding against the log’s current membership and the exact chain (spec §16.4). out_epochs receives the chain length.
hide_error_message
Human-readable text for a status code. The returned string is static and must not be freed.
hide_identity_generate⚠
Creates an identity and returns it sealed under passphrase, ready to write to disk. One seed backs both encryption and signing, so a caller has a single thing to back up; the seed itself never crosses the boundary.
hide_identity_head⚠
The head of an identity log: one 32-byte value naming this exact history.
hide_identity_trusts_device⚠
Whether a log trusts a device right now. out_trusted is set to 1 or 0.
hide_identity_verify⚠
Replays an identity log and reports how many devices it trusts now.
hide_identity_verify_pinned⚠
Verifies an identity log whose recovery key is established by a recovery binding, against the identity root the caller pinned (spec §16.1). This is the check that defeats an appended Recover under an attacker’s key; a bare hide_identity_verify with a recovery key taken from the same untrusted source does not.
hide_inspect_key⚠
Reports whether a key file is raw or passphrase-protected, without needing the passphrase.
hide_keypair_generate⚠
Generates a key pair. The secret is returned as an opaque handle; the public key is returned as bytes, which are safe to share.
hide_public_key_armor⚠
Encodes a public key as pasteable armored text, returned as UTF-8 bytes.
hide_public_key_dearmor⚠
Decodes armored public-key text back into bytes.
hide_secret_key_free⚠
Releases a secret key. The key material is zeroized.
hide_secret_key_open⚠
Loads a secret key from a file’s bytes. Pass passphrase = NULL for a raw key; a protected key without a passphrase fails rather than guessing.
hide_secret_key_protect⚠
Seals a secret key with a passphrase, producing the bytes to store on disk.
hide_secret_key_public⚠
Derives the public key belonging to a secret key.
hide_sign_message⚠
Signs a message under a caller-chosen context.
hide_signing_identity_free⚠
Releases a signing identity, zeroizing the seed.
hide_signing_identity_open⚠
Loads a signing identity from a key file’s bytes.
hide_signing_identity_public⚠
The shareable verifying key for a signing identity.
hide_spent_nonces_free⚠
Releases the record of spent nonces.
hide_spent_nonces_new⚠
Creates the verifier’s record of spent nonces.
hide_transparency_verify_consistency⚠
Checks a consistency proof: that old_root is the root the log had before it grew to new_root.
hide_transparency_verify_inclusion⚠
Checks an inclusion proof. path is the concatenated 32-byte hashes.
hide_verify_message⚠
Verifies a signature. Returns HIDE_OK only if both halves verify.
hide_version
The library version, as a static NUL-terminated string.