From: slontis Date: Thu, 3 Oct 2024 07:52:49 +0000 (+1000) Subject: Add LMS documentation X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=a3b9edcb7906ebc8132b313a9223a6bf0527ee94;p=thirdparty%2Fopenssl.git Add LMS documentation Reviewed-by: Viktor Dukhovni Reviewed-by: Matt Caswell Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/27885) --- diff --git a/doc/build.info b/doc/build.info index a92db008714..a91a5c57983 100644 --- 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 5faae0540cc..ebffe73f60e 100644 --- a/doc/man3/EVP_PKEY_CTX_set_params.pod +++ b/doc/man3/EVP_PKEY_CTX_set_params.pod @@ -57,6 +57,7 @@ L L L L +L L L @@ -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 build configuration option. + =head1 SEE ALSO L, @@ -88,6 +94,8 @@ All functions were added in OpenSSL 3.0. Support for B> and B was added in OpenSSL 3.5. +Support for B 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 39a68be86ac..3e3e7dab8ba 100644 --- 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. +LMS support is disabled by default at compile-time. +To enable, specify the B build configuration option. + =for comment We may choose to make this available for legacy methods too... =head1 RETURN VALUES @@ -270,6 +273,7 @@ L, L, L, L, +L, L, L, L, @@ -284,6 +288,8 @@ These functions were added in OpenSSL 3.0. Support for B, B and B was added in OpenSSL 3.5. +Support for B 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 9dee379a267..8e54f228ac7 100644 --- 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. +LMS support is disabled by default at compile-time. +To enable, specify the B 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, L, L, L, +L, L, L, L. @@ -62,6 +66,8 @@ These functions were added in OpenSSL 3.0. Support for B, B and B was added in OpenSSL 3.5. +Support for B 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 db08c33e577..e794f8ae0e8 100644 --- 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 keytype is implemented in OpenSSL's default provider. +The B 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 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, L, +L, L =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 index 00000000000..f4c7d255601 --- /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 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 build configuration option. + +=head1 EXAMPLES + +Error checking has been omitted from the following examples + +=head2 LMS signature verification + + /* See L, +L, + +=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. + +=cut diff --git a/doc/man7/OSSL_PROVIDER-FIPS.pod b/doc/man7/OSSL_PROVIDER-FIPS.pod index d979f9c722d..a20373d2f12 100644 --- 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 +=item LMS, see L + =back =head2 Asymmetric Cipher diff --git a/doc/man7/OSSL_PROVIDER-default.pod b/doc/man7/OSSL_PROVIDER-default.pod index a4021418b50..f54815bd1cc 100644 --- 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 + =item ML-DSA-44, see L =item ML-DSA-65, see L diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod index 1860814d318..438309c2f08 100644 --- 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 array. +=head1 NOTES + +LMS support is disabled by default at compile-time. +To enable, specify the B build configuration option. + =head1 SEE ALSO L, @@ -514,6 +519,7 @@ L, L, L, L, +L, L, L, L. @@ -532,6 +538,8 @@ The parameters "sign-check" and "fips-indicator" were added in OpenSSL 3.4. Support for the B, B and B algorithms was added in OpenSSL 3.5. +Support for the B algorithm was added in OpenSSL 3.6. + =head1 COPYRIGHT Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved.