GALANTHUS / ABI FUNCTION REFERENCE
gln_create_secret
Declared in <galanthus/c_api/gln_capi.h>.
GLN_API gln_status_t GLN_CALL gln_create_secret(
const uint8_t* in_bytes,
size_t in_len,
gln_secret_t** out_secret);
Purpose
Copies caller-supplied opaque bytes into a caller-owned secret handle.
Use the handle for sensitive inputs such as PINs, TANs, or client assertion key material accepted by other C ABI calls.
Return
Returns GLN_OK on success and a non-OK gln_status_t value on failure.
| Type | Nullability | Ownership |
|---|---|---|
gln_status_t | value | value |
Parameters
| Name | Direction | Type | Nullability | Ownership |
|---|---|---|---|---|
in_bytes | input | const uint8_t* | nullable if in_len == 0 | borrowed |
in_len | input | size_t | value | value |
out_secret | output | gln_secret_t** | nonnull | transferred_out |
Input Bytes
in_bytes is borrowed only for the call. On success, the library-owned secret contains its own copy and the caller retains ownership of the input buffer.
The bytes are length-delimited by in_len; they do not need to be NUL-terminated and may contain zero bytes.
The empty secret special case is in_bytes == NULL && in_len == 0. Passing NULL with a nonzero in_len returns GLN_ERR_INVALID_ARG.
Ownership And Wiping
On success, out_secret receives a caller-owned handle that must be released with gln_destroy_secret.
The secret is stored in Secure_string, which wipes its live buffer on destruction and move and uses a wiping allocator for heap storage. This is best-effort zeroing, not a guarantee that every transient source copy outside the handle has been erased.
Wipe or release the caller's original input buffer separately when the host runtime permits it.
Failure Cases
The call returns GLN_ERR_INVALID_ARG when out_secret is NULL or when in_bytes is NULL and in_len is nonzero.
Allocation failure returns GLN_ERR_OUT_OF_MEMORY; unexpected internal failures return GLN_ERR_INTERNAL.