Module ffi 

FFI bindings to expose core functionality to other languages (Swift, Kotlin, C, etc.).

Provides functions for key management (import, rotate, export), cryptographic operations, and agent-based signing.

Safety

Functions returning pointers (*mut c_char, *mut u8) allocate memory using libc::malloc. The caller is responsible for freeing this memory using the corresponding ffi_free_* function (ffi_free_str, ffi_free_bytes). Input C string pointers (*const c_char) must be valid, null-terminated UTF-8 strings. Input byte pointers (*const u8/*const c_uchar) must be valid for the specified length. Output length pointers (*mut usize) must be valid pointers. Operations involving raw pointers or calling C functions are wrapped in unsafe blocks.

Constants

FFI_ERR_AGENT_NOT_INITIALIZED

Agent not initialized (call ffi_init_agent first)

FFI_ERR_INVALID_UTF8

Invalid UTF-8 in C string input

FFI_ERR_PANIC

Internal panic occurred

FFI_OK

Successful operation

Functions

c_str_to_str^⚠Deprecated

Converts a C string pointer to a Rust &str. Returns an empty string if the pointer is null. Panics if the C string is not valid UTF-8.

c_str_to_str_safe^⚠

Safely converts a C string pointer to a Rust &str. Returns Ok("") if the pointer is null. Returns Err(FFI_ERR_INVALID_UTF8) if the C string is not valid UTF-8.

ffi_agent_sign^⚠

Signs a message using a key loaded into the FFI agent.

ffi_decrypt_data^⚠

Decrypts data using the given passphrase.

ffi_encrypt_data^⚠

Encrypts data using the given passphrase.

ffi_export_encrypted_key^⚠

Exports the raw encrypted private key bytes associated with the alias. This function does not require a passphrase.

ffi_export_private_key_openssh^⚠

Exports the decrypted private key in OpenSSH PEM format. Requires the correct passphrase to decrypt the key.

ffi_export_private_key_with_passphrase^⚠

Verifies a passphrase against the stored encrypted key for the given alias. If the passphrase is correct, returns a copy of the encrypted key data.

ffi_export_public_key_openssh^⚠

Exports the public key in OpenSSH .pub format. Requires the correct passphrase to decrypt the associated private key first.

ffi_free_bytes^⚠

Frees a byte buffer (unsigned char * / uint8_t *) previously returned by an FFI function in this library (which allocated it using libc::malloc). Does nothing if ptr is null. The len argument is ignored but kept for potential C-side compatibility if callers expect it.

ffi_free_str^⚠

Frees a C string (char *) previously returned by an FFI function in this library (which allocated it using CString::into_raw). Does nothing if ptr is null.

ffi_import_key^⚠

Imports a private key (provided as raw PKCS#8 bytes), encrypts it with the given passphrase, and stores it in the secure storage under the specified local alias, associated with the given controller DID.

ffi_init_agent^⚠

Initializes the FFI agent with the specified socket path.

ffi_key_exists^⚠

Checks if a key with the given alias exists in the secure storage.

ffi_rotate_key^⚠

Rotates the keypair for a given local alias. Generates a new key, encrypts it with the new passphrase, and replaces the existing key in secure storage, keeping the association with the original Controller DID.

ffi_set_encryption_algorithm^⚠

Sets the global encryption algorithm level used by encrypt_keypair. (1 = AES-GCM-256, 2 = ChaCha20Poly1305). Defaults to AES if level is unknown.

ffi_shutdown_agent^⚠

Shuts down the FFI agent, clearing all keys from memory.

malloc_and_copy_bytes^⚠

Helper to allocate memory via malloc, copy Rust slice data into it, set the out_len pointer, and return the raw pointer. Returns null pointer on allocation failure.

result_to_c_int^⚠

Converts a Rust Result<T, E: Display> to a C-style integer error code. Logs the error on failure. Returns 0 on Ok, 1 on Err (general error). Consider more specific error codes in the future.