gln_create_key_store

Declared in <galanthus/c_api/gln_capi.h>.

GLN_API gln_status_t GLN_CALL gln_create_key_store(
    const gln_key_store_vtable_t* in_vtable,
    gln_key_store_t**             out_store,
    gln_error_t*                  out_error);

• Family: Create and open functions
• Return type: gln_status_t

Purpose

Creates a caller-owned EBICS key-store handle from a caller-supplied vtable.

Use this constructor when EBICS client keys, bank keys, certificates, or signing operations live in host-owned storage such as an HSM, secure enclave, KMS, or application database.

Return

Returns GLN_OK on success and a non-OK gln_status_t value on failure.

Parameters

Vtable Contract

Every callback pointer in gln_key_store_vtable_t is required; only user_data may be NULL. The handle stores a copy of the vtable values and passes user_data unchanged to each callback.

Client-key lifecycle callbacks: generate_keys, has_keys, and reset_client_keys. has_keys writes a nonzero value only when the required EBICS client keys are present.

Public client material callbacks: authentication_public_key_json, encryption_public_key_json, signature_public_key_json, authentication_certificate_der, encryption_certificate_der, and signature_certificate_der.

Cryptographic operation callbacks: sign_authentication, sign_order, and decrypt_transaction_key.

Bank-key staging callbacks: store_bank_keys_json, load_bank_keys_json, store_pending_bank_keys_json, load_pending_bank_keys_json, promote_pending_bank_keys_json, reset_bank_keys, and clear_pending_bank_keys.

Allocator callback: free_buffer, used for all non-NULL strings and byte buffers returned by output callbacks.

Callback Ownership

The public-key JSON callbacks and bank-key load/promote callbacks return freshly allocated NUL-terminated char* buffers. The certificate, signature, and decrypted-key callbacks return freshly allocated uint8_t* buffers and lengths.

Public-key JSON is parsed as an object with modulus_base64 and exponent_base64 fields. Bank-key JSON is parsed as an object with host_id, authentication_digest, encryption_digest, and optional authentication_certificate and encryption_certificate fields.

Certificate DER buffers contain the encoded authentication, encryption, or signature certificate bytes for the matching callback.

The adapter copies or parses returned buffers before releasing them. It calls free_buffer(user_data, buffer) for every non-NULL buffer returned by these callbacks, including failure paths after the callback returned GLN_OK.

store_bank_keys_json and store_pending_bank_keys_json receive borrowed library-owned JSON strings that are valid only during the callback. Copy them into the backing store before returning.

sign_authentication, sign_order, and decrypt_transaction_key receive borrowed input byte ranges that are valid only during the callback.

Bank-Key Absence

load_bank_keys_json, load_pending_bank_keys_json, and promote_pending_bank_keys_json may return GLN_ERR_NOT_FOUND when the requested trusted or pending bank keys are absent. Other non-OK callback statuses are surfaced as EBICS key-store failures.

Handle Lifetime

On success, out_store receives a caller-owned handle that must be released with gln_destroy_key_store.

The object referenced by user_data remains host-owned and must stay valid for as long as any live handle or backend-retained key-store implementation can invoke the callbacks.

gln_open_ebics_backend retains the underlying key-store implementation before returning, so the C key-store handle itself does not need to outlive an opened EBICS backend. The backend does not destroy the caller's key-store handle.

Failure Cases

The function clears *out_store to NULL before validation when out_store is non-NULL.

The call returns GLN_ERR_INVALID_ARG when in_vtable, out_store, or any required callback pointer is NULL.

out_error may be NULL. If it is non-NULL, its struct_size must describe a valid gln_error_t; the function clears it on entry and writes invalid-vtable details when validation fails.

Built-In Alternative

On Windows x64 builds, gln_create_file_key_store creates the built-in file-backed EBICS key store. Use it when file-backed encrypted storage is sufficient and a custom vtable is unnecessary.

See Also

• gln_create_file_key_store
• gln_destroy_key_store
• gln_open_ebics_backend
• ABI function index