liboqs
Loading...
Searching...
No Matches
OQS_SIG_STFL_SECRET_KEY Struct Reference

OQS_SIG_STFL_SECRET_KEY object for stateful signature schemes. More...

#include <sig_stfl.h>

Data Fields

size_t length_secret_key
void * secret_key_data
void * mutex
void * context
OQS_STATUS(* serialize_key )(uint8_t **sk_buf_ptr, size_t *sk_buf_len, const OQS_SIG_STFL_SECRET_KEY *sk)
OQS_STATUS(* deserialize_key )(OQS_SIG_STFL_SECRET_KEY *sk, const uint8_t *sk_buf, const size_t sk_buf_len, void *context)
OQS_STATUS(* lock_key )(void *mutex)
OQS_STATUS(* unlock_key )(void *mutex)
OQS_STATUS(* secure_store_scrt_key )(uint8_t *sk_buf, size_t sk_buf_len, void *context)
void(* free_key )(OQS_SIG_STFL_SECRET_KEY *sk)
void(* set_scrt_key_store_cb )(OQS_SIG_STFL_SECRET_KEY *sk, secure_store_sk store_cb, void *context)

Detailed Description

OQS_SIG_STFL_SECRET_KEY object for stateful signature schemes.

Field Documentation

◆ context

void* OQS_SIG_STFL_SECRET_KEY::context

Application-managed data related to secure storage of secret key data

◆ deserialize_key

OQS_STATUS(* OQS_SIG_STFL_SECRET_KEY::deserialize_key) (OQS_SIG_STFL_SECRET_KEY *sk, const uint8_t *sk_buf, const size_t sk_buf_len, void *context)

Deserialize a byte stream into the internal representation of a stateful secret key.

This function takes a series of bytes representing a stateful secret key and initializes the internal OQS_SIG_STFL_SECRET_KEY object with the key material. This is particularly useful for reconstructing key objects from persisted or transmitted state.

Parameters
[out]skPointer to an uninitialized OQS_SIG_STFL_SECRET_KEY object to hold the secret key.
[in]sk_bufPointer to the byte stream containing the serialized secret key data.
[in]sk_buf_lenThe length of the secret key byte stream.
[in]contextPointer to application-specific data, handled externally, associated with the key.
Returns
OQS_SUCCESS if the deserialization succeeds, with the sk object populated with the key material.
Attention
The caller is responsible for ensuring that sk_buf is securely deallocated when it's no longer needed.

◆ free_key

void(* OQS_SIG_STFL_SECRET_KEY::free_key) (OQS_SIG_STFL_SECRET_KEY *sk)

Free internal variant-specific data

Parameters
[in]skThe secret key represented as OQS_SIG_STFL_SECRET_KEY object.
Returns
None.

◆ length_secret_key

size_t OQS_SIG_STFL_SECRET_KEY::length_secret_key

The (maximum) length, in bytes, of secret keys for this signature scheme.

◆ lock_key

OQS_STATUS(* OQS_SIG_STFL_SECRET_KEY::lock_key) (void *mutex)

Secret Key Locking Function

Parameters
[in]mutexapplication defined mutex
Returns
OQS_SUCCESS or OQS_ERROR

◆ mutex

void* OQS_SIG_STFL_SECRET_KEY::mutex

The mutual exclusion struct

◆ secret_key_data

void* OQS_SIG_STFL_SECRET_KEY::secret_key_data

The variant-specific secret key data must be allocated at the initialization.

◆ secure_store_scrt_key

OQS_STATUS(* OQS_SIG_STFL_SECRET_KEY::secure_store_scrt_key) (uint8_t *sk_buf, size_t sk_buf_len, void *context)

Store Secret Key Function

Callback function used to securely store key data after a signature generation. When populated, this pointer points to the application-supplied secure storage function.

Parameters
[in]sk_bufThe serialized secret key data to secure store
[in]sk_buf_lenlength of data to secure
[in]contextapplication supplied data used to locate where this secret key is stored (passed in at the time the function pointer was set).
Returns
OQS_SUCCESS or OQS_ERROR Ideally written to a secure device.

◆ serialize_key

OQS_STATUS(* OQS_SIG_STFL_SECRET_KEY::serialize_key) (uint8_t **sk_buf_ptr, size_t *sk_buf_len, const OQS_SIG_STFL_SECRET_KEY *sk)

Serialize the stateful secret key.

This function encodes the stateful secret key represented by sk into a byte stream for storage or transfer. The sk_buf_ptr will point to the allocated memory containing the byte stream. Users must free the sk_buf_ptr using OQS_MEM_secure_free after use. The sk_len will contain the length of the byte stream.

Parameters
[out]sk_buf_ptrPointer to the byte stream representing the serialized secret key.
[out]sk_buf_lenPointer to the length of the serialized byte stream.
[in]skPointer to the OQS_SIG_STFL_SECRET_KEY object to serialize.
Returns
The number of bytes in the serialized byte stream upon success, or an OQS error code on failure.
Attention
The caller is responsible for ensuring that sk is a valid object before calling this function.

◆ set_scrt_key_store_cb

void(* OQS_SIG_STFL_SECRET_KEY::set_scrt_key_store_cb) (OQS_SIG_STFL_SECRET_KEY *sk, secure_store_sk store_cb, void *context)

Set Secret Key Store Callback Function

This function is used to establish a callback mechanism for secure storage of private keys involved in stateful signature Signing operation. The secure storage and the management of private keys is the responsibility of the adopting application. Therefore, before invoking stateful signature generation, a callback function and associated context data must be provided by the application to manage the storage.

The context argument is designed to hold information requisite for private key storage, such as a hardware security module (HSM) context, a file path, or other relevant data. This context is passed to the libOQS when the callback function is registered.

Parameters
[in]skA pointer to the secret key object that requires secure storage management after signature Signing operations.
[in]store_cbA pointer to the callback function provided by the application for storing and updating the private key securely.
[in]contextApplication-specific context information for the private key storage, furnished when setting the callback function via OQS_SIG_STFL_SECRET_KEY_set_store_cb().
Returns
None.

◆ unlock_key

OQS_STATUS(* OQS_SIG_STFL_SECRET_KEY::unlock_key) (void *mutex)

Secret Key Unlocking / Releasing Function

Parameters
[in]mutexapplication defined mutex
Returns
OQS_SUCCESS or OQS_ERROR

The documentation for this struct was generated from the following file: