Skip to content

C

The read-only C ABI: install the archive from the release or build it from source, open a vault, get a secret, read the per-thread error state, load a project.

7 min read

The C ABI is the foundation of every binding that is not Python, Node or Rust, and it is a complete SDK on its own. The full reference is bindings/README.md (opens in a new tab); this page covers the read-only functions an application needs.

  1. Option 1: Set up with the CLI. Follow the CLI installation guide, then create the vault and set its secret values in your own terminal.
  2. Option 2: Set up with an AI coding agent. Run sourceorrery init --integration all, then ask your agent to set up SourceOrrery for the project without showing values. You keep vault keys and new values private. The agent setup guide works with an existing CLI installation.

The C ABI is not on a package registry: the release archive is the package, or build it from source. The sourceorrery-ffi-0.3.1-<target> archive on the v0.3.1 release (opens in a new tab) holds the shared library (libsourceorrery_ffi.so / .dylib / sourceorrery_ffi.dll with its import library), the static library, include/sourceorrery.h and the C++ header. Download the one for your platform, unpack it, and point the compiler and the loader at it; the example below is get_secret.c from the next section.

Terminal window
$release = "https://github.com/Netizine/sourceorrery/releases/download/v0.3.1"
$dir = "$env:LOCALAPPDATA\sourceorrery-ffi"
Invoke-WebRequest "$release/sourceorrery-ffi-0.3.1-x86_64-pc-windows-msvc.zip" -OutFile sourceorrery-ffi.zip # aarch64-pc-windows-msvc on Arm
Expand-Archive sourceorrery-ffi.zip -DestinationPath $dir -Force
cl /I "$dir\include" get_secret.c /link "$dir\sourceorrery_ffi.dll.lib"
$env:Path = "$dir;$env:Path" # sourceorrery_ffi.dll must be on PATH at run time
.\get_secret.exe

Verify a download against the release’s SHA256SUMS before unpacking it. To link statically on Linux or macOS, use libsourceorrery_ffi.a from the same directory (-lpthread -ldl -lm as well on Linux); on Windows the static sourceorrery_ffi.lib is MSVC-built with the static C runtime, so compile with /MT.

#include <stdio.h>
#include <string.h>
#include "sourceorrery.h"
int main(void) {
const char *vault = "development", *name = "database-password";
so_reader *reader = NULL;
so_bytes properties = {NULL, 0}, value = {NULL, 0};
/* NULL options: SOURCEORRERY_HOME, this machine's key in the OS credential
store, then SOURCEORRERY_RECOVERY_KEY and SOURCEORRERY_RECOVERY_KEY_FILE. */
if (so_reader_open((const uint8_t *)vault, strlen(vault), NULL, 0, NULL, 0, &reader) != SO_STATUS_OK) {
fprintf(stderr, "[%s] %s\n %s\n", so_last_error_code(), so_last_error_message(), so_last_error_hint());
return 1;
}
/* NULL version: the newest accessible version. */
if (so_reader_get(reader, (const uint8_t *)name, strlen(name), NULL, 0, &properties, &value) != SO_STATUS_OK) {
fprintf(stderr, "[%s] %s\n %s\n", so_last_error_code(), so_last_error_message(), so_last_error_hint());
so_reader_close(reader);
return 1;
}
connect(value.ptr, value.len); /* use the bytes ... */
so_bytes_free(&value); /* ... then zeroise and free them */
so_bytes_free(&properties); /* JSON, NUL-terminated: properties.ptr is a C string */
so_reader_close(reader);
return 0;
}
Function Does
so_reader_open(name, options_json, recovery_key, &reader) opens a vault. options_json (nullable) is {"home": "...", "recovery_key_file": "...", "environment": true}; recovery_key (nullable) is tried after this machine’s key in the OS credential store and before the environment. Never a prompt, never the vault’s view check; a secret a connection of the vault stores is read at that provider.
so_reader_get(reader, name, version, &properties_json, &value) the newest accessible version (version NULL) or exactly version
so_reader_properties(reader, name, version, &properties_json) metadata only, policy not applied
so_reader_resolve(reader, reference, &properties_json, &value) sourceorrery://vault/name[/version]
so_reader_descriptor(reader, &json) vault descriptor (no values)
so_reader_close(reader) zeroises the vault key
so_project_load(manifest_path, options_json, recovery_key, &project), so_project_count, so_project_info, so_project_entry(project, i, &entry_json, &value), so_project_free the secrets a sourceorrery.toml declares, like sourceorrery run
so_last_error_code(), so_last_error_message(), so_last_error_hint() per-thread error state after SO_STATUS_ERROR; the hint says what to do
so_bytes_free(&bytes) zeroise and free any output buffer; NULL-safe and idempotent

