src/sig_stfl/sig_stfl.h
Stateful Signature schemes.
The file tests/example_sig_stfl.c contains an example on using the OQS_SIG_STFL API.
SPDX-License-Identifier: MIT
Includes
#include <stdbool.h> #include <stddef.h> #include <stdint.h> #include <oqs/oqs.h> Typedefs
|
|
|
Application provided function to securely store data |
|
Application provided function to lock secret key object serialize access |
|
Application provided function to unlock secret key object |
Functions
OQS_API const char * | OQS_SIG_STFL_alg_identifier(size_t i) |
OQS_API int | OQS_SIG_STFL_alg_count(void) |
OQS_API int | OQS_SIG_STFL_alg_is_enabled(const char *method_name) |
OQS_API OQS_SIG_STFL * | OQS_SIG_STFL_new(const char *method_name) |
OQS_API OQS_STATUS | OQS_SIG_STFL_keypair(const OQS_SIG_STFL *sig, uint8_t *public_key, OQS_SIG_STFL_SECRET_KEY *secret_key) |
OQS_API OQS_STATUS | OQS_SIG_STFL_sign(const OQS_SIG_STFL *sig, uint8_t *signature, size_t *signature_len, const uint8_t *message, size_t message_len, OQS_SIG_STFL_SECRET_KEY *secret_key) |
OQS_API OQS_STATUS | OQS_SIG_STFL_verify(const OQS_SIG_STFL *sig, const uint8_t *message, size_t message_len, const uint8_t *signature, size_t signature_len, const uint8_t *public_key) |
OQS_API OQS_STATUS | OQS_SIG_STFL_sigs_remaining(const OQS_SIG_STFL *sig, unsigned long long *remain, const OQS_SIG_STFL_SECRET_KEY *secret_key) |
OQS_API OQS_STATUS | OQS_SIG_STFL_sigs_total(const OQS_SIG_STFL *sig, unsigned long long *max, const OQS_SIG_STFL_SECRET_KEY *secret_key) |
OQS_API void | OQS_SIG_STFL_free(OQS_SIG_STFL *sig) |
OQS_API OQS_SIG_STFL_SECRET_KEY * | OQS_SIG_STFL_SECRET_KEY_new(const char *method_name) |
OQS_API void | OQS_SIG_STFL_SECRET_KEY_free(OQS_SIG_STFL_SECRET_KEY *sk) |
OQS_API void | OQS_SIG_STFL_SECRET_KEY_SET_lock(OQS_SIG_STFL_SECRET_KEY *sk, lock_key lock) |
OQS_API void | OQS_SIG_STFL_SECRET_KEY_SET_unlock(OQS_SIG_STFL_SECRET_KEY *sk, unlock_key unlock) |
OQS_API void | OQS_SIG_STFL_SECRET_KEY_SET_mutex(OQS_SIG_STFL_SECRET_KEY *sk, void *mutex) |
OQS_STATUS | OQS_SIG_STFL_SECRET_KEY_lock(OQS_SIG_STFL_SECRET_KEY *sk) |
OQS_STATUS | OQS_SIG_STFL_SECRET_KEY_unlock(OQS_SIG_STFL_SECRET_KEY *sk) |
OQS_API void | OQS_SIG_STFL_SECRET_KEY_SET_store_cb(OQS_SIG_STFL_SECRET_KEY *sk, secure_store_sk store_cb, void *context) |
OQS_API OQS_STATUS | OQS_SIG_STFL_SECRET_KEY_serialize(uint8_t **sk_buf_ptr, size_t *sk_buf_len, const OQS_SIG_STFL_SECRET_KEY *sk) |
OQS_API OQS_STATUS | OQS_SIG_STFL_SECRET_KEY_deserialize(OQS_SIG_STFL_SECRET_KEY *sk, const uint8_t *sk_buf, size_t sk_buf_len, void *context) |
OQS_SIG_STFL_alg_identifier
OQS_API const char * OQS_SIG_STFL_alg_identifier(size_t i)Returns identifiers for available signature schemes in liboqs. Used with OQS_SIG_STFL_new.
Note that algorithm identifiers are present in this list even when the algorithm is disabled at compile time.
Parameters
size_t | i | Index of the algorithm identifier to return, 0 <= i < OQS_SIG_algs_length |
Returns
Algorithm identifier as a string, or NULL.
OQS_SIG_STFL_alg_is_enabled
OQS_API int OQS_SIG_STFL_alg_is_enabled(const char *method_name)Indicates whether the specified algorithm was enabled at compile-time or not.
Parameters
const char * | method_name | Name of the desired algorithm; one of the names in |
Returns
1 if enabled, 0 if disabled or not found
OQS_SIG_STFL_new
OQS_API OQS_SIG_STFL * OQS_SIG_STFL_new(const char *method_name)Constructs an OQS_SIG_STFL object for a particular algorithm.
Callers should always check whether the return value is NULL, which indicates either than an invalid algorithm name was provided, or that the requested algorithm was disabled at compile-time.
Parameters
const char * | method_name | Name of the desired algorithm; one of the names in |
Returns
An OQS_SIG_STFL for the particular algorithm, or NULL if the algorithm has been disabled at compile-time.
OQS_SIG_STFL_keypair
OQS_API OQS_STATUS OQS_SIG_STFL_keypair(const OQS_SIG_STFL *sig, uint8_t *public_key, OQS_SIG_STFL_SECRET_KEY *secret_key)Keypair generation algorithm.
Caller is responsible for allocating sufficient memory for public_key based on the length_* members in this object or the per-scheme compile-time macros OQS_SIG_STFL_*_length_*. The caller is also responsible for initializing secret_key using the OQS_SIG_STFL_SECRET_KEY(*) function.
Parameters
const OQS_SIG_STFL * | sig | The OQS_SIG_STFL object representing the signature scheme. |
uint8_t * | public_key | The public key is represented as a byte string. |
OQS_SIG_STFL_SECRET_KEY * | secret_key | The secret key object pointer. |
Returns
OQS_SUCCESS or OQS_ERROR
OQS_SIG_STFL_sign
OQS_API OQS_STATUS OQS_SIG_STFL_sign(const OQS_SIG_STFL *sig, uint8_t *signature, size_t *signature_len, const uint8_t *message, size_t message_len, OQS_SIG_STFL_SECRET_KEY *secret_key)Signature generation algorithm.
For stateful signatures, there is always a limited number of signatures that can be used, The private key signature counter is increased by one once a signature is successfully generated, When the signature counter reaches the maximum number of available signatures, the signature generation always fails.
Caller is responsible for allocating sufficient memory for signature, based on the length_* members in this object or the per-scheme compile-time macros OQS_SIG_STFL_*_length_*.
Parameters
const OQS_SIG_STFL * | sig | The OQS_SIG_STFL object representing the signature scheme. |
uint8_t * | signature | The signature on the message is represented as a byte string. |
size_t * | signature_len | The length of the signature. |
const uint8_t * | message | The message to sign is represented as a byte string. |
size_t | message_len | The length of the message to sign. |
OQS_SIG_STFL_SECRET_KEY * | secret_key | The secret key object pointer. |
Returns
OQS_SUCCESS or OQS_ERROR
OQS_SIG_STFL_verify
OQS_API OQS_STATUS OQS_SIG_STFL_verify(const OQS_SIG_STFL *sig, const uint8_t *message, size_t message_len, const uint8_t *signature, size_t signature_len, const uint8_t *public_key)Signature verification algorithm.
Parameters
const OQS_SIG_STFL * | sig | The OQS_SIG_STFL object representing the signature scheme. |
const uint8_t * | message | The message is represented as a byte string. |
size_t | message_len | The length of the message. |
const uint8_t * | signature | The signature on the message is represented as a byte string. |
size_t | signature_len | The length of the signature. |
const uint8_t * | public_key | The public key is represented as a byte string. |
Returns
OQS_SUCCESS or OQS_ERROR
OQS_SIG_STFL_sigs_remaining
OQS_API OQS_STATUS OQS_SIG_STFL_sigs_remaining(const OQS_SIG_STFL *sig, unsigned long long *remain, const OQS_SIG_STFL_SECRET_KEY *secret_key)Query the number of remaining signatures.
The remaining signatures are the number of signatures available before the private key runs out of its total signature and expires.
Parameters
const OQS_SIG_STFL * | sig | The OQS_SIG_STFL object representing the signature scheme. |
unsigned long long * | remain | The number of remaining signatures. |
const OQS_SIG_STFL_SECRET_KEY * | secret_key | The secret key object. |
Returns
OQS_SUCCESS or OQS_ERROR
OQS_SIG_STFL_sigs_total
OQS_API OQS_STATUS OQS_SIG_STFL_sigs_total(const OQS_SIG_STFL *sig, unsigned long long *max, const OQS_SIG_STFL_SECRET_KEY *secret_key)Query the total number of signatures.
The total number of signatures is the constant number present in how many signatures can be generated from a private key.
Parameters
const OQS_SIG_STFL * | sig | The OQS_SIG_STFL object representing the signature scheme. |
unsigned long long * | max | The number of remaining signatures |
const OQS_SIG_STFL_SECRET_KEY * | secret_key | The secret key object. |
Returns
OQS_SUCCESS or OQS_ERROR
OQS_SIG_STFL_SECRET_KEY_new
OQS_API OQS_SIG_STFL_SECRET_KEY * OQS_SIG_STFL_SECRET_KEY_new(const char *method_name)Construct an OQS_SIG_STFL_SECRET_KEY object for a particular algorithm.
Callers should always check whether the return value is NULL, which indicates either than an invalid algorithm name was provided, or that the requested algorithm was disabled at compile-time.
Parameters
const char * | method_name | Name of the desired algorithm; one of the names in |
Returns
An OQS_SIG_STFL_SECRET_KEY for the particular algorithm, or NULL if the algorithm has been disabled at compile-time.
OQS_SIG_STFL_SECRET_KEY_SET_lock
OQS_API void OQS_SIG_STFL_SECRET_KEY_SET_lock(OQS_SIG_STFL_SECRET_KEY *sk, lock_key lock)Attach a locking mechanism to a secret key object.
This allows for proper synchronization in a multi-threaded or multi-process environment, by ensuring that a secret key is not used concurrently by multiple entities, which could otherwise lead to security issues.
Parameters
OQS_SIG_STFL_SECRET_KEY * | sk | Pointer to the secret key object whose lock function is to be set. |
lock_key | lock | Function pointer to the locking routine provided by the application. |
OQS_SIG_STFL_SECRET_KEY_SET_unlock
OQS_API void OQS_SIG_STFL_SECRET_KEY_SET_unlock(OQS_SIG_STFL_SECRET_KEY *sk, unlock_key unlock)Attach an unlock mechanism to a secret key object.
This allows for proper synchronization in a multi-threaded or multi-process environment, by ensuring that a secret key is not used concurrently by multiple entities, which could otherwise lead to security issues.
Parameters
OQS_SIG_STFL_SECRET_KEY * | sk | Pointer to the secret key object whose unlock function is to be set. |
unlock_key | unlock | Function pointer to the unlock routine provided by the application. |
OQS_SIG_STFL_SECRET_KEY_SET_mutex
OQS_API void OQS_SIG_STFL_SECRET_KEY_SET_mutex(OQS_SIG_STFL_SECRET_KEY *sk, void *mutex)Assign a mutex function to handle concurrency control over the secret key.
This is to ensure that only one process can access or modify the key at any given time.
Parameters
OQS_SIG_STFL_SECRET_KEY * | sk | A pointer to the secret key that the mutex functionality will protect. |
void * | mutex | A function pointer to the desired concurrency control mechanism. |
OQS_SIG_STFL_SECRET_KEY_lock
OQS_STATUS OQS_SIG_STFL_SECRET_KEY_lock(OQS_SIG_STFL_SECRET_KEY *sk)Lock the secret key to ensure exclusive access in a concurrent environment.
If the mutex is not set, this lock operation will fail. This lock operation is essential in multi-threaded or multi-process contexts to prevent simultaneous Signing operations that could compromise the stateful signature security.
Parameters
OQS_SIG_STFL_SECRET_KEY * | sk | Pointer to the secret key to be locked. |
Returns
OQS_SUCCESS if the lock is successfully applied; OQS_ERROR otherwise.
OQS_SIG_STFL_SECRET_KEY_unlock
OQS_STATUS OQS_SIG_STFL_SECRET_KEY_unlock(OQS_SIG_STFL_SECRET_KEY *sk)Unlock the secret key, making it accessible to other processes.
This function is crucial in environments where multiple processes need to coordinate access to the secret key, as it allows a process to signal that it has finished using the key, so others can safely use it.
Parameters
OQS_SIG_STFL_SECRET_KEY * | sk | Pointer to the secret key whose lock should be released. |
Returns
OQS_SUCCESS if the lock was successfully released; otherwise, OQS_ERROR.
OQS_SIG_STFL_SECRET_KEY_SET_store_cb
OQS_API void OQS_SIG_STFL_SECRET_KEY_SET_store_cb(OQS_SIG_STFL_SECRET_KEY *sk, secure_store_sk store_cb, void *context)Set the callback and context for securely storing a stateful secret key.
This function is designed to be called after a new stateful secret key has been generated. It enables the library to securely store secret key and update it every time a Signing operation occurs. Without properly setting this callback and context, signature generation will not succeed as the updated state of the secret key cannot be preserved.
Parameters
OQS_SIG_STFL_SECRET_KEY * | sk | Pointer to the stateful secret key to be managed. |
secure_store_sk | store_cb | Callback function that handles the secure storage of the key. |
void * | context | Application-specific context that assists in the storage of secret key data. This context is managed by the application, which allocates it, keeps track of it, and deallocates it as necessary. |
OQS_SIG_STFL_SECRET_KEY_serialize
OQS_API OQS_STATUS OQS_SIG_STFL_SECRET_KEY_serialize(uint8_t **sk_buf_ptr, size_t *sk_buf_len, const OQS_SIG_STFL_SECRET_KEY *sk)Serialize the stateful secret key data into a byte array.
Converts an OQS_SIG_STFL_SECRET_KEY object into a byte array for storage or transmission.
Parameters
uint8_t ** | sk_buf_ptr | Pointer to the allocated byte array containing the serialized key. |
size_t * | sk_buf_len | Length of the serialized key byte array. |
const OQS_SIG_STFL_SECRET_KEY * | sk | Pointer to the OQS_SIG_STFL_SECRET_KEY object to be serialized. |
Returns
OQS_SUCCESS on success, or an OQS error code on failure.
OQS_SIG_STFL_SECRET_KEY_deserialize
OQS_API OQS_STATUS OQS_SIG_STFL_SECRET_KEY_deserialize(OQS_SIG_STFL_SECRET_KEY *sk, const uint8_t *sk_buf, size_t sk_buf_len, void *context)Deserialize a byte array into an OQS_SIG_STFL_SECRET_KEY object.
Transforms a binary representation of a secret key into an OQS_SIG_STFL_SECRET_KEY structure. After deserialization, the secret key object can be used for subsequent cryptographic operations.
Parameters
OQS_SIG_STFL_SECRET_KEY * | sk | A pointer to the secret key object that will be populated from the binary data. |
const uint8_t * | sk_buf | The buffer containing the serialized secret key data. |
size_t | sk_buf_len | The length of the binary secret key data in bytes. |
void * | context | Application-specific data used to maintain context about the secret key. |
Returns
OQS_SUCCESS if deserialization was successful; otherwise, OQS_ERROR.
Macros
|
Algorithm identifier for XMSS-SHA2_10_256 |
|
Algorithm identifier for XMSS-SHA2_16_256 |
|
Algorithm identifier for XMSS-SHA2_20_256 |
|
Algorithm identifier for XMSS-SHAKE_10_256 |
|
Algorithm identifier for XMSS-SHAKE_16_256 |
|
Algorithm identifier for XMSS-SHAKE_20_256 |
|
Algorithm identifier for XMSS-SHA2_10_512 |
|
Algorithm identifier for XMSS-SHA2_16_512 |
|
Algorithm identifier for XMSS-SHA2_20_512 |
|
Algorithm identifier for XMSS-SHAKE_10_512 |
|
Algorithm identifier for XMSS-SHAKE_16_512 |
|
Algorithm identifier for XMSS-SHAKE_20_512 |
|
Algorithm identifier for XMSS-SHA2_10_192 |
|
Algorithm identifier for XMSS-SHA2_16_192 |
|
Algorithm identifier for XMSS-SHA2_20_192 |
|
Algorithm identifier for XMSS-SHAKE256_10_192 |
|
Algorithm identifier for XMSS-SHAKE256_16_192 |
|
Algorithm identifier for XMSS-SHAKE256_20_192 |
|
Algorithm identifier for XMSS-SHAKE256_10_256 |
|
Algorithm identifier for XMSS-SHAKE256_16_256 |
|
Algorithm identifier for XMSS-SHAKE256_20_256 |
|
Algorithm identifier for XMSSMT-SHA2_20/2_256 |
|
Algorithm identifier for XMSSMT-SHA2_20/4_256 |
|
Algorithm identifier for XMSSMT-SHA2_40/2_256 |
|
Algorithm identifier for XMSSMT-SHA2_40/4_256 |
|
Algorithm identifier for XMSSMT-SHA2_40/8_256 |
|
Algorithm identifier for XMSSMT-SHA2_60/3_256 |
|
Algorithm identifier for XMSSMT-SHA2_60/6_256 |
|
Algorithm identifier for XMSSMT-SHA2_60/12_256 |
|
Algorithm identifier for XMSSMT-SHAKE_20/2_256 |
|
Algorithm identifier for XMSSMT-SHAKE_20/4_256 |
|
Algorithm identifier for XMSSMT-SHAKE_40/2_256 |
|
Algorithm identifier for XMSSMT-SHAKE_40/4_256 |
|
Algorithm identifier for XMSSMT-SHAKE_40/8_256 |
|
Algorithm identifier for XMSSMT-SHAKE_60/3_256 |
|
Algorithm identifier for XMSSMT-SHAKE_60/6_256 |
|
Algorithm identifier for XMSSMT-SHAKE_60/12_256 |
|
Algorithm identifier for LMS-SHA256_H5_W1 |
|
Algorithm identifier for LMS-SHA256_H5_W2 |
|
Algorithm identifier for LMS-SHA256_H5_W4 |
|
Algorithm identifier for LMS-SHA256_H5_W8 |
|
Algorithm identifier for LMS-SHA256_H10_W1 |
|
Algorithm identifier for LMS-SHA256_H10_W2 |
|
Algorithm identifier for LMS-SHA256_H10_W4 |
|
Algorithm identifier for LMS-SHA256_H10_W8 |
|
Algorithm identifier for LMS-SHA256_H15_W1 |
|
Algorithm identifier for LMS-SHA256_H15_W2 |
|
Algorithm identifier for LMS-SHA256_H15_W4 |
|
Algorithm identifier for LMS-SHA256_H15_W8 |
|
Algorithm identifier for LMS-SHA256_H20_W1 |
|
Algorithm identifier for LMS-SHA256_H20_W2 |
|
Algorithm identifier for LMS-SHA256_H20_W4 |
|
Algorithm identifier for LMS-SHA256_H20_W8 |
|
Algorithm identifier for LMS-SHA256_H25_W1 |
|
Algorithm identifier for LMS-SHA256_H25_W2 |
|
Algorithm identifier for LMS-SHA256_H25_W4 |
|
Algorithm identifier for LMS-SHA256_H25_W8 |
|
Algorithm identifier for LMS-SHA256_H5_W8_H5_W8 |
|
Algorithm identifier for LMS-SHA256_H10_W4_H5_W8 |
|
Algorithm identifier for LMS-SHA256_H10_W8_H5_W8 |
|
Algorithm identifier for LMS-SHA256_H10_W2_H10_W2 |
|
Algorithm identifier for LMS-SHA256_H10_W4_H10_W4 |
|
Algorithm identifier for LMS-SHA256_H10_W8_H10_W8 |
|
Algorithm identifier for LMS-SHA256_H15_W8_H5_W8 |
|
Algorithm identifier for LMS-SHA256_H15_W8_H10_W8 |
|
Algorithm identifier for LMS-SHA256_H15_W8_H15_W8 |
|
Algorithm identifier for LMS-SHA256_H20_W8_H5_W8 |
|
Algorithm identifier for LMS-SHA256_H20_W8_H10_W8 |
|
Algorithm identifier for LMS-SHA256_H20_W8_H15_W8 |
|
Algorithm identifier for LMS-SHA256_H20_W8_H20_W8 |
|
Total number of stateful variants defined above, used to create the tracking array |
|
Stateful signature scheme object |