Update per comments

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
 <!--- OQS_TEMPLATE_FRAGMENT_LIST_SIGS_END -->
 
 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

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)