Crate gmcrypto_c 

C ABI for gmcrypto-core (v0.4 W4).

Exposes SM2 (sign/verify, encrypt/decrypt, and — since v1.2 — the GM/T 0003.3 key exchange with key confirmation) / SM3 / SM4 (ECB/CBC/CTR/GCM/CCM/XTS) / HMAC-SM3 / PBKDF2-HMAC-SM3 plus SM2 key import/export to C / C++ / Python / Go / Zig / Ruby callers via opaque handles and a cbindgen-generated header at include/gmcrypto.h.

Failure-mode invariant

Every entry point returning c_int uses the convention:

• 0 = success.
• Non-zero = failure (single-Failed-equivalent per the workspace failure-mode invariant; no enumerated error codes).

C callers MUST treat all non-zero returns as opaque failure. Per Q4.8 in docs/v0.4-scope.md, distinguishing failure modes would introduce a padding-oracle / wrong-password-oracle attack surface.

Output buffer convention

Entry points emitting variable-length output (signatures, ciphertexts, PKCS#8 blobs) follow the (out_ptr, out_capacity, out_actual_len) shape per Q4.13:

• out_ptr: caller-allocated buffer.
• out_capacity: buffer length in bytes.
• out_actual_len: pointer to a size_t where the entry point writes the actual output length (or the required capacity if the buffer was too small).

On too-small buffer: return non-zero, write the required length to *out_actual_len, do not modify out_ptr.

Handle ownership

Opaque handles are heap-allocated Box<T>s returned as *mut T_t. Callers MUST pair each _new with exactly one _free to avoid leaks. Double-free or use-after-free is undefined behaviour (per Box::from_raw’s contract). Calling _free(NULL) is a no-op (mirrors C’s free() semantics).

Constant-time

The FFI shim itself does not introduce new secret-touching paths. Every cryptographic operation runs in gmcrypto-core’s already- dudect-gated code. The null-pointer check at each entry point is constant-time (single integer compare); the return-on-null early-exit has a different timing signature than a successful call, but the attacker who could measure this is local-host and has far more invasive options.

Panic discipline

Every entry point wraps its body in std::panic::catch_unwind. Rust panics unwinding into C are undefined behaviour; on panic we convert to a non-zero return. Per the failure-mode invariant, the C caller cannot distinguish panic from other failure modes.

Structs

gmcrypto_hmac_sm3_t

Opaque handle for a streaming HMAC-SM3 keyed MAC.

gmcrypto_sm2_kx_initiator_t

Opaque handle for an SM2 key-exchange INITIATOR (party A; GM/T 0003.3, v1.2). Born already awaiting the responder’s reply — gmcrypto_sm2_kx_initiator_new samples the ephemeral internally and writes R_A immediately, so no pre-ephemeral state exists in C. Pair with exactly one gmcrypto_sm2_kx_initiator_confirm (which consumes + frees) or one gmcrypto_sm2_kx_initiator_free.

gmcrypto_sm2_kx_responder_t

Opaque handle for an SM2 key-exchange RESPONDER (party B; GM/T 0003.3, v1.2). Lifecycle: gmcrypto_sm2_kx_responder_new → gmcrypto_sm2_kx_responder_respond (takes R_A, emits R_B + S_B) → gmcrypto_sm2_kx_responder_finish (takes S_A, releases K, consumes + frees). Pair with exactly one _finish or one gmcrypto_sm2_kx_responder_free.

gmcrypto_sm2_privkey_t

Opaque handle for an SM2 private key.

gmcrypto_sm2_pubkey_t

Opaque handle for an SM2 public key.

gmcrypto_sm3_t

Opaque handle for a streaming SM3 hasher.

gmcrypto_sm4_cbc_decryptor_t

Opaque handle for a streaming SM4-CBC decryptor (v0.5 W1). Same buffer-back-by-one padding-oracle defense as the v0.3 W5 Rust streaming surface: the most recent decrypted block is held back from emission until gmcrypto_sm4_cbc_decryptor_finalize confirms it is the last block and validates the PKCS#7 padding.

gmcrypto_sm4_cbc_encryptor_t

Opaque handle for a streaming SM4-CBC encryptor (v0.5 W1). Construct with gmcrypto_sm4_cbc_encryptor_new, feed plaintext via gmcrypto_sm4_cbc_encryptor_update, emit the trailing PKCS#7- padded block(s) via gmcrypto_sm4_cbc_encryptor_finalize.

gmcrypto_sm4_gcm_decryptor_t

Opaque handle for a streaming (incremental-input, output-BUFFERED) SM4-GCM decryptor (v0.10 W2). Commit-on-verify: gmcrypto_sm4_gcm_decryptor_update buffers ciphertext and emits nothing; gmcrypto_sm4_gcm_decryptor_finalize_verify releases the full plaintext only after a constant-time tag check. Memory is O(message). Construct with gmcrypto_sm4_gcm_decryptor_new.

gmcrypto_sm4_gcm_encryptor_t

Opaque handle for a streaming (incremental-input) SM4-GCM encryptor (v0.10 W1). Output-streaming: each gmcrypto_sm4_gcm_encryptor_update emits the ciphertext for its chunk; gmcrypto_sm4_gcm_encryptor_finalize emits the 16-byte tag. Construct with gmcrypto_sm4_gcm_encryptor_new; pair with exactly one finalize (which frees the handle) or one gmcrypto_sm4_gcm_encryptor_free.

gmcrypto_sm4_t

Opaque handle for an SM4 cipher (key-scheduled).

Constants

GMCRYPTO_ERR

Generic failure return code. All non-zero returns are equivalent per the failure-mode invariant; this constant exists only as a convenience for C callers that want a named symbol for the not-success case.

GMCRYPTO_OK

Success return code.

GMCRYPTO_SM2_KX_CONFIRM_SIZE

SM2 key-exchange confirmation-tag size in bytes (S_A / S_B are SM3 digests; v1.2). Ephemeral points R_A / R_B use GMCRYPTO_SM2_SEC1_UNCOMPRESSED_SIZE (65).

GMCRYPTO_SM2_SCALAR_SIZE

SM2 private-key scalar size in bytes (32 = 256 bits big-endian).

GMCRYPTO_SM2_SEC1_UNCOMPRESSED_SIZE

SEC1 uncompressed-point size for SM2 public keys (04 || X || Y = 65 bytes).

GMCRYPTO_SM3_DIGEST_SIZE

SM3 digest output size in bytes (32 = 256 bits).

GMCRYPTO_SM4_BLOCK_SIZE

SM4 block size in bytes (16 = 128 bits).

GMCRYPTO_SM4_KEY_SIZE

SM4 key size in bytes (16 = 128 bits).

GMCRYPTO_SM4_XTS_KEY_SIZE

SM4-XTS key size in bytes (32 = Key1 ‖ Key2, two 128-bit keys).

Functions

gmcrypto_hmac_sm3^⚠

Single-shot HMAC-SM3. Writes 32 bytes to out_tag.

gmcrypto_hmac_sm3_finalize^⚠

Consume the streaming HMAC-SM3 instance and write the 32-byte tag to out_tag. The handle is freed by this call.

gmcrypto_hmac_sm3_free^⚠

Free a streaming HMAC-SM3 instance. NULL is a no-op.

gmcrypto_hmac_sm3_new^⚠

Construct a fresh streaming HMAC-SM3 instance keyed with key. Returns NULL on invalid input.

gmcrypto_hmac_sm3_update^⚠

Absorb data into the streaming HMAC-SM3 instance.

gmcrypto_hmac_sm3_verify^⚠

Consume the streaming HMAC-SM3 instance and verify the candidate tag in constant time. Returns GMCRYPTO_OK on match; GMCRYPTO_ERR on mismatch. The handle is freed by this call.

gmcrypto_pbkdf2_hmac_sm3^⚠

Derive out_len bytes via PBKDF2-HMAC-SM3 over (pwd, salt, iterations). Writes into the caller-supplied out buffer.

gmcrypto_sm2_decrypt^⚠

SM2 private-key decrypt of a GM/T 0009-2012 DER ciphertext.

gmcrypto_sm2_decrypt_c1c2c3_legacy^⚠

SM2 private-key decrypt of a legacy raw byte-concat C1 || C2 || C3 ciphertext. Decrypt-only — there is no emit path for the legacy ordering, and there will not be one in any v0.5+ version (per CLAUDE.md “Don’t” entry).

gmcrypto_sm2_decrypt_c1c3c2^⚠

SM2 private-key decrypt of a modern raw byte-concat C1 || C3 || C2 ciphertext. Input length must be at least 65 + 32 + 1 = 98 bytes (C1 + C3 + at least one C2 byte).

gmcrypto_sm2_encrypt^⚠

SM2 public-key encrypt. Output is GM/T 0009-2012 DER. RNG from getrandom::SysRng.

gmcrypto_sm2_encrypt_c1c3c2^⚠

SM2 public-key encrypt; output in the modern raw byte-concat C1 || C3 || C2 format. C1 is the 65-byte SEC1-uncompressed point (0x04 || X || Y); C3 is the 32-byte SM3 MAC; C2 is msg_len bytes of XOR-ed ciphertext. Output length is exactly 65 + 32 + msg_len.

gmcrypto_sm2_encrypt_with_rng^⚠

_with_rng variant of gmcrypto_sm2_encrypt. Identical contract except RNG bytes come from the caller’s rng_callback rather than getrandom::SysRng.

gmcrypto_sm2_kx_initiator_confirm^⚠

Receive the responder’s reply and finish the initiator side: verify S_B (constant-time), and on success write the agreed key (exactly klen bytes, the klen given at _new) to key_out and the initiator’s confirmation tag S_A (GMCRYPTO_SM2_KX_CONFIRM_SIZE = 32 bytes) to out_s_a — send S_A to the responder. r_b is the responder’s ephemeral point (65 bytes); s_b its confirmation tag (32 bytes).

gmcrypto_sm2_kx_initiator_free^⚠

Free an UNCONSUMED initiator handle (abandonment path — e.g. the responder never replied). Safe on NULL. Do NOT call after _confirm (which already consumed + freed the handle).

gmcrypto_sm2_kx_initiator_new^⚠

Construct a key-exchange INITIATOR (party A) and write its ephemeral point R_A (SEC1 uncompressed 04 ‖ X ‖ Y, exactly GMCRYPTO_SM2_SEC1_UNCOMPRESSED_SIZE = 65 bytes) to out_r_a. The handle is created already awaiting the responder’s reply: send out_r_a to the responder, then call gmcrypto_sm2_kx_initiator_confirm with its (R_B, S_B).

gmcrypto_sm2_kx_initiator_new_with_rng^⚠

_with_rng variant of gmcrypto_sm2_kx_initiator_new: identical contract except the ephemeral randomness comes from the caller’s rng_callback (the v0.5 gmcrypto_rng_callback shape) rather than getrandom::SysRng. A null or failing callback returns NULL — indistinguishable from every other failure by design.

gmcrypto_sm2_kx_responder_finish^⚠

Verify the initiator’s confirmation tag S_A (32 bytes, constant-time) and on success write the agreed key (exactly klen bytes, the klen given at _new) to key_out.

gmcrypto_sm2_kx_responder_free^⚠

Free an UNCONSUMED responder handle (abandonment path — e.g. the initiator never confirmed, or a _respond failure spent the handle). Safe on NULL. Do NOT call after _finish (which already consumed + freed the handle). Any held key material is wiped.

gmcrypto_sm2_kx_responder_new^⚠

Construct a key-exchange RESPONDER (party B). local_privkey is B’s static key; peer_pubkey is A’s static public key; ids and klen follow the gmcrypto_sm2_kx_initiator_new conventions (and must match the initiator’s, or the confirmation tags will not verify). The handle then waits for the initiator’s R_A — call gmcrypto_sm2_kx_responder_respond.

gmcrypto_sm2_kx_responder_respond^⚠

Receive the initiator’s R_A (65 bytes) and produce the responder’s reply: writes R_B (65 bytes) to out_r_b and the responder’s confirmation tag S_B (32 bytes) to out_s_b — send both to the initiator, then call gmcrypto_sm2_kx_responder_finish with its S_A. Ephemeral randomness comes from the OS (getrandom::SysRng).

gmcrypto_sm2_kx_responder_respond_with_rng^⚠

_with_rng variant of gmcrypto_sm2_kx_responder_respond: identical contract except the ephemeral randomness comes from the caller’s rng_callback rather than getrandom::SysRng.

gmcrypto_sm2_privkey_free^⚠

Free an SM2 private key. NULL is a no-op. The inner scalar is zeroized via ZeroizeOnDrop before the heap slot is freed.

gmcrypto_sm2_privkey_from_pkcs8^⚠

Load an SM2 private key from a password-encrypted PKCS#8 PEM blob. On success, writes the new handle to *out_key and returns GMCRYPTO_OK. Caller MUST free via gmcrypto_sm2_privkey_free.

gmcrypto_sm2_privkey_new^⚠

Construct an SM2 private key from a 32-byte big-endian scalar. Returns NULL on out-of-range scalar (must be in [1, n-2]).

gmcrypto_sm2_privkey_to_pkcs8^⚠

Emit a password-encrypted PKCS#8 PEM blob containing the SM2 private key. PBES2 / PBKDF2-HMAC-SM3 / SM4-CBC per RFC 8018.

gmcrypto_sm2_privkey_to_sec1_be^⚠

Export the SM2 private key as a 32-byte big-endian scalar.

gmcrypto_sm2_pubkey_free^⚠

Free an SM2 public key. NULL is a no-op.

gmcrypto_sm2_pubkey_new^⚠

Construct an SM2 public key from a SEC1 uncompressed-point byte string (04 || X || Y, 65 bytes). Returns NULL on invalid input (off-curve, identity point, non-uncompressed prefix).

gmcrypto_sm2_pubkey_to_sec1_uncompressed^⚠

Export the SM2 public key as a SEC1 uncompressed-point byte string (04 || X || Y, 65 bytes).

gmcrypto_sm2_sign^⚠

Sign msg with the SM2 private key using the supplied signer_id (or DEFAULT_SIGNER_ID = "1234567812345678" if signer_id_len == 0). Output is DER-encoded SEQUENCE { r, s }. RNG is sourced from getrandom::SysRng.

gmcrypto_sm2_sign_with_rng^⚠

_with_rng variant of gmcrypto_sm2_sign. Identical contract except RNG bytes come from the caller’s rng_callback rather than getrandom::SysRng.

gmcrypto_sm2_verify^⚠

Verify a DER-encoded (r, s) signature against msg using the SM2 public key and signer_id. Returns GMCRYPTO_OK on valid; GMCRYPTO_ERR on invalid or any error.

gmcrypto_sm3_finalize^⚠

Consume the streaming SM3 hasher and write the digest to out_digest. The handle is freed by this call; do not call gmcrypto_sm3_free on it afterwards.

gmcrypto_sm3_free^⚠

Free a streaming SM3 hasher. Passing NULL is a no-op.

gmcrypto_sm3_hash^⚠

Single-shot SM3 hash. Writes 32 bytes to out_digest.

gmcrypto_sm3_new

Construct a fresh streaming SM3 hasher. Returns an opaque handle; must be freed via gmcrypto_sm3_free.

gmcrypto_sm3_update^⚠

Absorb data into the streaming SM3 hasher.

gmcrypto_sm4_cbc_decrypt^⚠

SM4-CBC single-shot decrypt. Single-Failed return on any failure mode (length not multiple of 16, bad padding, key/IV mismatch) per the failure-mode invariant.

gmcrypto_sm4_cbc_decryptor_finalize^⚠

Strip PKCS#7 padding from the held-back final block and emit the last plaintext bytes. Consumes the decryptor — the handle is freed by this call; do NOT call gmcrypto_sm4_cbc_decryptor_free on it afterwards.

gmcrypto_sm4_cbc_decryptor_free^⚠

Free a streaming SM4-CBC decryptor. Passing NULL is a no-op. Do NOT call after gmcrypto_sm4_cbc_decryptor_finalize — that already consumed the handle.

gmcrypto_sm4_cbc_decryptor_new^⚠

Construct a streaming SM4-CBC decryptor. key is exactly 16 bytes; iv is exactly 16 bytes and must match the value used during encryption. Returns NULL on invalid pointer input.

gmcrypto_sm4_cbc_decryptor_update^⚠

Absorb ciphertext into the streaming SM4-CBC decryptor and emit zero or more full plaintext blocks. The final-candidate block is HELD BACK from emission until _finalize validates the trailing padding (buffer-back-by-one padding-oracle defense). Same buffer- size contract as the encryptor’s _update: caller MUST allocate out_capacity >= ct_len + 16 (strict upper bound on bytes emitted in one call). On insufficient capacity returns GMCRYPTO_ERR and the decryptor state is left mid-stream; size the buffer up-front.

gmcrypto_sm4_cbc_encrypt^⚠

SM4-CBC single-shot encrypt with PKCS#7 padding. IV must be caller-supplied and unpredictable (per NIST SP 800-38A Appendix C). Output length is always ((pt_len / 16) + 1) * 16.

gmcrypto_sm4_cbc_encryptor_finalize^⚠

Apply PKCS#7 padding to the buffered tail and emit the final ciphertext block(s). Consumes the encryptor — the handle is freed by this call; do NOT call gmcrypto_sm4_cbc_encryptor_free on it afterwards.

gmcrypto_sm4_cbc_encryptor_free^⚠

Free a streaming SM4-CBC encryptor. Passing NULL is a no-op. Do NOT call after gmcrypto_sm4_cbc_encryptor_finalize — that already consumed the handle.

gmcrypto_sm4_cbc_encryptor_new^⚠

Construct a streaming SM4-CBC encryptor. key is exactly 16 bytes; iv is exactly 16 bytes and MUST be caller-supplied unpredictable bytes (NIST SP 800-38A Appendix C). Returns NULL on invalid pointer input.

gmcrypto_sm4_cbc_encryptor_update^⚠

Absorb plaintext into the streaming SM4-CBC encryptor and emit zero or more full ciphertext blocks. The caller-allocated out buffer MUST be at least pt_len + 16 bytes — that is the upper bound on bytes emitted by a single _update call (a buffered partial block from a prior call can produce one extra block when this call’s input fills it). On insufficient capacity, the call returns GMCRYPTO_ERR and the encryptor state is left mid- stream (the ciphertext bytes that would have been emitted are lost). Callers should size the output buffer correctly up-front.

gmcrypto_sm4_ccm_decrypt^⚠

SM4-CCM single-shot decrypt. Input ct is ct_len bytes (ciphertext ‖ tag); tag_len must match the value used at encrypt time. pt_out receives ct_len - tag_len bytes. GMCRYPTO_ERR on any failure (single failure mode).

gmcrypto_sm4_ccm_encrypt^⚠

SM4-CCM single-shot encrypt. tag_len must be in {4, 6, 8, 10, 12, 14, 16}; nonce_len in [7, 13]. out receives pt_len + tag_len bytes (ciphertext ‖ tag). Invalid parameters → GMCRYPTO_ERR.

gmcrypto_sm4_decrypt_block^⚠

Decrypt one 16-byte block in place under the SM4 cipher.

gmcrypto_sm4_encrypt_block^⚠

Encrypt one 16-byte block in place under the SM4 cipher.

gmcrypto_sm4_free^⚠

Free an SM4 cipher. NULL is a no-op.

gmcrypto_sm4_gcm_decrypt^⚠

SM4-GCM single-shot decrypt with a 16-byte tag. pt_out receives ct_len bytes. Returns GMCRYPTO_OK only if the tag verifies; GMCRYPTO_ERR on any failure (single failure mode).

gmcrypto_sm4_gcm_decrypt_with_tag_len^⚠

SM4-GCM decrypt with a truncated tag. tag is tag_len bytes; tag_len must be in {4, 8, 12, 13, 14, 15, 16}. pt_out receives ct_len bytes. GMCRYPTO_ERR on any failure.

gmcrypto_sm4_gcm_decryptor_finalize_verify^⚠

Verify tag (tag_len bytes; the length is validated against the NIST-permitted set {4, 8, 12, 13, 14, 15, 16}) and, on success, write the full decrypted plaintext (length == total ciphertext fed) to (out, out_capacity, out_actual_len).

gmcrypto_sm4_gcm_decryptor_free^⚠

Free a streaming SM4-GCM decryptor without verifying (abort path). NULL is a no-op. Do NOT call after gmcrypto_sm4_gcm_decryptor_finalize_verify.

gmcrypto_sm4_gcm_decryptor_new^⚠

Construct a streaming SM4-GCM decryptor. Same parameter contract as gmcrypto_sm4_gcm_encryptor_new. Returns NULL on invalid input.

gmcrypto_sm4_gcm_decryptor_update^⚠

Buffer ct_len bytes of ciphertext and fold them into the running GHASH. Emits no plaintext (commit-on-verify) — there is no output parameter. Returns GMCRYPTO_ERR only on null handle or invalid input pointer; a length-ceiling overflow is latched and surfaces as GMCRYPTO_ERR at gmcrypto_sm4_gcm_decryptor_finalize_verify.

gmcrypto_sm4_gcm_encrypt^⚠

SM4-GCM single-shot encrypt. ct_out receives pt_len bytes (via the capacity/actual-len convention); tag_out receives exactly 16 bytes. Returns GMCRYPTO_OK / GMCRYPTO_ERR.

gmcrypto_sm4_gcm_encrypt_with_tag_len^⚠

SM4-GCM encrypt with a truncated tag. tag_len must be in {4, 8, 12, 13, 14, 15, 16}; tag_out receives tag_len bytes. Invalid tag_len → GMCRYPTO_ERR.

gmcrypto_sm4_gcm_encryptor_finalize^⚠

Finish and emit the full 16-byte tag. Consumes the encryptor — the handle is freed by this call (even on error); do NOT call gmcrypto_sm4_gcm_encryptor_free on it afterwards. tag_out must be valid for exactly 16 bytes.

gmcrypto_sm4_gcm_encryptor_finalize_with_tag_len^⚠

Finish and emit a truncated tag of tag_len bytes (MSB_t per NIST SP 800-38D §5.2.1.2). tag_len must be in {4, 8, 12, 13, 14, 15, 16} (else GMCRYPTO_ERR). Consumes the encryptor — the handle is freed by this call (even on error); do NOT call gmcrypto_sm4_gcm_encryptor_free afterwards.

gmcrypto_sm4_gcm_encryptor_free^⚠

Free a streaming SM4-GCM encryptor without finalizing (abort path). Passing NULL is a no-op. Do NOT call after any _finalize* — those already consumed the handle.

gmcrypto_sm4_gcm_encryptor_new^⚠

Construct a streaming SM4-GCM encryptor. key is exactly 16 bytes; nonce is nonce_len bytes (12 = canonical; other lengths invoke the extra GHASH J0-derivation per NIST SP 800-38D §8.2.2); aad is the full associated data (the message header, supplied up-front). Returns NULL on invalid pointer/length input. Nonce uniqueness is the caller’s responsibility — reusing (key, nonce) is catastrophic for GCM.

gmcrypto_sm4_gcm_encryptor_update^⚠

Encrypt pt_len bytes of plaintext, emitting the ciphertext for this chunk (length == pt_len; GCM does not pad or buffer). The out buffer MUST be at least pt_len bytes; on insufficient capacity returns GMCRYPTO_ERR (and the required length is written to *out_actual_len), and the encryptor state is left mid-stream (the chunk’s ciphertext is lost — size the buffer correctly). Returns GMCRYPTO_ERR once the cumulative plaintext would exceed the GCM ceiling (2^36 − 32 bytes); the encryptor is poisoned and all later calls also return GMCRYPTO_ERR.

gmcrypto_sm4_new^⚠

Construct an SM4 cipher from a 16-byte key. Returns NULL on null key.

gmcrypto_sm4_xts_decrypt^⚠

SM4-XTS single-shot decrypt (GB/T 17964-2021, xts_standard=GB). Inverse of gmcrypto_sm4_xts_encrypt with the same argument shape; out receives data_len bytes. Returns GMCRYPTO_OK / GMCRYPTO_ERR (same single failure mode). XTS is unauthenticated, so decrypt cannot detect tampering — it only fails on invalid parameters (length / weak key / buffer).

gmcrypto_sm4_xts_decrypt_sectors^⚠

SM4-XTS in-place multi-sector decrypt (GB/T 17964-2021, xts_standard=GB). Inverse of gmcrypto_sm4_xts_encrypt_sectors under the same (key, sector_size, start_sector); same in-place contract, single failure mode, and buf-untouched-on-error guarantee. XTS is unauthenticated, so decrypt cannot detect tampering — it only fails on invalid parameters.

gmcrypto_sm4_xts_encrypt^⚠

SM4-XTS single-shot encrypt (GB/T 17964-2021, xts_standard=GB). key is exactly GMCRYPTO_SM4_XTS_KEY_SIZE (32) bytes (Key1 ‖ Key2); tweak is exactly GMCRYPTO_SM4_BLOCK_SIZE (16) raw bytes (the data-unit/sector identifier — caller-unique per key). out receives data_len bytes (length-preserving) via the capacity/actual-len convention. Returns GMCRYPTO_OK / GMCRYPTO_ERR (single failure mode: data_len outside [16, 16 MiB], Key1 == Key2, null pointer, or buffer too small — in which case *out_actual_len is set to the required length). Confidentiality only — SM4-XTS does not authenticate.

gmcrypto_sm4_xts_encrypt_sectors^⚠

SM4-XTS in-place multi-sector encrypt (GB/T 17964-2021, xts_standard=GB). key is exactly GMCRYPTO_SM4_XTS_KEY_SIZE (32) bytes (Key1 ‖ Key2); buf is a contiguous run of buf_len / sector_size equal-size sectors transformed in place (buf_len must be a whole multiple of sector_size). Sector i is encrypted under tweak = little-endian-128(start_sector + i) — the data-unit / LBA convention; sector numbers must be unique within the XTS-key namespace (caller’s contract). start_sector is a uint64_t (LBA width), so the addressable range is [0, 2^64 − 1]; for the full u128 sector space use the Rust mode_xts::encrypt_sectors API. Returns GMCRYPTO_OK / GMCRYPTO_ERR (single failure mode: sector_size outside [16, 16 MiB] or not a multiple of 16, buf_len not a whole multiple of sector_size, Key1 == Key2, or null pointer). buf is untouched on GMCRYPTO_ERR. buf_len == 0 is a vacuous GMCRYPTO_OK (but the key is still validated, so empty + weak key → GMCRYPTO_ERR). Confidentiality only — SM4-XTS does not authenticate.

gmcrypto_version

Returns a NUL-terminated string with the gmcrypto-c crate version, tracking Cargo’s CARGO_PKG_VERSION at build time (e.g. "1.0.0"). The returned pointer is to a static &'static CStr and must NOT be freed by the caller.

Type Aliases

gmcrypto_rng_callback

C ABI function pointer for caller-supplied RNG. Returns 0 on success and non-zero on failure. See module-level docs for the full contract.