Update LMS/LMOTS documentation
Signed-off-by: Raef Coles <raef.coles@arm.com>
diff --git a/ChangeLog.d/LMS.txt b/ChangeLog.d/LMS.txt
index 0f09f01..6de374f 100644
--- a/ChangeLog.d/LMS.txt
+++ b/ChangeLog.d/LMS.txt
@@ -1,12 +1,11 @@
Features
- * Add the LMS post-quantum-safe stateful-hash asymmetric signature scheme
- as defined in RFC8554 and NIST.SP.200-208. This currently only supports
- one parameter set (LMS_SHA256_M32_H10), meaning that each private key can
- be used to sign 1024 messages. As such, it is not intended for use in TLS,
- but instead for verification of assets transmitted over an insecure
- channel, particularly firmware images. This is one of the signature
- schemes recommended by the IETF draft SUIT standard for IOT firmware
- upgrades (RFC9019).
+ * Add the LMS post-quantum-safe stateful-hash asymmetric signature scheme.
+ Signature verification is production-ready, but generation is for testing
+ purposes only. This currently only supports one parameter set
+ (LMS_SHA256_M32_H10), meaning that each private key can be used to sign
+ 1024 messages. As such, it is not intended for use in TLS, but instead for
+ verification of assets transmitted over an insecure channel, particularly
+ firmware images.
* Add the LM-OTS post-quantum-safe one-time signature scheme, which is
required for LMS. This can be used independently, but each key can only be
used to sign one message so is impractical for most circumstances.
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