# gmcrypto-c
C ABI for `gmcrypto-core` — pure-Rust SM2 / SM3 / SM4 SDK exposed to
C / C++ / Python (cffi) / Go (cgo) / Zig / Ruby (FFI) callers via a
cdylib + staticlib and a cbindgen-generated header.
The library is a thin shim over [`gmcrypto-core`](../gmcrypto-core);
every cryptographic operation runs in the dudect-gated Rust core,
not in this crate. The C ABI is the language-binding surface only.
## Build
```bash
# cdylib (libgmcrypto_c.so / .dylib / .dll) + staticlib (.a / .lib) +
# rlib (for Rust consumers).
cargo build -p gmcrypto-c --release
```
Output artifacts land in `target/release/`:
- `libgmcrypto_c.so` (Linux) / `libgmcrypto_c.dylib` (macOS) /
`gmcrypto_c.dll` (Windows) — shared library.
- `libgmcrypto_c.a` (Linux/macOS) / `gmcrypto_c.lib` (Windows) —
static library.
## Header
The committed header at [`include/gmcrypto.h`](include/gmcrypto.h)
is the v0.4 C ABI contract. To regenerate after editing the FFI
surface in [`src/lib.rs`](src/lib.rs):
```bash
cargo build -p gmcrypto-c --features regen-header
```
CI verifies the committed header is in sync via `git diff --exit-code`
on every PR.
## Linking against C
```bash
# Compile a C consumer against the shared library.
gcc -I crates/gmcrypto-c/include \
-L target/release -lgmcrypto_c \
examples/sm2_sign.c -o sm2_sign
# Run (set LD_LIBRARY_PATH on Linux / DYLD_LIBRARY_PATH on macOS):
LD_LIBRARY_PATH=target/release ./sm2_sign
```
Static linking:
```bash
gcc -I crates/gmcrypto-c/include \
examples/sm2_sign.c \
target/release/libgmcrypto_c.a \
-o sm2_sign-static
./sm2_sign-static
```
## Failure-mode invariant
Every entry point returning `int` follows the workspace
failure-mode discipline:
- `0` (= `GMCRYPTO_OK`) on success.
- Non-zero (= `GMCRYPTO_ERR` etc.) on failure. **All non-zero
returns are equivalent**; do not distinguish failure modes by
the specific value.
Per Q4.8 in [`docs/v0.4-scope.md`](../../docs/v0.4-scope.md):
distinguishing failure modes (wrong password vs. malformed PEM
vs. inner-key-parse failure) would introduce a password-oracle
attack surface. C consumers MUST treat all non-zero returns as
opaque.
## Output buffer convention
Variable-length output (signatures, ciphertexts, PKCS#8 blobs)
uses the `(out_ptr, out_capacity, out_actual_len)` shape per
Q4.13:
```c
size_t actual = 0;
int rc = gmcrypto_sm2_sign(
key, NULL, 0, /* signer_id = DEFAULT */
msg, msg_len,
sig_buf, sizeof sig_buf,
&actual);
if (rc != GMCRYPTO_OK) {
if (actual > sizeof sig_buf) {
/* too-small buffer; `actual` carries the required length */
} else {
/* other failure */
}
}
```
On too-small buffer: `rc != 0`, `*out_actual_len` set to the
required length, `out_ptr` unmodified.
## Handle ownership
Opaque handles (`gmcrypto_sm2_privkey_t*`, etc.) are heap-allocated
via `Box::into_raw`. Pair every `_new` with exactly one `_free`.
`_free(NULL)` is a no-op (mirrors C's `free()`).
Private-key handles inherit `ZeroizeOnDrop` from gmcrypto-core; the
inner scalar / round keys are zeroized before the heap slot is
freed.
## RNG sourcing
`gmcrypto_sm2_sign`, `gmcrypto_sm2_encrypt`, and
`gmcrypto_sm2_privkey_to_pkcs8` source randomness from
`getrandom::SysRng` internally. C consumers do not pass an RNG
callback in v0.4; a "register custom RNG" entry point may land
post-v0.4 if a use case surfaces.
## `unsafe_code` posture
Per Q4.7 in the scope doc: `gmcrypto-c` cannot satisfy
`unsafe_code = "forbid"` because raw-pointer dereferencing and
`Box::from_raw` are inherent to FFI. Every `unsafe` block carries
a `// SAFETY:` comment naming the caller-side preconditions. The
core crate [`gmcrypto-core`](../gmcrypto-core) itself stays
`unsafe_code = "forbid"`.
## SemVer
The C ABI is the v0.4 baseline. Signature changes in v0.4.x are
breaking ABI changes; v0.5 may break the C ABI without a major
Rust-side bump (since `gmcrypto-c` is a separate crate from
`gmcrypto-core`).
`gmcrypto_sm2_privkey_to_sec1_be` is NOT SemVer-stable across
v0.4.x per Q4.19 — caller MUST zeroize the returned scalar bytes;
documented in the header.