Conventions: strings in are (ptr, len) UTF-8, never NUL-terminated; buffers out are so_bytes {ptr, len} with a hidden trailing NUL so JSON can be read as a C string; metadata is JSON in the core’s shape (keys vault, name, version, enabled, content_type, tags, not_before, expires_on, created_on, updated_on, recovery_level); values are raw bytes and never appear in JSON, messages or hints. A reader may be used from several threads; error state is per thread.

The write-capable so_vault_* / so_secret_* functions in the same header exist for administrative tooling; an application should not link them (ADR 0005).

You need Git, Rust 1.91.1 or newer installed with rustup, and a C compiler (on Linux also pkg-config and libdbus-1-dev); Building from source has the commands for each platform.

Terminal window
git clone https://github.com/Netizine/sourceorrery
cd sourceorrery
git checkout v0.3.1 # or stay on main for the newest changes
cargo build --release -p sourceorrery-ffi

The libraries land in target/release and the header is crates/sourceorrery-ffi/include/sourceorrery.h: use those two directories where the install steps above use the unpacked archive’s directory and its include/. cargo build --release -p sourceorrery-ffi --no-default-features leaves out the OS credential store and the providers, for hosts that open vaults with their recovery keys only. CI checks that the committed header is exactly what cbindgen generates from the source.

crates/sourceorrery-ffi/examples/get_secret.c is the complete example program. CI compiles it with cc -Wall -Wextra -Werror and MSVC /W4 /WX and runs it against the test vault the CLI creates. To do the same, build the CLI too and run the rest in Bash from the repository root (on Windows, see the MSVC lines below):

Terminal window
cargo build --release -p sourceorrery-cli -p sourceorrery-ffi
eval "$(bash scripts/ci/fixture-vault.sh)" # a throwaway vault, the variables the runner reads, SOURCEORRERY_NATIVE_DIR
mkdir -p build
cc -Wall -Wextra -Werror -I crates/sourceorrery-ffi/include crates/sourceorrery-ffi/examples/get_secret.c \
-L "$SOURCEORRERY_NATIVE_DIR" -lsourceorrery_ffi -o build/get_secret
cc -Wall -Wextra -Werror -I crates/sourceorrery-ffi/include crates/sourceorrery-ffi/examples/conformance.c \
-L "$SOURCEORRERY_NATIVE_DIR" -lsourceorrery_ffi -o build/conformance_c
export LD_LIBRARY_PATH="$SOURCEORRERY_NATIVE_DIR" DYLD_LIBRARY_PATH="$SOURCEORRERY_NATIVE_DIR"
build/get_secret "$SOURCEORRERY_TEST_VAULT" database-password
python tests/conformance/sdk/harness.py --runner c

On Windows the compiler is MSVC’s cl, which is on PATH only in a Developer Command Prompt for VS. Start Git Bash from that prompt ("C:\Program Files\Git\bin\bash.exe") so that cl and the fixture’s variables are in one shell, and replace the two cc lines and the export with these. Git Bash would rewrite /W4 as a path, so the options are written with -, which cl accepts as well:

Terminal window
cl -nologo -W4 -WX -I crates/sourceorrery-ffi/include crates/sourceorrery-ffi/examples/get_secret.c \
-Fe:build/get_secret.exe -Fo:build/ -link "$SOURCEORRERY_NATIVE_DIR/sourceorrery_ffi.dll.lib"
cl -nologo -W4 -WX -I crates/sourceorrery-ffi/include crates/sourceorrery-ffi/examples/conformance.c \
-Fe:build/conformance_c.exe -Fo:build/ -link "$SOURCEORRERY_NATIVE_DIR/sourceorrery_ffi.dll.lib"
export PATH="$(cygpath -u "$SOURCEORRERY_NATIVE_DIR"):$PATH" # sourceorrery_ffi.dll at run time

What the fixture script creates: The SDK test vault. Source: crates/sourceorrery-ffi (opens in a new tab).