initial commit

Signed-off-by: Kamal Tufekcic <kamal@lo.sh>

soliton_capi/cbindgen.toml

@@ -0,0 +1,81 @@
+language = "C"
+header = "/* Warning: this file is autogenerated by cbindgen. Do not modify manually. */"
+include_guard = "SOLITON_H"
+after_includes = """
+/* ─── Usage contract ──────────────────────────────────────────────────── */
+/*
+ * THREAD SAFETY: Opaque handles (SolitonRatchet*, SolitonKeyRing*,
+ * SolitonCallKeys*) are NOT thread-safe. Concurrent access to the same
+ * handle from multiple threads is undefined behavior. Callers must
+ * serialize access externally (e.g., mutex) or use one handle per thread.
+ * Stateless functions (sha3_256, hmac, hkdf, aead, xwing, identity,
+ * verification_phrase) are safe to call concurrently with distinct buffers.
+ *
+ * OWNERSHIP: Opaque handle _free functions take a double pointer
+ * (e.g., `soliton_ratchet_free(&ptr)`) and set the handle to NULL after
+ * freeing, making double-free a safe no-op. Cross-type free (e.g., passing
+ * a SolitonRatchet** to soliton_keyring_free) is undefined behavior.
+ *
+ * Compound struct _free functions (soliton_encrypted_message_free,
+ * soliton_kex_initiated_session_free, soliton_kex_received_session_free,
+ * soliton_decoded_session_init_free) take a single pointer and free
+ * internal buffers. They do NOT null the caller's pointer (the struct is
+ * caller-allocated, not library-allocated). Repeated calls are safe (no-op)
+ * because internal buffers are nulled after freeing.
+ *
+ * FIXED-SIZE PARAMETERS: Functions accepting raw pointers for fixed-size
+ * inputs (keys, nonces, fingerprints) require exactly the documented number
+ * of bytes. Passing a shorter buffer is undefined behavior (out-of-bounds
+ * read). Required sizes are documented per function and as SOLITON_*_SIZE
+ * constants below.
+ */
+
+/* ─── Size constants (bytes) ──────────────────────────────────────────── */
+#define SOLITON_PUBLIC_KEY_SIZE    3200
+#define SOLITON_SECRET_KEY_SIZE   2496
+#define SOLITON_XWING_PK_SIZE     1216
+#define SOLITON_XWING_SK_SIZE     2432
+#define SOLITON_XWING_CT_SIZE     1120
+#define SOLITON_ED25519_SIG_SIZE  64
+#define SOLITON_HYBRID_SIG_SIZE   3373
+#define SOLITON_MLDSA_SIG_SIZE    3309
+#define SOLITON_SHARED_SECRET_SIZE 32
+#define SOLITON_FINGERPRINT_SIZE  32
+#define SOLITON_AEAD_TAG_SIZE     16
+#define SOLITON_AEAD_NONCE_SIZE   24
+#define SOLITON_CALL_ID_SIZE      16
+#define SOLITON_STREAM_HEADER_SIZE  26
+#define SOLITON_STREAM_CHUNK_SIZE   1048576
+#define SOLITON_STREAM_ENCRYPT_MAX  1048849
+
+/* ─── Error codes ─────────────────────────────────────────────────────── */
+#define SOLITON_OK                    0
+#define SOLITON_ERR_INVALID_LENGTH   -1
+#define SOLITON_ERR_DECAPSULATION    -2
+#define SOLITON_ERR_VERIFICATION     -3
+#define SOLITON_ERR_AEAD             -4
+#define SOLITON_ERR_BUNDLE           -5
+#define SOLITON_ERR_TOO_MANY_SKIPPED -6
+#define SOLITON_ERR_DUPLICATE        -7
+/* -8 reserved (was SOLITON_ERR_SKIPPED_KEY, removed) */
+#define SOLITON_ERR_ALGORITHM        -9
+#define SOLITON_ERR_VERSION          -10
+#define SOLITON_ERR_DECOMPRESSION    -11
+#define SOLITON_ERR_INTERNAL         -12
+#define SOLITON_ERR_NULL_POINTER     -13
+#define SOLITON_ERR_FLAGS            -14
+#define SOLITON_ERR_CHAIN_EXHAUSTED  -15
+#define SOLITON_ERR_CRYPTO_VERSION   -16
+#define SOLITON_ERR_INVALID_DATA     -17
+#define SOLITON_ERR_CONCURRENT_ACCESS -18
+"""
+
+[parse]
+parse_deps = false
+
+[export]
+# Exclude the Rust error enum since error codes are in the header #defines above
+exclude = ["SolitonError"]
+
+[enum]
+prefix_with_name = true