diff --git a/README.md b/README.md index ef415c6f12..2554c18495 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,8 @@ The list below indicates all algorithms supported by liboqs, but not all those a - **Falcon**: Falcon-512, Falcon-1024 - **SPHINCS+-SHA2**: SPHINCS+-SHA2-128f-simple, SPHINCS+-SHA2-128s-simple, SPHINCS+-SHA2-192f-simple, SPHINCS+-SHA2-192s-simple, SPHINCS+-SHA2-256f-simple, SPHINCS+-SHA2-256s-simple - **SPHINCS+-SHAKE**: SPHINCS+-SHAKE-128f-simple, SPHINCS+-SHAKE-128s-simple, SPHINCS+-SHAKE-192f-simple, SPHINCS+-SHAKE-192s-simple, SPHINCS+-SHAKE-256f-simple, SPHINCS+-SHAKE-256s-simple +- **XMSS**: Variants of XMSS stateful signature scheames. e.g XMSS-SHA2_10_256, XMSSMT-SHA2_60/6, XMSSMT-SHA2_40/4_256 +- **LMS**: Variants of LMS stateful signature scheames. e.g LMS_SHA256_H5_W8, LMS_SHA256_H10_W8, LMS_SHA256_H10_W8_H10_W8 Note that for algorithms marked with a dagger (†), liboqs contains at least one implementation that uses a large amount of stack space; this may cause failures when run in threads or in constrained environments. For more information, consult the algorithm information sheets in the [docs/algorithms](https://github.com/open-quantum-safe/liboqs/tree/main/docs/algorithms) folder. @@ -112,10 +114,12 @@ The following instructions assume we are in `build`. - `test_kem`: Simple test harness for key encapsulation mechanisms - `test_sig`: Simple test harness for key signature schemes + - `test_sig_stfl`: Simple test harness for stateful key signature schemes - `test_kem_mem`: Simple test harness for checking memory consumption of key encapsulation mechanisms - `test_sig_mem`: Simple test harness for checking memory consumption of key signature schemes - `kat_kem`: Program that generates known answer test (KAT) values for key encapsulation mechanisms using the same procedure as the NIST submission requirements, for checking against submitted KAT values using `tests/test_kat.py` - `kat_sig`: Program that generates known answer test (KAT) values for signature schemes using the same procedure as the NIST submission requirements, for checking against submitted KAT values using `tests/test_kat.py` + - `kat_stfl_sig`: Program for checking results against submitted KAT values using `tests/test_kat.py` - `speed_kem`: Benchmarking program for key encapsulation mechanisms; see `./speed_kem --help` for usage instructions - `speed_sig`: Benchmarking program for signature mechanisms; see `./speed_sig --help` for usage instructions - `example_kem`: Minimal runnable example showing the usage of the KEM API diff --git a/src/sig_stfl/sig_stfl.h b/src/sig_stfl/sig_stfl.h index 42baaab8b0..c681d6a149 100644 --- a/src/sig_stfl/sig_stfl.h +++ b/src/sig_stfl/sig_stfl.h @@ -118,6 +118,9 @@ extern "C" { #define OQS_SIG_STFL_alg_lms_sha256_n32_h20_w8_h15_w8 "LMS_SHA256_H20_W8_H15_W8" //"20/8, 15/8" #define OQS_SIG_STFL_alg_lms_sha256_n32_h20_w8_h20_w8 "LMS_SHA256_H20_W8_H20_W8" //"20/8, 20/8" +/* + * Total number of stateful variants defined above, used to create the tracking array + */ #define OQS_SIG_STFL_algs_length 61 /* Defined LM parameter identifiers */ @@ -130,7 +133,7 @@ typedef struct OQS_SIG_STFL_SECRET_KEY OQS_SIG_STFL_SECRET_KEY; * Application provided function to securely store data * @param[in] sk_buf pointer to the data to be saved * @param[in] buf_len length of the data to be stored - * @param[out] context pointer to application relevant data. + * @param[out] context pass back application data related to secret key data storage. * return OQS_SUCCESS if successful, otherwise OQS_ERROR */ typedef OQS_STATUS (*secure_store_sk)(uint8_t *sk_buf, size_t buf_len, void *context); @@ -220,7 +223,7 @@ typedef struct OQS_SIG_STFL { * compile-time macros `OQS_SIG_STFL_*_length_*`. * * @param[out] public_key The public key is represented as a byte string. - * @param[out] secret_key The secret key is represented as a byte string + * @param[out] secret_key The secret key object * @return OQS_SUCCESS or OQS_ERROR */ OQS_STATUS (*keypair)(uint8_t *public_key, OQS_SIG_STFL_SECRET_KEY *secret_key); @@ -236,7 +239,7 @@ typedef struct OQS_SIG_STFL { * @param[out] signature_len The length of the signature. * @param[in] message The message to sign is represented as a byte string. * @param[in] message_len The length of the message to sign. - * @param[in] secret_key The secret key is represented as a byte string. + * @param[in] secret_key The secret key object pointer. * @return OQS_SUCCESS or OQS_ERROR */ OQS_STATUS (*sign)(uint8_t *signature, size_t *signature_len, const uint8_t *message, size_t message_len, OQS_SIG_STFL_SECRET_KEY *secret_key); @@ -257,7 +260,7 @@ typedef struct OQS_SIG_STFL { * Query number of remaining signatures * * @param[out] remain The number of remaining signatures - * @param[in] secret_key The secret key is represented as a byte string. + * @param[in] secret_key The secret key object pointer. * @return OQS_SUCCESS or OQS_ERROR */ OQS_STATUS (*sigs_remaining)(unsigned long long *remain, const OQS_SIG_STFL_SECRET_KEY *secret_key); @@ -266,7 +269,7 @@ typedef struct OQS_SIG_STFL { * Total number of signatures * * @param[out] total The total number of signatures - * @param[in] secret_key The secret key is represented as a byte string. + * @param[in] secret_key The secret key key object pointer. * @return OQS_SUCCESS or OQS_ERROR */ OQS_STATUS (*sigs_total)(unsigned long long *total, const OQS_SIG_STFL_SECRET_KEY *secret_key); @@ -291,7 +294,7 @@ typedef struct OQS_SIG_STFL_SECRET_KEY { /* mutual exclusion struct */ void *mutex; - /* file storage handle */ + /* Application managed data related to secure storage of secret key data */ void *context; /** @@ -312,6 +315,8 @@ typedef struct OQS_SIG_STFL_SECRET_KEY { * @param[in] key_len length of the returned byte string * @param[in] sk_buf The secret key data to populate the key object * @param[in] context application-specific data + * used to keep track of this secret key stored in a secure manner. + * The application manages this memory. * @returns status of the operation populated with key material none zero length. * Caller is responsible to **unallocate** the buffer `sk_buf`. */ @@ -338,7 +343,8 @@ typedef struct OQS_SIG_STFL_SECRET_KEY { * Callback function used to securely store key data * @param[in] sk_buf The serialized secret key data to secure store * @param[in] buf_len length of data to secure - * @param[in] context aids the secure writing of data + * @param[in] context application supplied data used to locate where this secret key + * is stored * * @return OQS_SUCCESS or OQS_ERROR * Ideally written to secure device @@ -358,7 +364,7 @@ typedef struct OQS_SIG_STFL_SECRET_KEY { * * @param[in] sk secret key pointer to be updated * @param[in] store_cb callback pointer - * @param[in] context secret key specific data/identifier + * @param[in] context application data related to secret key data/identifier storage */ void (*set_scrt_key_store_cb)(OQS_SIG_STFL_SECRET_KEY *sk, secure_store_sk store_cb, void *context); } OQS_SIG_STFL_SECRET_KEY; @@ -384,7 +390,7 @@ OQS_API OQS_SIG_STFL *OQS_SIG_STFL_new(const char *method_name); * * @param[in] sig The OQS_SIG_STFL object representing the signature scheme. * @param[out] public_key The public key is represented as a byte string. - * @param[out] secret_key The secret key is represented as a byte string. + * @param[out] secret_key The secret key object pointer. * @return OQS_SUCCESS or OQS_ERROR */ OQS_API OQS_STATUS OQS_SIG_STFL_keypair(const OQS_SIG_STFL *sig, uint8_t *public_key, OQS_SIG_STFL_SECRET_KEY *secret_key); @@ -401,7 +407,7 @@ OQS_API OQS_STATUS OQS_SIG_STFL_keypair(const OQS_SIG_STFL *sig, uint8_t *public * @param[out] signature_len The length of the signature. * @param[in] message The message to sign is represented as a byte string. * @param[in] message_len The length of the message to sign. - * @param[in] secret_key The secret key is represented as a byte string. + * @param[in] secret_key The secret key object pointer. * @return OQS_SUCCESS or OQS_ERROR */ 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); @@ -423,7 +429,7 @@ OQS_API OQS_STATUS OQS_SIG_STFL_verify(const OQS_SIG_STFL *sig, const uint8_t *m * Query number of remaining signatures * * @param[in] sig The OQS_SIG_STFL object representing the signature scheme. - * @param[in] secret_key The secret key is represented as a byte string. + * @param[in] secret_key The secret key object. * @return OQS_SUCCESS or OQS_ERROR */ 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); @@ -433,7 +439,7 @@ OQS_API OQS_STATUS OQS_SIG_STFL_sigs_remaining(const OQS_SIG_STFL *sig, unsigned * * @param[in] sig The OQS_SIG_STFL object representing the signature scheme. * @param[out] max The number of remaining signatures - * @param[in] secret_key The secret key is represented as a byte string. + * @param[in] secret_key The secret key object. * @return OQS_SUCCESS or OQS_ERROR */ 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); @@ -526,15 +532,35 @@ OQS_STATUS OQS_SIG_STFL_SECRET_KEY_unlock(OQS_SIG_STFL_SECRET_KEY *sk); * * @param[in] sk secret key pointer to be updated * @param[in] store_cb callback pointer - * @param[in] context secret key specific data/identifier + * @param[in] context application data related to where how secret key data storage * */ void OQS_SIG_STFL_SECRET_KEY_SET_store_cb(OQS_SIG_STFL_SECRET_KEY *sk, secure_store_sk store_cb, void *context); -/* Serialize stateful secret key data into a byte string, and return an allocated buffer. Users are responsible for deallocating the buffer `sk_buf`. */ +/** + * OQS_SECRET_KEY_STFL_serialize_key . + * + * Serialize stateful secret key data into a byte string, and + * return an allocated buffer. Users are responsible for deallocating + * the buffer `sk_buf_ptr`. + * + * @param[out] sk_buf_ptr secret key buffer returned. Caller deletes. + * @param[out] sk_len size of the buffer returned + * @param[in] sk secret key pointer to be serialize + */ OQS_API OQS_STATUS OQS_SECRET_KEY_STFL_serialize_key(uint8_t **sk_buf_ptr, size_t *sk_len, const OQS_SIG_STFL_SECRET_KEY *sk); -/* Insert stateful byte string into a secret key object. Users are responsible for deallocating buffer `sk_buf`. */ +/** + * OQS_SECRET_KEY_STFL_serialize_key . + * + * Insert stateful byte string into a secret key object. + * Users are responsible for deallocating buffer `sk_buf`. + * + * @param[in] sk secret key pointer to be serialize + * @param[in] sk_len size of the buffer returned + * @param[in] sk_buf secret key buffer returned. Caller deletes. + * @param[in] context application managed data related to where/how secret key data is stored. + */ OQS_API OQS_STATUS OQS_SECRET_KEY_STFL_deserialize_key(OQS_SIG_STFL_SECRET_KEY *sk, size_t key_len, const uint8_t *sk_buf, void *context); #if defined(__cplusplus)