> ## Documentation Index
> Fetch the complete documentation index at: https://docs.everabyte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# C ABI reference

> The complete C interface of the Everabyte Crypto SDK native library — the integration surface for PHP, Java, C#, Go and every other language with a C FFI.

The native library `evb_e2ee_ffi` (built from `bindings/dart/rust` of [everabyte/crypto-sdk](https://github.com/everabyte/crypto-sdk)) exposes the whole protocol through a C ABI. The canonical header is `include/evb_e2ee.h` in the repository — copy it and include it from your FFI declaration of choice.

## Conventions

* **Return**: `0` = OK; negative = error (`-1` bad argument, `-2` crypto failure, `-3` malformed payload, `-4` buffer too small, `-5` JSON failure, `-6` invalid UTF-8, `-7` internal lock).
* **Buffers**: caller-allocated; string outputs are NUL-terminated; byte outputs write the length to `out_len`.
* **Errors**: a short, secret-free message via `evb_last_error(buf, cap)` — call with `cap = 0` first to get the required capacity. `evb_clear_last_error()` resets the slot.
* **UMK material** crosses the boundary as 96 bytes: X25519 secret (32) ‖ ML-KEM-768 seed (64).

## Functions

### Randomness

| Symbol | Signature | Notes |
| - | - | - |
| `evb_random` | `(len u64, out *u8, out_cap u64, out_len *u64) → i32` | OS CSPRNG fill — use it for salts, nonces, DEKs |

### Account key (UMK)

| Symbol | Signature | Notes |
| - | - | - |
| `evb_generate_umk` | `(out *u8, out_cap u64, out_len *u64) → i32` | 96 bytes: sk(32) ‖ seed(64) |
| `evb_umk_public_keys` | `(sk *u8, seed *u8, out_json *char, out_cap u64) → i32` | JSON `{publicKeyX25519: b64(32), publicKeyMlkem: b64(1184)}` |
| `evb_wrap_umk_with_mnemonic` | `(sk, seed, mnemonic *char, salt *u8(16), nonce *u8(12), out_blob *char, out_cap) → i32` | Argon2id v3 blob, cap ≥ 8192 recommended |
| `evb_unwrap_umk_with_mnemonic` | `(blob_b64 *char, mnemonic *char, out *u8, out_cap 96, out_len) → i32` | candidate chain: v3 → RFC 9106 profile → legacy PBKDF2 |
| `evb_wrap_umk_with_device_key` | `(sk, seed, device_secret *u8(32), nonce *u8(12), out_blob, out_cap) → i32` | device secret stays on-device |
| `evb_unwrap_umk_with_device_key` | `(blob_b64, device_secret *u8(32), out, out_cap 96, out_len) → i32` | — |

### File key (DEK) envelopes

| Symbol | Signature | Notes |
| - | - | - |
| `evb_wrap_dek_to_umk` | `(dek *u8(32), pk_x25519 *u8(32), pk_mlkem *u8(1184), out_json *char, out_cap ≥ 4096) → i32` | HPKE v2 envelope JSON |
| `evb_unwrap_dek_from_umk` | `(envelope_json *char, sk, seed, out *u8(32), out_cap, out_len) → i32` | dispatches v2/v1 |

### File content (EVB1)

| Symbol | Signature | Notes |
| - | - | - |
| `evb1_seal_all` | `(dek *u8(32), file_nonce *u8(12), plaintext *u8, len u64, out *u8, out_cap, out_len) → i32` | EVB1 payload = 16 B header + chunks |
| `evb1_open_all` | `(dek, payload *u8, payload_len u64, out *u8, out_cap, out_len) → i32` | output capacity ≥ payload − 16 |

### File names

| Symbol | Signature | Notes |
| - | - | - |
| `evb_derive_wire_alias` | `(sk, seed, real_name *char, out *char, out_cap 128) → i32` | `"evb-"` + hex64 |
| `evb_encrypt_file_name` | `(dek, real_name *char, nonce *u8(12), out_blob *char, out_cap 512) → i32` | b64(nonce ‖ ct ‖ tag) |
| `evb_decrypt_file_name` | `(dek, blob_b64 *char, out *u8, out_cap, out_len) → i32` | out = UTF-8 name bytes |

### Primitives & diagnostics

| Symbol | Signature | Notes |
| - | - | - |
| `evb_hkdf_sha256` | `(ikm, ikm_len, info, info_len, out[32]) → i32` | salt-less HKDF-SHA256 |
| `evb_last_error` | `(buf *char, cap u64) → i32` | `0` written; `> 0` = required capacity |
| `evb_clear_last_error` | `() → i32` | zeroizes the slot |

## Buffer sizing cheat-sheet

| Output | Recommended capacity |
| - | - |
| UMK | 96 |
| public-keys JSON | 2048 |
| mnemonic / device wrap blob | 8192 |
| envelope JSON | 4096 |
| wire alias | 128 |
| encrypted-name blob | 512 |
| EVB1 ciphertext | `plaintextLen + 65536 + 16` |
| decrypted name | real name length + 1 |

## Status codes

| Code | Meaning |
| - | - |
| `0` | OK |
| `-1` | Bad argument (null / wrong size) |
| `-2` | Crypto failure (wrong key, RNG) |
| `-3` | Malformed payload / unsupported version |
| `-4` | Output buffer too small |
| `-5` | JSON serialization failure |
| `-6` | Input not valid UTF-8 |
| `-7` | Internal error-slot lock failure |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.