C/C++ FFI Bridge
edgesentry-bridge is a separate Rust crate that exposes Ed25519 signing and
BLAKE3 hash-chain verification as a stable C ABI. C and C++ firmware or
gateways can call the same security logic as the Rust library without a full
rewrite. Downstream languages (including Python) must reach the same ABI or
the eds audit CLI — see Canonicalization contract.
Canonicalization contract
AuditRecord::hash() is defined as:
(see crates/edgesentry-audit/src/record.rs). postcard is schema-driven and
not self-describing: field order, varint integer encoding, fixed-size
arrays without length prefixes, and serialize_bytes length prefixes must
match byte-for-byte.
Downstream implementations MUST NOT reimplement postcard (or otherwise recompute the record hash outside Rust). A subtly wrong reimplementation still succeeds on write and only fails at verification — the worst failure mode for an audit chain.
Canonical hashing, signing, and verification must go through one of:
| Path | Mechanism | Typical use |
|---|---|---|
| Write (in-process) | C ABI: eds_sign_record, eds_record_hash, … |
Hot path from C/C++ or ctypes |
| Verify (out-of-process) | eds audit verify-chain --records-file <path> --public-key-hex <hex> |
Independent re-check; verifier is a separate binary from the writer |
Keeping write and verify in different binaries is intentional: the same Rust implementation is exercised on two process boundaries, so chain validity is not a self-check inside a single address space.
Fallback: if the shared library cannot be loaded, both write and verify
may use the CLI (eds audit sign-record / eds audit verify-chain). See
tools/seal_events.py for a subprocess write example. Prefer the FFI write
path when available.
Building the library
This produces:
| Platform | File |
|---|---|
| macOS | target/release/libedgesentry_bridge.dylib and .a |
| Linux | target/release/libedgesentry_bridge.so and .a |
The header crates/edgesentry-bridge/include/edgesentry_bridge.h is
regenerated automatically by build.rs using cbindgen.
On newer macOS, if ctypes.CDLL / dlopen fails with a mis-aligned
LINKEDIT error on the rustc-produced .dylib, re-link from the staticlib:
cc -dynamiclib -o target/release/libedgesentry_bridge.dylib \
-Wl,-force_load,target/release/libedgesentry_bridge.a \
-framework Security -framework CoreFoundation \
-lSystem -liconv \
-install_name libedgesentry_bridge.dylib
Prebuilt release assets
GitHub Releases ship sibling archives alongside eds for the same
Unix targets used by the CLI matrix:
| Target | Archive |
|---|---|
x86_64-unknown-linux-gnu |
libedgesentry_bridge-{tag}-{target}.tar.gz (.so + header) |
aarch64-apple-darwin |
libedgesentry_bridge-{tag}-{target}.tar.gz (.dylib + header) |
Each archive contains the shared library and edgesentry_bridge.h at the
top level. On macOS, release builds re-link the cdylib with Apple ld from
the staticlib so dlopen succeeds on newer macOS (rustc-produced dylibs can
fail with a mis-aligned LINKEDIT string pool).
Example (Linux CI):
TAG=vX.Y.Z
TARGET=x86_64-unknown-linux-gnu
curl -fsSL \
"https://github.com/edgesentry/edgesentry-rs/releases/download/${TAG}/libedgesentry_bridge-${TAG}-${TARGET}.tar.gz" \
| tar -xz
python3 -c "import ctypes; ctypes.CDLL('./libedgesentry_bridge.so'); print('ok')"
Point consumers at the extracted library with EDS_BRIDGE_LIB (or pass the
path to ctypes.CDLL directly). Windows DLL assets are not published.
Cross-compiling for aarch64 (Linux)
For edge hosts (e.g. Raspberry Pi) that need libedgesentry_bridge.so and
the eds CLI on aarch64-unknown-linux-gnu — this target is not
shipped as a GitHub Release asset; build locally or in CI:
# Install the target once (rustup)
rustup target add aarch64-unknown-linux-gnu
# eds CLI
cargo build -p eds --release --target aarch64-unknown-linux-gnu
# bridge shared library
cargo build -p edgesentry-bridge --release --target aarch64-unknown-linux-gnu
# → target/aarch64-unknown-linux-gnu/release/libedgesentry_bridge.so
# → target/aarch64-unknown-linux-gnu/release/eds
A linker for the target (for example aarch64-linux-gnu-gcc via
cross or a distro cross-toolchain) must be available. CI currently
cross-builds the eds binary only for this target.
Linking from C/C++
macOS:
cc -o my_app main.c \
-I path/to/edgesentry-bridge/include \
-L path/to/target/release \
-ledgesentry_bridge \
-framework Security -framework CoreFoundation
Linux:
cc -o my_app main.c \
-I path/to/edgesentry-bridge/include \
-L path/to/target/release \
-ledgesentry_bridge \
-lpthread -ldl
A ready-made Makefile is provided in
crates/edgesentry-bridge/examples/c_integration/.
API reference
Error codes
| Constant | Value | Meaning |
|---|---|---|
EDS_OK |
0 |
Success |
EDS_ERR_NULL_PTR |
-1 |
A required pointer was NULL |
EDS_ERR_INVALID_UTF8 |
-2 |
String argument is not valid UTF-8 |
EDS_ERR_INVALID_KEY |
-3 |
Key or hash buffer is invalid |
EDS_ERR_STRING_TOO_LONG |
-4 |
String exceeds fixed buffer size |
EDS_ERR_CHAIN_INVALID |
-5 |
Hash-chain verification failed |
EDS_ERR_PANIC |
-6 |
Unexpected internal error |
EDS_ERR_HASH_MISMATCH |
-7 |
Payload hash does not match expected value |
EDS_ERR_BAD_SIGNATURE |
-8 |
Ed25519 signature is invalid |
After any call that returns a negative error code, call eds_last_error_message() to retrieve a human-readable description of the failure.
Record struct
typedef struct {
uint64_t sequence; /* monotonic record index (starts at 1) */
uint64_t timestamp_ms; /* Unix epoch in milliseconds */
uint8_t payload_hash[32]; /* BLAKE3 hash of the raw payload */
uint8_t signature[64]; /* Ed25519 signature over audit context */
uint8_t prev_record_hash[32]; /* hash of preceding record (zero for first) */
uint8_t device_id[256]; /* null-terminated device identifier */
uint8_t object_ref[512]; /* null-terminated storage reference */
} EdsAuditRecord;
EdsAuditRecord is caller-allocated. Rust never calls malloc or
returns a heap pointer — no _free function is needed.
Functions
/* Generate an Ed25519 keypair via OS CSPRNG.
private_key_out and public_key_out must each point to 32 bytes. */
int32_t eds_keygen(uint8_t *private_key_out, uint8_t *public_key_out);
/* Hash payload with BLAKE3 and sign device_id, sequence, timestamp_ms,
prev_record_hash, object_ref, and payload_hash. Fill *out.
Pass NULL for prev_record_hash to use the zero hash (first record). */
int32_t eds_sign_record(const char *device_id,
uint64_t sequence,
uint64_t timestamp_ms,
const uint8_t *payload,
size_t payload_len,
const uint8_t *prev_record_hash,
const char *object_ref,
const uint8_t *private_key,
EdsAuditRecord *out);
/* Compute the per-record hash (used as prev_record_hash for the next record).
hash_out must point to 32 bytes. */
int32_t eds_record_hash(const EdsAuditRecord *record, uint8_t *hash_out);
/* Verify Ed25519 signature. Returns 1 valid, 0 invalid, negative on error. */
int32_t eds_verify_record(const EdsAuditRecord *record,
const uint8_t *public_key);
/* Verify hash links, sequence, and every signature under public_key.
public_key must point to 32 bytes when count is non-zero.
Returns EDS_OK or EDS_ERR_CHAIN_INVALID. */
int32_t eds_verify_chain(const EdsAuditRecord *records,
size_t count,
const uint8_t *public_key);
/* Verify a software update before installation (CLS-03 / STAR-2 R2.2).
Checks BLAKE3(payload) == payload_hash, then verifies the Ed25519
publisher signature over package_id, version, and payload_hash.
package_id and version are null-terminated UTF-8.
payload_hash must point to 32 bytes; signature to 64 bytes;
publisher_key to 32 bytes.
Returns EDS_OK, EDS_ERR_HASH_MISMATCH, EDS_ERR_BAD_SIGNATURE, or
EDS_ERR_INVALID_KEY / EDS_ERR_NULL_PTR / EDS_ERR_INVALID_UTF8 on bad inputs. */
int32_t eds_verify_update(const uint8_t *payload,
size_t payload_len,
const char *package_id,
const char *version,
const uint8_t *payload_hash,
const uint8_t *signature,
const uint8_t *publisher_key);
/* Return a thread-local human-readable description of the last error.
The pointer is valid until the next eds_* call on this thread.
Returns "" when no error has occurred. Never returns NULL. */
const char *eds_last_error_message(void);
Minimal C example
#include "edgesentry_bridge.h"
#include <string.h>
#include <assert.h>
int main(void) {
uint8_t priv_key[32], pub_key[32];
if (eds_keygen(priv_key, pub_key) != EDS_OK) {
fprintf(stderr, "keygen failed: %s\n", eds_last_error_message());
return 1;
}
const char *payload = "check=door,status=ok";
EdsAuditRecord rec;
memset(&rec, 0, sizeof(rec));
int rc = eds_sign_record("lift-01", 1, 1700000000000ULL,
(const uint8_t *)payload, strlen(payload),
NULL, /* zero hash — first record */
"lift-01/1.bin",
priv_key, &rec);
if (rc != EDS_OK) {
fprintf(stderr, "sign_record failed: %s\n", eds_last_error_message());
return 1;
}
assert(eds_verify_record(&rec, pub_key) == 1);
return 0;
}
See the full example in
crates/edgesentry-bridge/examples/c_integration/main.c.
Minimal Python (ctypes) example
Build the library first (cargo build -p edgesentry-bridge --release).
Do not hash or sign records in pure Python — load the shared library.
#!/usr/bin/env python3
"""Minimal ctypes consumer of libedgesentry_bridge (canonical write path)."""
from __future__ import annotations
import ctypes
import sys
from pathlib import Path
EDS_OK = 0
class EdsAuditRecord(ctypes.Structure):
_fields_ = [
("sequence", ctypes.c_uint64),
("timestamp_ms", ctypes.c_uint64),
("payload_hash", ctypes.c_uint8 * 32),
("signature", ctypes.c_uint8 * 64),
("prev_record_hash", ctypes.c_uint8 * 32),
("device_id", ctypes.c_uint8 * 256),
("object_ref", ctypes.c_uint8 * 512),
]
def load_bridge(release_dir: Path) -> ctypes.CDLL:
if sys.platform == "darwin":
name = "libedgesentry_bridge.dylib"
else:
name = "libedgesentry_bridge.so"
lib = ctypes.CDLL(str(release_dir / name))
lib.eds_last_error_message.restype = ctypes.c_char_p
lib.eds_last_error_message.argtypes = []
lib.eds_keygen.restype = ctypes.c_int32
lib.eds_keygen.argtypes = [
ctypes.POINTER(ctypes.c_uint8),
ctypes.POINTER(ctypes.c_uint8),
]
lib.eds_sign_record.restype = ctypes.c_int32
lib.eds_sign_record.argtypes = [
ctypes.c_char_p,
ctypes.c_uint64,
ctypes.c_uint64,
ctypes.POINTER(ctypes.c_uint8),
ctypes.c_size_t,
ctypes.POINTER(ctypes.c_uint8),
ctypes.c_char_p,
ctypes.POINTER(ctypes.c_uint8),
ctypes.POINTER(EdsAuditRecord),
]
lib.eds_record_hash.restype = ctypes.c_int32
lib.eds_record_hash.argtypes = [
ctypes.POINTER(EdsAuditRecord),
ctypes.POINTER(ctypes.c_uint8),
]
lib.eds_verify_chain.restype = ctypes.c_int32
lib.eds_verify_chain.argtypes = [
ctypes.POINTER(EdsAuditRecord),
ctypes.c_size_t,
ctypes.POINTER(ctypes.c_uint8),
]
return lib
def check(lib: ctypes.CDLL, rc: int, what: str) -> None:
if rc < 0:
msg = lib.eds_last_error_message() or b""
raise RuntimeError(f"{what} failed ({rc}): {msg.decode()}")
def main() -> int:
release = Path("target/release") # adjust if needed
lib = load_bridge(release)
priv = (ctypes.c_uint8 * 32)()
pub = (ctypes.c_uint8 * 32)()
check(lib, lib.eds_keygen(priv, pub), "eds_keygen")
payload = b"check=door,status=ok"
rec = EdsAuditRecord()
check(
lib,
lib.eds_sign_record(
b"lift-01",
1,
1_700_000_000_000,
(ctypes.c_uint8 * len(payload)).from_buffer_copy(payload),
len(payload),
None, # first record → zero prev hash
b"lift-01/1.bin",
priv,
ctypes.byref(rec),
),
"eds_sign_record",
)
nxt = (ctypes.c_uint8 * 32)()
check(lib, lib.eds_record_hash(ctypes.byref(rec), nxt), "eds_record_hash")
records = (EdsAuditRecord * 1)(rec)
check(lib, lib.eds_verify_chain(records, 1, pub), "eds_verify_chain")
print("FFI chain OK; next prev_record_hash =", bytes(nxt).hex())
return 0
if __name__ == "__main__":
raise SystemExit(main())
Recommended independent verification: persist an AuditRecord JSON array
(for example via eds audit sign-record / sign-document, or by exporting
records your app already wrote through the Rust types) and re-check
out-of-process:
eds audit verify-chain --records-file /path/to/records.json --public-key-hex <hex>
# prints CHAIN_VALID on success
In-process eds_verify_chain is fine for unit tests; production demos that
claim independent re-verification should use the CLI against a separate
eds binary.
Memory safety conventions
| Rule | Detail |
|---|---|
| No heap allocation | EdsAuditRecord is caller-allocated; Rust never calls malloc |
| NULL-checked | Every pointer argument is checked; EDS_ERR_NULL_PTR returned on failure |
| Fixed-size strings | device_id max 255 chars; object_ref max 511 chars — truncated inputs return EDS_ERR_STRING_TOO_LONG |
| Panic safety | std::panic::catch_unwind wraps every FFI function; a Rust panic returns EDS_ERR_PANIC instead of unwinding across the C boundary |
| Key sizes | private_key and public_key must point to exactly 32 bytes; hash buffers to 32 bytes; signature buffer to 64 bytes |
HSM path
For CLS Level 4, the private key should never exist as an extractable byte
array. The planned HSM integration (#54)
will delegate the eds_sign_record operation to an HSM-backed provider
without exposing key bytes to the caller.