Update LMS/LMOTS documentation
Signed-off-by: Raef Coles <raef.coles@arm.com>
diff --git a/include/mbedtls/lmots.h b/include/mbedtls/lmots.h
index c98f3bf..d89f5bb 100644
--- a/include/mbedtls/lmots.h
+++ b/include/mbedtls/lmots.h
@@ -2,7 +2,9 @@
* \file lmots.h
*
* \brief This file provides an API for the LM-OTS post-quantum-safe one-time
- * public-key signature scheme.
+ * public-key signature scheme as defined in RFC8554 and NIST.SP.200-208.
+ * This implementation currently only supports a single parameter set
+ * MBEDTLS_LMOTS_SHA256_N32_W8 in order to reduce complexity.
*/
/*
* Copyright The Mbed TLS Contributors
@@ -67,6 +69,33 @@
} mbedtls_lmots_algorithm_type_t;
+/** LMOTS context structure.
+ *
+ * The context must be initialized before it is used. A public key must either
+ * be imported, or an algorithm type set, a private key generated and the public
+ * key calculated from it. A context that does not contain a public key cannot
+ * verify, and a context that does not contain a private key cannot sign.
+ * Signing a message will remove the private key from the context, as private
+ * keys can only be used a single time.
+ *
+ * \dot
+ * digraph lmots {
+ * UNINITIALIZED -> INIT [label="init"];
+ * TYPE_SET -> INIT [label="free"];
+ * PRIVATE -> INIT [label="free"];
+ * PUBLIC -> INIT [label="free"];
+ * "PRIVATE+PUBLIC" -> INIT [label="free"];
+ * INIT -> TYPE_SET [label="set_algorithm_type"];
+ * PRIVATE -> TYPE_SET [label="sign"];
+ * "PRIVATE+PUBLIC" -> PUBLIC [label="sign"];
+ * INIT -> PUBLIC [label="import_public"];
+ * PUBLIC -> PUBLIC [label="export_pubkey"];
+ * "PRIVATE+PUBLIC" -> "PRIVATE+PUBLIC" [label="export_pubkey"];
+ * PRIVATE -> "PRIVATE+PUBLIC" [label="gen_pubkey"];
+ * TYPE_SET -> PRIVATE [label="gen_privkey"];
+ * }
+ * \enddot
+ */
typedef struct {
unsigned char MBEDTLS_PRIVATE(have_privkey); /*!< Whether the context contains a private key.
Boolean values only. */
@@ -129,15 +158,14 @@
* mbedtls_lmots_verify will be used for LMOTS
* signature verification.
*
- * \param I_key_identifier The key identifier of the key, as a 16 byte
- * bytestring.
+ * \param I_key_identifier The key identifier of the key, as a 16-byte string.
* \param q_leaf_identifier The leaf identifier of key. If this LMOTS key is
* not being used as part of an LMS key, this should
* be set to 0.
* \param msg The buffer from which the message will be read.
* \param msg_len The size of the message that will be read.
- * \param sig The buff from which the signature will be read.
- * MBEDTLS_LMOTS_SIG_LEN bytes will be read from this.
+ * \param sig The buffer from which the signature will be read.
+ * #MBEDTLS_LMOTS_SIG_LEN bytes will be read from this.
* \param out The buffer where the candidate public key will be
* stored. Must be at least #MBEDTLS_LMOTS_N_HASH_LEN
* bytes in size.
@@ -189,6 +217,10 @@
* \brief This function verifies a LMOTS signature, using a
* LMOTS context that contains a public key.
*
+ * \warning This function is **not intended for use in
+ * production**, due to as-yet unsolved problems with
+ * handling stateful keys.
+ *
* \note Before this function is called, the context must
* have been initialized and must contain a public key
* (either by import or generation).
@@ -270,6 +302,10 @@
* \brief This function generates an LMOTS private key, and
* stores in into an LMOTS context.
*
+ * \warning This function is **not intended for use in
+ * production**, due to as-yet unsolved problems with
+ * handling stateful keys.
+ *
* \note Before this function is called, the context must
* have been initialized and the type of the LMOTS
* context set using mbedtls_lmots_set_algorithm_type
@@ -278,8 +314,7 @@
*
* \param ctx The initialized LMOTS context to generate the key
* into.
- * \param I_key_identifier The key identifier of the key, as a 16 byte
- * bytestring.
+ * \param I_key_identifier The key identifier of the key, as a 16-byte string.
* \param q_leaf_identifier The leaf identifier of key. If this LMOTS key is
* not being used as part of an LMS key, this should
* be set to 0.
diff --git a/include/mbedtls/lms.h b/include/mbedtls/lms.h
index 77559e2..72ed521 100644
--- a/include/mbedtls/lms.h
+++ b/include/mbedtls/lms.h
@@ -2,7 +2,11 @@
* \file lms.h
*
* \brief This file provides an API for the LMS post-quantum-safe stateful-hash
- * public-key signature scheme.
+ public-key signature scheme as defined in RFC8554 and NIST.SP.200-208.
+ * This implementation currently only supports a single parameter set
+ * MBEDTLS_LMS_SHA256_M32_H10 in order to reduce complexity. This is one
+ * of the signature schemes recommended by the IETF draft SUIT standard
+ * for IOT firmware upgrades (RFC9019).
*/
/*
* Copyright The Mbed TLS Contributors
@@ -36,7 +40,7 @@
#define MBEDTLS_LMS_TYPE_LEN (4)
#define MBEDTLS_LMS_H_TREE_HEIGHT (10)
-#define MBEDTLS_LMS_M_NODE_BYTES (32)
+#define MBEDTLS_LMS_M_NODE_BYTES (32) /* The length of a hash output, 32 for SHA256 */
#define MBEDTLS_LMS_SIG_LEN (MBEDTLS_LMOTS_Q_LEAF_ID_LEN + MBEDTLS_LMOTS_SIG_LEN + \
MBEDTLS_LMS_TYPE_LEN + MBEDTLS_LMS_H_TREE_HEIGHT * MBEDTLS_LMS_M_NODE_BYTES)
@@ -66,6 +70,29 @@
} mbedtls_lms_algorithm_type_t;
+/** LMS context structure.
+ *
+ * The context must be initialized before it is used. A public key must either
+ * be imported, or an algorithm type set, a private key generated and the public
+ * key calculated from it. A context that does not contain a public key cannot
+ * verify, and a context that does not contain a private key cannot sign.
+ *
+ * \dot
+ * digraph lmots {
+ * UNINITIALIZED -> INIT [label="init"];
+ * TYPE_SET -> INIT [label="free"];
+ * PRIVATE -> INIT [label="free"];
+ * PUBLIC -> INIT [label="free"];
+ * "PRIVATE+PUBLIC" -> INIT [label="free"];
+ * INIT -> TYPE_SET [label="set_algorithm_type"];
+ * INIT -> PUBLIC [label="import_public"];
+ * PUBLIC -> PUBLIC [label="export_pubkey"];
+ * "PRIVATE+PUBLIC" -> "PRIVATE+PUBLIC" [label="export_pubkey"];
+ * PRIVATE -> "PRIVATE+PUBLIC" [label="gen_pubkey"];
+ * TYPE_SET -> PRIVATE [label="gen_privkey"];
+ * }
+ * \enddot
+ */
typedef struct {
unsigned char MBEDTLS_PRIVATE(have_privkey); /*!< Whether the context contains a private key.
Boolean values only. */
@@ -123,9 +150,9 @@
* \brief This function creates a LMS signature, using a
* LMOTS context that contains a private key.
*
- * \note This function is intended for _testing purposes
- * only_, due to complexities around updating stateful
- * keys.
+ * \warning This function is **not intended for use in
+ * production**, due to as-yet unsolved problems with
+ * handling stateful keys.
*
* \note Before this function is called, the context must
* have been initialized and must contain a private
@@ -242,6 +269,10 @@
* \brief This function generates an LMS private key, and
* stores in into an LMS context.
*
+ * \warning This function is **not intended for use in
+ * production**, due to as-yet unsolved problems with
+ * handling stateful keys.
+ *
* \note Before this function is called, the context must
* have been initialized and the type of the LMS
* context set using mbedtls_lmots_set_algorithm_type