Mirrors/openssl
0
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2026-01-18 17:11:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

Add LMS documentation

Browse Source 
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)
This commit is contained in:
slontis
2024-10-03 17:52:49 +10:00
committed by Pauli
parent 48af66aef7
commit a3b9edcb79
9 changed files with 117 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/build.info
View File

@@ -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 \

8
doc/man3/EVP_PKEY_CTX_set_params.pod
View File

@@ -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.

6
doc/man3/EVP_PKEY_fromdata.pod
View File

@@ -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.

6
doc/man3/EVP_PKEY_todata.pod
View File

@@ -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.

19
doc/man7/EVP_PKEY-LMS.pod
View File

@@ -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

65
doc/man7/EVP_SIGNATURE-LMS.pod Normal file
View File

@@ -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

2
doc/man7/OSSL_PROVIDER-FIPS.pod
View File

@@ -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

2
doc/man7/OSSL_PROVIDER-default.pod
View File

@@ -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)>

8
doc/man7/provider-keymgmt.pod
View File

@@ -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.