Crate hide_ffi 

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_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_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_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_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_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_verify_message^⚠

Verifies a signature. Returns HIDE_OK only if both halves verify.

hide_version

The library version, as a static NUL-terminated string.