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.
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.
Project setup options
Section titled “Project setup options”- 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.
- 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.
Install
Section titled “Install”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.
$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 ArmExpand-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.exerelease=https://github.com/Netizine/sourceorrery/releases/download/v0.3.1archive=sourceorrery-ffi-0.3.1-aarch64-apple-darwin # x86_64-apple-darwin on Intelcurl -LO "$release/$archive.tar.gz"sudo mkdir -p /opt/sourceorrery && sudo tar xzf "$archive.tar.gz" --no-same-owner -C /opt/sourceorrery --strip-components=1
cc -I/opt/sourceorrery/include get_secret.c -L/opt/sourceorrery -lsourceorrery_ffi -o get_secretDYLD_LIBRARY_PATH=/opt/sourceorrery ./get_secretrelease=https://github.com/Netizine/sourceorrery/releases/download/v0.3.1archive=sourceorrery-ffi-0.3.1-x86_64-unknown-linux-gnu # aarch64-unknown-linux-gnu on arm64curl -LO "$release/$archive.tar.gz"sudo mkdir -p /opt/sourceorrery && sudo tar xzf "$archive.tar.gz" --no-same-owner -C /opt/sourceorrery --strip-components=1
cc -I/opt/sourceorrery/include get_secret.c -L/opt/sourceorrery -lsourceorrery_ffi -Wl,-rpath,/opt/sourceorrery -o get_secret./get_secretVerify 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.
Get a secret
Section titled “Get a secret”#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;}The read-only surface
Section titled “The read-only surface”| 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).
Building from source
Section titled “Building from source”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.
git clone https://github.com/Netizine/sourceorrerycd sourceorrerygit checkout v0.3.1 # or stay on main for the newest changescargo build --release -p sourceorrery-ffiThe 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):
cargo build --release -p sourceorrery-cli -p sourceorrery-ffieval "$(bash scripts/ci/fixture-vault.sh)" # a throwaway vault, the variables the runner reads, SOURCEORRERY_NATIVE_DIRmkdir -p buildcc -Wall -Wextra -Werror -I crates/sourceorrery-ffi/include crates/sourceorrery-ffi/examples/get_secret.c \ -L "$SOURCEORRERY_NATIVE_DIR" -lsourceorrery_ffi -o build/get_secretcc -Wall -Wextra -Werror -I crates/sourceorrery-ffi/include crates/sourceorrery-ffi/examples/conformance.c \ -L "$SOURCEORRERY_NATIVE_DIR" -lsourceorrery_ffi -o build/conformance_cexport LD_LIBRARY_PATH="$SOURCEORRERY_NATIVE_DIR" DYLD_LIBRARY_PATH="$SOURCEORRERY_NATIVE_DIR"build/get_secret "$SOURCEORRERY_TEST_VAULT" database-passwordpython tests/conformance/sdk/harness.py --runner cOn 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:
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 timeWhat the fixture script creates: The SDK test vault.
Source: crates/sourceorrery-ffi (opens in a new tab).