From fc875389ee4197c8a4aea86b6dbbfed6d65e5f85 Mon Sep 17 00:00:00 2001 From: slontis Date: Thu, 3 Oct 2024 17:52:49 +1000 Subject: [PATCH] Add LMS documentation Reviewed-by: Hugo Landau Reviewed-by: Dmitry Belyavskiy Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/25598) --- doc/build.info | 6 +++ doc/man3/EVP_PKEY_CTX_set_params.pod | 1 + doc/man3/EVP_PKEY_fromdata.pod | 2 +- doc/man3/EVP_PKEY_todata.pod | 2 +- doc/man7/EVP_PKEY-LMS.pod | 10 +++-- doc/man7/EVP_SIGNATURE-LMS.pod | 60 ++++++++++++++++++++++++++++ doc/man7/OSSL_PROVIDER-FIPS.pod | 2 + doc/man7/OSSL_PROVIDER-default.pod | 2 + doc/man7/provider-keymgmt.pod | 3 +- 9 files changed, 82 insertions(+), 6 deletions(-) create mode 100644 doc/man7/EVP_SIGNATURE-LMS.pod diff --git a/doc/build.info b/doc/build.info index 44e6ca27c07..e80c3d98ccc 100644 --- a/doc/build.info +++ b/doc/build.info @@ -4809,6 +4809,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-RSA.html]=man7/EVP_SIGNATURE-RSA.pod GENERATE[html/man7/EVP_SIGNATURE-RSA.html]=man7/EVP_SIGNATURE-RSA.pod DEPEND[man/man7/EVP_SIGNATURE-RSA.7]=man7/EVP_SIGNATURE-RSA.pod @@ -5160,6 +5164,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-RSA.html \ html/man7/OSSL_PROVIDER-FIPS.html \ html/man7/OSSL_PROVIDER-base.html \ @@ -5308,6 +5313,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-RSA.7 \ man/man7/OSSL_PROVIDER-FIPS.7 \ man/man7/OSSL_PROVIDER-base.7 \ diff --git a/doc/man3/EVP_PKEY_CTX_set_params.pod b/doc/man3/EVP_PKEY_CTX_set_params.pod index 8947648ccbe..7eaa9d64260 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 =head1 RETURN VALUES diff --git a/doc/man3/EVP_PKEY_fromdata.pod b/doc/man3/EVP_PKEY_fromdata.pod index 2cdbced9cfd..462c8867d02 100644 --- a/doc/man3/EVP_PKEY_fromdata.pod +++ b/doc/man3/EVP_PKEY_fromdata.pod @@ -261,7 +261,7 @@ L, L, L, L, L, L, L, L, L, L, L, L, -L +L, L =head1 HISTORY diff --git a/doc/man3/EVP_PKEY_todata.pod b/doc/man3/EVP_PKEY_todata.pod index c28a867b7a9..a5c9ada901a 100644 --- a/doc/man3/EVP_PKEY_todata.pod +++ b/doc/man3/EVP_PKEY_todata.pod @@ -45,7 +45,7 @@ L, L, L, L, L, L, L, L, L, L, -L +L, L =head1 HISTORY diff --git a/doc/man7/EVP_PKEY-LMS.pod b/doc/man7/EVP_PKEY-LMS.pod index db08c33e577..b55ce611db7 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 @@ -77,6 +80,7 @@ To load a LMS key from XDR encoded "data" of size "datalen": L, L, +L, L =head1 HISTORY diff --git a/doc/man7/EVP_SIGNATURE-LMS.pod b/doc/man7/EVP_SIGNATURE-LMS.pod new file mode 100644 index 00000000000..2ba2d49611c --- /dev/null +++ b/doc/man7/EVP_SIGNATURE-LMS.pod @@ -0,0 +1,60 @@ +=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 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.5.0 + +=head1 COPYRIGHT + +Copyright 2024 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 d370f9b5c53..e0f4dd5b899 100644 --- a/doc/man7/OSSL_PROVIDER-FIPS.pod +++ b/doc/man7/OSSL_PROVIDER-FIPS.pod @@ -170,6 +170,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 bc3fe22e171..c7ca5e6e84c 100644 --- a/doc/man7/OSSL_PROVIDER-default.pod +++ b/doc/man7/OSSL_PROVIDER-default.pod @@ -199,6 +199,8 @@ The OpenSSL default provider supports these operations and algorithms: =item CMAC, see L +=item LMS, see L + =back =head2 Asymmetric Cipher diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod index 1fed9faf35f..d4baaabb127 100644 --- a/doc/man7/provider-keymgmt.pod +++ b/doc/man7/provider-keymgmt.pod @@ -502,7 +502,8 @@ L, L, L, L, L, L, L, L, -L, L +L, L, +L =head1 HISTORY -- 2.47.2