Add LMS documentation

Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Paul Dale <ppzgs1@gmail.com>
(Merged from https://github.com/openssl/openssl/pull/27885)

diff --git a/doc/build.info b/doc/build.info
index a92db008714f6c3efa42d95becc97e0bbf4d9e4f..a91a5c5798309f3362f4f919c17ef348bcdf73a9 100644 (file)
--- a/doc/build.info
+++ b/doc/build.info
@@ -4883,6 +4883,10 @@ DEPEND[html/man7/EVP_SIGNATURE-HMAC.html]=man7/EVP_SIGNATURE-HMAC.pod
 GENERATE[html/man7/EVP_SIGNATURE-HMAC.html]=man7/EVP_SIGNATURE-HMAC.pod
 DEPEND[man/man7/EVP_SIGNATURE-HMAC.7]=man7/EVP_SIGNATURE-HMAC.pod
 GENERATE[man/man7/EVP_SIGNATURE-HMAC.7]=man7/EVP_SIGNATURE-HMAC.pod
+DEPEND[html/man7/EVP_SIGNATURE-LMS.html]=man7/EVP_SIGNATURE-LMS.pod
+GENERATE[html/man7/EVP_SIGNATURE-LMS.html]=man7/EVP_SIGNATURE-LMS.pod
+DEPEND[man/man7/EVP_SIGNATURE-LMS.7]=man7/EVP_SIGNATURE-LMS.pod
+GENERATE[man/man7/EVP_SIGNATURE-LMS.7]=man7/EVP_SIGNATURE-LMS.pod
 DEPEND[html/man7/EVP_SIGNATURE-ML-DSA.html]=man7/EVP_SIGNATURE-ML-DSA.pod
 GENERATE[html/man7/EVP_SIGNATURE-ML-DSA.html]=man7/EVP_SIGNATURE-ML-DSA.pod
 DEPEND[man/man7/EVP_SIGNATURE-ML-DSA.7]=man7/EVP_SIGNATURE-ML-DSA.pod
@@ -5262,6 +5266,7 @@ html/man7/EVP_SIGNATURE-DSA.html \
 html/man7/EVP_SIGNATURE-ECDSA.html \
 html/man7/EVP_SIGNATURE-ED25519.html \
 html/man7/EVP_SIGNATURE-HMAC.html \
+html/man7/EVP_SIGNATURE-LMS.html \
 html/man7/EVP_SIGNATURE-ML-DSA.html \
 html/man7/EVP_SIGNATURE-RSA.html \
 html/man7/EVP_SIGNATURE-SLH-DSA.html \
@@ -5420,6 +5425,7 @@ man/man7/EVP_SIGNATURE-DSA.7 \
 man/man7/EVP_SIGNATURE-ECDSA.7 \
 man/man7/EVP_SIGNATURE-ED25519.7 \
 man/man7/EVP_SIGNATURE-HMAC.7 \
+man/man7/EVP_SIGNATURE-LMS.7 \
 man/man7/EVP_SIGNATURE-ML-DSA.7 \
 man/man7/EVP_SIGNATURE-RSA.7 \
 man/man7/EVP_SIGNATURE-SLH-DSA.7 \

diff --git a/doc/man3/EVP_PKEY_CTX_set_params.pod b/doc/man3/EVP_PKEY_CTX_set_params.pod
index 5faae0540cc0602108c59003b04a3b2845bfafd1..ebffe73f60ea8530d905385452161b0a89b0fdf7 100644 (file)
--- a/doc/man3/EVP_PKEY_CTX_set_params.pod
+++ b/doc/man3/EVP_PKEY_CTX_set_params.pod
@@ -57,6 +57,7 @@ L<EVP_PKEY-DH(7)/DH parameters>
 L<EVP_PKEY-DH(7)/DH key generation parameters>
 L<EVP_PKEY-EC(7)/Common EC parameters>
 L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>
+L<EVP_PKEY-LMS(7)/Common LMS parameters>
 L<EVP_PKEY-ML-DSA(7)/Common parameters>
 L<EVP_PKEY-ML-KEM(7)/Common parameters>
 
@@ -71,6 +72,11 @@ All other functions and macros described on this page return a positive value
 for success and 0 or a negative value for failure. In particular a return value
 of -2 indicates the operation is not supported by the public key algorithm.
 
+=head1 NOTES
+
+LMS support is disabled by default at compile-time.
+To enable, specify the B<enable-lms> build configuration option.
+
 =head1 SEE ALSO
 
 L<EVP_PKEY_CTX_new(3)>,
@@ -88,6 +94,8 @@ All functions were added in OpenSSL 3.0.
 
 Support for B<ML-DSA>> and B<ML-KEM> was added in OpenSSL 3.5.
 
+Support for B<LMS> was added in OpenSSL 3.6.
+
 =head1 COPYRIGHT
 
 Copyright 2020-2025 The OpenSSL Project Authors. All Rights Reserved.

diff --git a/doc/man3/EVP_PKEY_fromdata.pod b/doc/man3/EVP_PKEY_fromdata.pod
index 39a68be86acd0d449f3f38dbc35d5a6f12553000..3e3e7dab8ba62b5d049d90e57efdabe4cad2703e 100644 (file)
--- a/doc/man3/EVP_PKEY_fromdata.pod
+++ b/doc/man3/EVP_PKEY_fromdata.pod
@@ -86,6 +86,9 @@ public key and key parameters.
 These functions only work with key management methods coming from a provider.
 This is the mirror function to L<EVP_PKEY_todata(3)>.
 
+LMS support is disabled by default at compile-time.
+To enable, specify the B<enable-lms> build configuration option.
+
 =for comment We may choose to make this available for legacy methods too...
 
 =head1 RETURN VALUES
@@ -270,6 +273,7 @@ L<EVP_PKEY-RSA(7)>,
 L<EVP_PKEY-EC(7)>,
 L<EVP_PKEY-ED25519(7)>,
 L<EVP_PKEY-ED448(7)>,
+L<EVP_PKEY-LMS(7)>,
 L<EVP_PKEY-DSA(7)>,
 L<EVP_PKEY-DH(7)>,
 L<EVP_PKEY-X25519(7)>,
@@ -284,6 +288,8 @@ These functions were added in OpenSSL 3.0.
 
 Support for B<ML-DSA>, B<ML-KEM> and B<SLH-DSA> was added in OpenSSL 3.5.
 
+Support for B<LMS> was added in OpenSSL 3.6.
+
 =head1 COPYRIGHT
 
 Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved.

diff --git a/doc/man3/EVP_PKEY_todata.pod b/doc/man3/EVP_PKEY_todata.pod
index 9dee379a26724fde7cf451f17deb40252f2dec80..8e54f228ac737b72393f5a08f8fd92f5d6f574a5 100644 (file)
--- a/doc/man3/EVP_PKEY_todata.pod
+++ b/doc/man3/EVP_PKEY_todata.pod
@@ -35,6 +35,9 @@ EVP_PKEY_todata() if persistence is required.
 These functions only work with key management methods coming from a provider.
 This is the mirror function to L<EVP_PKEY_fromdata(3)>.
 
+LMS support is disabled by default at compile-time.
+To enable, specify the B<enable-lms> build configuration option.
+
 =head1 RETURN VALUES
 
 EVP_PKEY_todata() and EVP_PKEY_export() return 1 for success and 0 for failure.
@@ -52,6 +55,7 @@ L<EVP_PKEY-ED448(7)>,
 L<EVP_PKEY-DH(7)>,
 L<EVP_PKEY-X25519(7)>,
 L<EVP_PKEY-X448(7)>,
+L<EVP_PKEY-LMS(7)>,
 L<EVP_PKEY-ML-DSA(7)>,
 L<EVP_PKEY-ML-KEM(7)>,
 L<EVP_PKEY-SLH-DSA(7)>.
@@ -62,6 +66,8 @@ These functions were added in OpenSSL 3.0.
 
 Support for B<ML-DSA>, B<ML-KEM> and B<SLH-DSA> was added in OpenSSL 3.5.
 
+Support for B<LMS> was added in OpenSSL 3.6.
+
 =head1 COPYRIGHT
 
 Copyright 2021-2025 The OpenSSL Project Authors. All Rights Reserved.

diff --git a/doc/man7/EVP_PKEY-LMS.pod b/doc/man7/EVP_PKEY-LMS.pod
index db08c33e5779898140a70133c58f24801d1a734c..e794f8ae0e8fb7993b04f4664a82dc6d865cfc60 100644 (file)
--- a/doc/man7/EVP_PKEY-LMS.pod
+++ b/doc/man7/EVP_PKEY-LMS.pod
@@ -7,11 +7,14 @@ EVP_PKEY-LMS, EVP_KEYMGMT-LMS, LMS
 
 =head1 DESCRIPTION
 
-The B<LMS> keytype is implemented in OpenSSL's default provider.
+The B<LMS> keytype is implemented in OpenSSL's default and FIPS providers.
+The OpenSSL providers only support LMS signature verification, as this is a
+[SP 800-208](https://csrc.nist.gov/pubs/sp/800/208/final) requirement for
+software modules.
 
 =head2 Common LMS parameters
 
-LMS public keys are encoded in XDR format (i.e. not ANS1 format),
+LMS public keys are encoded in XDR format (i.e. not ASN1 format).
 The following parameters are used by EVP_PKEY_fromdata() and by the
 LMS keymanager for import and export.
 
@@ -32,7 +35,7 @@ is expected to be in XDR format.
 
 Leighton-Micali Hash-Based Signatures
 
-=item NIST SP 800-208
+=item NIST SP800-208
 
 Recommendation for Stateful Hash-Based Signature Schemes
 
@@ -42,6 +45,11 @@ Commercial National Security Algorithm Suite
 
 =back
 
+=head1 NOTES
+
+LMS support is disabled by default at compile-time.
+To enable it, specify the B<enable-lms> build configuration option.
+
 =head1 EXAMPLES
 
 NOTE error checking has been omitted in these examples
@@ -77,15 +85,16 @@ To load a LMS key from XDR encoded "data" of size "datalen":
 
 L<EVP_KEYMGMT(3)>,
 L<EVP_PKEY(3)>,
+L<EVP_SIGNATURE-LMS(7)>,
 L<provider-keymgmt(7)>
 
 =head1 HISTORY
 
-This functionality was added in OpenSSL 3.5.0
+This functionality was added in OpenSSL 3.6.
 
 =head1 COPYRIGHT
 
-Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy

diff --git a/doc/man7/EVP_SIGNATURE-LMS.pod b/doc/man7/EVP_SIGNATURE-LMS.pod
new file mode 100644 (file)
index 0000000..f4c7d25
--- /dev/null
+++ b/doc/man7/EVP_SIGNATURE-LMS.pod
@@ -0,0 +1,65 @@
+=pod
+
+=head1 NAME
+
+EVP_SIGNATURE-LMS
+- The EVP_PKEY Leighton-Micali Signature (LMS) implementation
+
+=head1 DESCRIPTION
+
+The B<LMS> EVP_PKEY implementation supports Leighton-Micali Signatures (LMS)
+described in [RFC 8554](https://datatracker.ietf.org/doc/html/rfc8854)
+and [SP 800-208](https://csrc.nist.gov/pubs/sp/800/208/final).
+
+The OpenSSL providers only support LMS signature verification, as this is a
+SP 800-208 requirement for software modules.
+
+EVP_PKEY_verify_message_init() and EVP_PKEY_verify() are the only supported
+functions used for LMS signatures. Streaming is not currently supported,
+and since the signature data contains data related to the digest used, functions
+that specify the digest name are not necessary.
+
+=head1 NOTES
+
+LMS support is disabled by default at compile-time.
+To enable, specify the B<enable-lms> build configuration option.
+
+=head1 EXAMPLES
+
+Error checking has been omitted from the following examples
+
+=head2 LMS signature verification
+
+ /* See L<EVP_PKEY-LMS(7)/EXAMPLES for an example of loading a LMS |pub| key */
+ ctx = EVP_PKEY_CTX_new_from_pkey(libctx, pub, propq);
+ sig = EVP_SIGNATURE_fetch(libctx, "LMS", propq);
+ EVP_PKEY_verify_message_init(ctx, sig, NULL);
+ /*
+  * EVP_PKEY_verify_message_update() and EVP_PKEY_verify_message_final()
+  * are not supported
+  */
+ ret = EVP_PKEY_verify(ctx, sigdata, sigdata_len, msg, msglen);
+ /*
+  * ret == 1 indicates success, 0 verify failure and < 0 for some
+  * other error.
+  */
+
+=head1 SEE ALSO
+
+L<EVP_PKEY-LMS(7)>,
+L<provider-signature(7)>,
+
+=head1 HISTORY
+
+This functionality was added in OpenSSL 3.6.
+
+=head1 COPYRIGHT
+
+Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut

diff --git a/doc/man7/OSSL_PROVIDER-FIPS.pod b/doc/man7/OSSL_PROVIDER-FIPS.pod
index d979f9c722dea81ae241e2bee19025cd3c5a94f2..a20373d2f12893d3b53d2f283e7697d33859bc5a 100644 (file)
--- a/doc/man7/OSSL_PROVIDER-FIPS.pod
+++ b/doc/man7/OSSL_PROVIDER-FIPS.pod
@@ -181,6 +181,8 @@ for signature generation, but may be used for verification for legacy use cases.
 
 =item CMAC, see L<EVP_SIGNATURE-CMAC(7)>
 
+=item LMS, see L<EVP_SIGNATURE-LMS(7)>
+
 =back
 
 =head2 Asymmetric Cipher

diff --git a/doc/man7/OSSL_PROVIDER-default.pod b/doc/man7/OSSL_PROVIDER-default.pod
index a4021418b50e4e2b7523c87c8dda89d4e705bdc9..f54815bd1cce0b73c9214be38a85dc4ac3c4c1d1 100644 (file)
--- a/doc/man7/OSSL_PROVIDER-default.pod
+++ b/doc/man7/OSSL_PROVIDER-default.pod
@@ -203,6 +203,8 @@ The OpenSSL default provider supports these operations and algorithms:
 
 =item SM2
 
+=item LMS, see L<EVP_SIGNATURE-LMS(7)>
+
 =item ML-DSA-44, see L<EVP_SIGNATURE-ML-DSA(7)>
 
 =item ML-DSA-65, see L<EVP_SIGNATURE-ML-DSA(7)>

diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod
index 1860814d318bec1ce64c548f1d8db1f20827e3a8..438309c2f0859ea7a01b3bba43d8577afa7255a8 100644 (file)
--- a/doc/man7/provider-keymgmt.pod
+++ b/doc/man7/provider-keymgmt.pod
@@ -500,6 +500,11 @@ OSSL_FUNC_keymgmt_export_types(), OSSL_FUNC_keymgmt_export_types_ex()
 should
 always return a constant L<OSSL_PARAM(3)> array.
 
+=head1 NOTES
+
+LMS support is disabled by default at compile-time.
+To enable, specify the B<enable-lms> build configuration option.
+
 =head1 SEE ALSO
 
 L<EVP_PKEY_get_size(3)>,
@@ -514,6 +519,7 @@ L<EVP_PKEY-EC(7)>,
 L<EVP_PKEY-RSA(7)>,
 L<EVP_PKEY-DSA(7)>,
 L<EVP_PKEY-DH(7)>,
+L<EVP_PKEY-LMS(7)>,
 L<EVP_PKEY-ML-DSA(7)>,
 L<EVP_PKEY-ML-KEM(7)>,
 L<EVP_PKEY-SLH-DSA(7)>.
@@ -532,6 +538,8 @@ The parameters "sign-check" and "fips-indicator" were added in OpenSSL 3.4.
 
 Support for the B<ML-DSA>, B<ML-KEM> and B<SLH-DSA> algorithms was added in OpenSSL 3.5.
 
+Support for the B<LMS> algorithm was added in OpenSSL 3.6.
+
 =head1 COPYRIGHT
 
 Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved.