Update XMSS secret key object APIs, sync with LMS

src/sig_stfl/lms/sig_stfl_lms.c

@@ -8,7 +8,7 @@
 #include "sig_stfl_lms.h"
 
 /* Convert LMS secret key object to byte string */
-static OQS_STATUS OQS_SECRET_KEY_LMS_serialize_key(const OQS_SIG_STFL_SECRET_KEY *sk, size_t *sk_len, uint8_t **sk_buf_ptr);
+static OQS_STATUS OQS_SECRET_KEY_LMS_serialize_key(OQS_SIG_STFL_SECRET_KEY *sk, size_t *sk_len, uint8_t **sk_buf_ptr);
 
 /* Insert lms byte string in an LMS secret key object */
 static OQS_STATUS OQS_SECRET_KEY_LMS_deserialize_key(OQS_SIG_STFL_SECRET_KEY *sk, const size_t sk_len, const uint8_t *sk_buf, void *context);
@@ -1760,7 +1760,7 @@ void OQS_SECRET_KEY_LMS_free(OQS_SIG_STFL_SECRET_KEY *sk) {
 }
 
 /* Convert LMS secret key object to byte string */
-static OQS_STATUS OQS_SECRET_KEY_LMS_serialize_key(const OQS_SIG_STFL_SECRET_KEY *sk, size_t *sk_len, uint8_t **sk_buf_ptr) {
+static OQS_STATUS OQS_SECRET_KEY_LMS_serialize_key(OQS_SIG_STFL_SECRET_KEY *sk, size_t *sk_len, uint8_t **sk_buf_ptr) {
 	OQS_STATUS status;
 	if (sk->lock_key && sk->mutex) {
 		sk->lock_key(sk->mutex);

src/sig_stfl/lms/sig_stfl_lms.h

@@ -209,7 +209,7 @@ int oqs_sig_stfl_lms_verify(const uint8_t *m, size_t mlen, const uint8_t *sm, si
 
 void oqs_secret_lms_key_free(OQS_SIG_STFL_SECRET_KEY *sk);
 
-OQS_STATUS oqs_serialize_lms_key(const OQS_SIG_STFL_SECRET_KEY *sk, size_t *sk_len, uint8_t **sk_key);
+OQS_STATUS oqs_serialize_lms_key(OQS_SIG_STFL_SECRET_KEY *sk, size_t *sk_len, uint8_t **sk_key);
 OQS_STATUS oqs_deserialize_lms_key(OQS_SIG_STFL_SECRET_KEY *sk, const size_t sk_len, const uint8_t *sk_buf, void *context);
 void oqs_lms_key_set_store_cb(OQS_SIG_STFL_SECRET_KEY *sk, secure_store_sk store_cb, void *context);
 

src/sig_stfl/lms/sig_stfl_lms_functions.c

@@ -51,7 +51,6 @@ OQS_API OQS_STATUS OQS_SIG_STFL_alg_lms_sign(uint8_t *signature, size_t *signatu
 	OQS_STATUS status = OQS_ERROR;
 	OQS_STATUS rc_keyupdate = OQS_ERROR;
 	oqs_lms_key_data *lms_key_data = NULL;
-	const OQS_SIG_STFL_SECRET_KEY *sk;
 	uint8_t *sk_key_buf = NULL;
 	size_t sk_key_buf_len = 0;
 	void *context;
@@ -89,8 +88,7 @@ OQS_API OQS_STATUS OQS_SIG_STFL_alg_lms_sign(uint8_t *signature, size_t *signatu
 	 * but, delete signature and the serialized key other wise
 	 */
 
-	sk = secret_key;
-	rc_keyupdate = oqs_serialize_lms_key(sk, &sk_key_buf_len, &sk_key_buf);
+	rc_keyupdate = oqs_serialize_lms_key(secret_key, &sk_key_buf_len, &sk_key_buf);
 	if (rc_keyupdate != OQS_SUCCESS) {
 		goto err;
 	}
@@ -121,8 +119,7 @@ OQS_API OQS_STATUS OQS_SIG_STFL_alg_lms_sign(uint8_t *signature, size_t *signatu
 }
 
 OQS_API OQS_STATUS OQS_SIG_STFL_alg_lms_verify(const uint8_t *message, size_t message_len,
-        const uint8_t *signature, size_t signature_len,
-        const uint8_t *public_key) {
+        const uint8_t *signature, size_t signature_len, const uint8_t *public_key) {
 
 	if (message == NULL || signature == NULL || public_key == NULL) {
 		return OQS_ERROR;
@@ -566,7 +563,7 @@ void oqs_secret_lms_key_free(OQS_SIG_STFL_SECRET_KEY *sk) {
  * Convert LMS secret key object to byte string
  * Writes secret key + aux data if present
  */
-OQS_STATUS oqs_serialize_lms_key(const OQS_SIG_STFL_SECRET_KEY *sk, size_t *sk_len, uint8_t **sk_key) {
+OQS_STATUS oqs_serialize_lms_key(OQS_SIG_STFL_SECRET_KEY *sk, size_t *sk_len, uint8_t **sk_key) {
 
 	if (sk == NULL || sk_len == NULL || sk_key == NULL) {
 		return OQS_ERROR;

src/sig_stfl/lms/sig_stfl_lms_wrap.h

@@ -7,7 +7,6 @@
 #include "external/hss.h"
 #include "external/hss_sign_inc.h"
 
-
 /**
  * @brief OQS_LMS_KEY object for HSS key pair
  */
@@ -17,7 +16,6 @@ typedef struct OQS_LMS_SIG_DATA oqs_lms_sig_data;
 
 typedef struct OQS_LMS_SIG_DATA {
 
-
 	/* message buffer */
 	unsigned char *message;
 
@@ -33,4 +31,3 @@ typedef struct OQS_LMS_SIG_DATA {
 } oqs_lms_sig_data;
 
 #endif //OQS_SIG_STFL_LMS_H
-

src/sig_stfl/sig_stfl.c

@@ -14,6 +14,7 @@
 OQS_API const char *OQS_SIG_STFL_alg_identifier(size_t i) {
 
 	const char *a[OQS_SIG_STFL_algs_length] = {
+		// XMSS
 		OQS_SIG_STFL_alg_xmss_sha256_h10,
 		OQS_SIG_STFL_alg_xmss_sha256_h16,
 		OQS_SIG_STFL_alg_xmss_sha256_h20,
@@ -42,6 +43,7 @@ OQS_API const char *OQS_SIG_STFL_alg_identifier(size_t i) {
 		OQS_SIG_STFL_alg_xmssmt_shake128_h60_3,
 		OQS_SIG_STFL_alg_xmssmt_shake128_h60_6,
 		OQS_SIG_STFL_alg_xmssmt_shake128_h60_12,
+		// LMS
 		OQS_SIG_STFL_alg_lms_sha256_n32_h5_w1,
 		OQS_SIG_STFL_alg_lms_sha256_n32_h5_w2,
 		OQS_SIG_STFL_alg_lms_sha256_n32_h5_w4,
@@ -799,54 +801,38 @@ OQS_API OQS_SIG_STFL_SECRET_KEY *OQS_SIG_STFL_SECRET_KEY_new(const char *method_
 	}
 }
 
-void OQS_SECRET_KEY_XMSS_free(OQS_SIG_STFL_SECRET_KEY *sk) {
-	if (sk == NULL) {
-		return;
-	}
-
-	OQS_MEM_secure_free(sk->secret_key_data, sk->length_secret_key);
-	sk->secret_key_data = NULL;
-}
-
 OQS_API void OQS_SIG_STFL_SECRET_KEY_free(OQS_SIG_STFL_SECRET_KEY *sk) {
-	if (sk == NULL) {
+	if (sk == NULL || sk->free_key == NULL) {
 		return;
 	}
 
 	/* Call object specific free */
-	if (sk->free_key) {
-		sk->free_key(sk);
-	}
+	sk->free_key(sk);
+
+	/* Free sk object */
 	OQS_MEM_secure_free(sk, sizeof(sk));
+	sk = NULL;
 }
 
 OQS_API void OQS_SIG_STFL_SECRET_KEY_SET_store_cb(OQS_SIG_STFL_SECRET_KEY *sk, secure_store_sk store_cb, void *context) {
-	if (sk) {
-		if (sk->set_scrt_key_store_cb) {
-			sk->set_scrt_key_store_cb(sk, store_cb, context);
-		}
+	if (sk == NULL || sk->set_scrt_key_store_cb == NULL) {
+		return;
 	}
+	sk->set_scrt_key_store_cb(sk, store_cb, context);
 }
 
 /* Convert secret key object to byte string */
-OQS_API OQS_STATUS OQS_SECRET_KEY_STFL_serialize_key(const OQS_SIG_STFL_SECRET_KEY *sk, size_t *sk_len, uint8_t **sk_buf) {
-	if ((sk == NULL) || (sk_len == NULL) || (sk_buf == NULL)) {
-		return 0;
-	}
-	if (sk->serialize_key) {
-		return sk->serialize_key(sk, sk_len, sk_buf);
-	} else {
-		return 0;
+OQS_API OQS_STATUS OQS_SECRET_KEY_STFL_serialize_key(OQS_SIG_STFL_SECRET_KEY *sk, size_t *sk_len, uint8_t **sk_buf) {
+	if (sk == NULL || sk_len == NULL || sk_buf == NULL || sk->serialize_key == NULL) {
+		return OQS_ERROR;
 	}
+
+	return sk->serialize_key(sk, sk_len, sk_buf);
 }
 
 /* Insert secret key byte string in an Stateful secret key object */
 OQS_API OQS_STATUS OQS_SECRET_KEY_STFL_deserialize_key(OQS_SIG_STFL_SECRET_KEY *sk, const size_t key_len, const uint8_t *sk_buf, void *context) {
-	if ((sk == NULL) || (sk_buf == NULL)) {
-		return OQS_ERROR;
-	}
-
-	if (sk->deserialize_key == NULL) {
+	if (sk == NULL || sk_buf == NULL || sk->deserialize_key == NULL) {
 		return OQS_ERROR;
 	}
 

src/sig_stfl/sig_stfl.h

@@ -165,7 +165,10 @@ OQS_API int OQS_SIG_STFL_alg_is_enabled(const char *method_name);
  */
 typedef struct OQS_SIG_STFL {
 
-	/** A local ordinal representing the LMS parameter of the signature scheme. */
+	/**
+	 * A local ordinal representing the LMS/XMSS OID parameter of the signature scheme.
+	 * This OID is unrelated to ASN.1 OID or anything, it's only for LMS/XMSS internal usage.
+	 */
 	uint32_t oid;
 
 	/** Printable string representing the name of the signature scheme. */
@@ -262,7 +265,7 @@ typedef struct OQS_SIG_STFL_SECRET_KEY {
 	/* The (maximum) length, in bytes, of secret keys for this signature scheme. */
 	size_t length_secret_key;
 
-	/* The variant specific secret key data */
+	/* The variant specific secret key data, must be allocated at the initialization. */
 	void *secret_key_data;
 
 	/* mutual exclusion struct */
@@ -278,19 +281,19 @@ typedef struct OQS_SIG_STFL_SECRET_KEY {
 	 * @param[out] sk_len length of private key as a byte stream
 	 * @param[out] sk_buf_ptr pointer to private key data as a byte stream
 	 * @returns length of key material data available
-	 * Caller deletes the buffer if memory was allocated.
+	 * Caller is responsible to **unallocate** the pointer to buffer `sk_buf_ptr`.
 	 */
-	OQS_STATUS (*serialize_key)(const OQS_SIG_STFL_SECRET_KEY *sk, size_t *sk_len, uint8_t **sk_buf_ptr);
+	OQS_STATUS (*serialize_key)(OQS_SIG_STFL_SECRET_KEY *sk, size_t *sk_len, uint8_t **sk_buf_ptr);
 
 	/**
-	 * set Secret Key to internal structure Function
+	 * Secret Key to internal structure Function
 	 *
 	 * @param[in] sk OQS_SIG_STFL_SECRET_KEY object
 	 * @param[in] key_len length of the returned byte string
-	 * @param[in] sk_buf The secret key data to populate key obj
-	 * @param[in]  context application specific data
-	 * @returns  status of the operation populated with key material none-zero length. Caller
-	 * deletes the buffer. if sk_buf is NULL the function returns the length
+	 * @param[in] sk_buf The secret key data to populate key object
+	 * @param[in] context application specific data
+	 * @returns  status of the operation populated with key material none-zero length.
+	 * Caller is responsible to **unallocate** the buffer `sk_buf`.
 	 */
 	OQS_STATUS (*deserialize_key)(OQS_SIG_STFL_SECRET_KEY *sk, const size_t sk_len, const uint8_t *sk_buf, void *context);
 
@@ -432,14 +435,6 @@ 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);
 
-/**
- * Frees an OQS_SIG_STFL_SECRET_KEY **inner** data that was constructed by OQS_SECRET_KEY_new.
- *
- * @param[in] sig The OQS_SIG_STFL_SECRET_KEY object to free.
- * @return OQS_SUCCESS if successful, or OQS_ERROR if the object could not be freed.
- */
-void OQS_SECRET_KEY_XMSS_free(OQS_SIG_STFL_SECRET_KEY *sk);
-
 /**
  * Frees an OQS_SIG_STFL_SECRET_KEY object that was constructed by OQS_SECRET_KEY_new.
  *
@@ -516,9 +511,10 @@ OQS_STATUS OQS_SIG_STFL_SECRET_KEY_unlock(OQS_SIG_STFL_SECRET_KEY *sk);
  */
 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_SECRET_KEY_STFL_serialize_key(const OQS_SIG_STFL_SECRET_KEY *sk,  size_t *sk_len, uint8_t **sk_buf);
+/* Serialize stateful secret key data into a byte string, return an allocated buffer. Users is responsible to unallocate the buffer `sk_buf`. */
+OQS_API OQS_STATUS OQS_SECRET_KEY_STFL_serialize_key(OQS_SIG_STFL_SECRET_KEY *sk,  size_t *sk_len, uint8_t **sk_buf);
 
-/* Insert lms byte string in an LMS secret key object */
+/* Insert stateful byte string into an secret key object. User is responsible to unallocate buffer `sk_buf`. */
 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)