diff --git a/CHANGES.md b/CHANGES.md index a9adbb4e3e..8dd1ccfdd2 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -39,17 +39,23 @@ OpenSSL 3.5 *Neil Horman* +* Add SLH-DSA as specified by FIPS 205. + + *Shane Lontis* + * ML-KEM as specified in FIPS 203. Based on the original implementation in BoringSSL, ported from C++ to C, refactored, and integrated into the OpenSSL default and FIPS providers. Including also the X25519MLKEM768, SecP256r1MLKEM768, SecP384r1MLKEM1024 TLS hybrid key post-quantum/classical key agreement schemes. + *Michael Baentsch, Viktor Dukhovni, Shane Lontis and Paul Dale* * Add ML-DSA as specified in FIPS 204. The base code was derived from BoringSSL C++ code. + *Shane Lontis, Viktor Dukhovni and Paul Dale* * Added new API calls to enable 3rd party QUIC stacks to use the OpenSSL TLS @@ -91,14 +97,14 @@ OpenSSL 3.5 *Viktor Dukhovni* - * All the BIO_meth_get_*() functions allowing reuse of the internal OpenSSL + * All the `BIO_meth_get_*()` functions allowing reuse of the internal OpenSSL BIO method implementations were deprecated. The reuse is unsafe due to dependency on the code of the internal methods not changing. *Tomáš Mráz* - * Support DEFAULT keyword and '-' prefix in SSL_CTX_set1_groups_list(). - SSL_CTX_set1_groups_list() now supports the DEFAULT keyword which sets the + * Support DEFAULT keyword and '-' prefix in `SSL_CTX_set1_groups_list()`. + `SSL_CTX_set1_groups_list()` now supports the DEFAULT keyword which sets the available groups to the default selection. The '-' prefix allows the calling application to remove a group from the selection. @@ -112,7 +118,7 @@ OpenSSL 3.5 *Aditya* * Enhanced PKCS#7 inner contents verification. - In the PKCS7_verify() function, the BIO *indata parameter refers to the + In the `PKCS7_verify()` function, the BIO *indata parameter refers to the signed data if the content is detached from p7. Otherwise, indata should be NULL, and then the signed data must be in p7. diff --git a/doc/build.info b/doc/build.info index 4a4cf94b43..bff57d5d50 100644 --- a/doc/build.info +++ b/doc/build.info @@ -4811,6 +4811,10 @@ DEPEND[html/man7/EVP_PKEY-RSA.html]=man7/EVP_PKEY-RSA.pod GENERATE[html/man7/EVP_PKEY-RSA.html]=man7/EVP_PKEY-RSA.pod DEPEND[man/man7/EVP_PKEY-RSA.7]=man7/EVP_PKEY-RSA.pod GENERATE[man/man7/EVP_PKEY-RSA.7]=man7/EVP_PKEY-RSA.pod +DEPEND[html/man7/EVP_PKEY-SLH-DSA.html]=man7/EVP_PKEY-SLH-DSA.pod +GENERATE[html/man7/EVP_PKEY-SLH-DSA.html]=man7/EVP_PKEY-SLH-DSA.pod +DEPEND[man/man7/EVP_PKEY-SLH-DSA.7]=man7/EVP_PKEY-SLH-DSA.pod +GENERATE[man/man7/EVP_PKEY-SLH-DSA.7]=man7/EVP_PKEY-SLH-DSA.pod DEPEND[html/man7/EVP_PKEY-SM2.html]=man7/EVP_PKEY-SM2.pod GENERATE[html/man7/EVP_PKEY-SM2.html]=man7/EVP_PKEY-SM2.pod DEPEND[man/man7/EVP_PKEY-SM2.7]=man7/EVP_PKEY-SM2.pod @@ -4875,6 +4879,10 @@ 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 GENERATE[man/man7/EVP_SIGNATURE-RSA.7]=man7/EVP_SIGNATURE-RSA.pod +DEPEND[html/man7/EVP_SIGNATURE-SLH-DSA.html]=man7/EVP_SIGNATURE-SLH-DSA.pod +GENERATE[html/man7/EVP_SIGNATURE-SLH-DSA.html]=man7/EVP_SIGNATURE-SLH-DSA.pod +DEPEND[man/man7/EVP_SIGNATURE-SLH-DSA.7]=man7/EVP_SIGNATURE-SLH-DSA.pod +GENERATE[man/man7/EVP_SIGNATURE-SLH-DSA.7]=man7/EVP_SIGNATURE-SLH-DSA.pod DEPEND[html/man7/OSSL_PROVIDER-FIPS.html]=man7/OSSL_PROVIDER-FIPS.pod GENERATE[html/man7/OSSL_PROVIDER-FIPS.html]=man7/OSSL_PROVIDER-FIPS.pod DEPEND[man/man7/OSSL_PROVIDER-FIPS.7]=man7/OSSL_PROVIDER-FIPS.pod @@ -5226,6 +5234,7 @@ html/man7/EVP_PKEY-HMAC.html \ html/man7/EVP_PKEY-ML-DSA.html \ html/man7/EVP_PKEY-ML-KEM.html \ html/man7/EVP_PKEY-RSA.html \ +html/man7/EVP_PKEY-SLH-DSA.html \ html/man7/EVP_PKEY-SM2.html \ html/man7/EVP_PKEY-X25519.html \ html/man7/EVP_RAND-CRNG-TEST.html \ @@ -5242,6 +5251,7 @@ html/man7/EVP_SIGNATURE-ED25519.html \ html/man7/EVP_SIGNATURE-HMAC.html \ html/man7/EVP_SIGNATURE-ML-DSA.html \ html/man7/EVP_SIGNATURE-RSA.html \ +html/man7/EVP_SIGNATURE-SLH-DSA.html \ html/man7/OSSL_PROVIDER-FIPS.html \ html/man7/OSSL_PROVIDER-base.html \ html/man7/OSSL_PROVIDER-default.html \ @@ -5381,6 +5391,7 @@ man/man7/EVP_PKEY-HMAC.7 \ man/man7/EVP_PKEY-ML-DSA.7 \ man/man7/EVP_PKEY-ML-KEM.7 \ man/man7/EVP_PKEY-RSA.7 \ +man/man7/EVP_PKEY-SLH-DSA.7 \ man/man7/EVP_PKEY-SM2.7 \ man/man7/EVP_PKEY-X25519.7 \ man/man7/EVP_RAND-CRNG-TEST.7 \ @@ -5397,6 +5408,7 @@ man/man7/EVP_SIGNATURE-ED25519.7 \ man/man7/EVP_SIGNATURE-HMAC.7 \ man/man7/EVP_SIGNATURE-ML-DSA.7 \ man/man7/EVP_SIGNATURE-RSA.7 \ +man/man7/EVP_SIGNATURE-SLH-DSA.7 \ man/man7/OSSL_PROVIDER-FIPS.7 \ man/man7/OSSL_PROVIDER-base.7 \ man/man7/OSSL_PROVIDER-default.7 \ diff --git a/doc/man3/EVP_PKEY_fromdata.pod b/doc/man3/EVP_PKEY_fromdata.pod index 5341716aa9..5f911c311c 100644 --- a/doc/man3/EVP_PKEY_fromdata.pod +++ b/doc/man3/EVP_PKEY_fromdata.pod @@ -275,13 +275,14 @@ L, L, L, L, -L. +L, +L. =head1 HISTORY These functions were added in OpenSSL 3.0. -Support for B and B was added in OpenSSL 3.5. +Support for B, B and B was added in OpenSSL 3.5. =head1 COPYRIGHT diff --git a/doc/man3/EVP_PKEY_todata.pod b/doc/man3/EVP_PKEY_todata.pod index a03c2933f6..7bfa061c34 100644 --- a/doc/man3/EVP_PKEY_todata.pod +++ b/doc/man3/EVP_PKEY_todata.pod @@ -53,13 +53,14 @@ L, L, L, L, -L. +L, +L. =head1 HISTORY These functions were added in OpenSSL 3.0. -Support for B and B was added in OpenSSL 3.5. +Support for B, B and B was added in OpenSSL 3.5. =head1 COPYRIGHT diff --git a/doc/man7/EVP_PKEY-SLH-DSA.pod b/doc/man7/EVP_PKEY-SLH-DSA.pod new file mode 100644 index 0000000000..7a0d2ad7a0 --- /dev/null +++ b/doc/man7/EVP_PKEY-SLH-DSA.pod @@ -0,0 +1,123 @@ +=pod + +=head1 NAME + +EVP_PKEY-SLH-DSA, EVP_KEYMGMT-SLH-DSA, +EVP_PKEY-SLH-DSA-SHA2-128s, EVP_PKEY-SLH-DSA-SHA2-128f, +EVP_PKEY-SLH-DSA-SHA2-192s, EVP_PKEY-SLH-DSA-SHA2-192f, +EVP_PKEY-SLH-DSA-SHA2-256s, EVP_PKEY-SLH-DSA-SHA2-256f, +EVP_PKEY-SLH-DSA-SHAKE-128s, EVP_PKEY-SLH-DSA-SHAKE-128f, +EVP_PKEY-SLH-DSA-SHAKE-192s, EVP_PKEY-SLH-DSA-SHAKE-192f, +EVP_PKEY-SLH-DSA-SHAKE-256s, EVP_PKEY-SLH-DSA-SHAKE-256f +- EVP_PKEY SLH-DSA keytype and algorithm support + +=head1 DESCRIPTION + +The B, B, +B, B, +B, B, +B, B, +B, B, +B and B key types are +implemented in OpenSSL's default and FIPS providers. These implementations +support the associated key, containing the public key I and the +private key I. + +Each of the different key types has an associated security parameter B. +This value is one of 16, 24 or 32 for key types B, B +and B respectively. + +Both the public and private key contain 2 elements of size B. +Key generation generates the private key elements and one of the public key +elements randomly, the final public key element is computed from these values. + +=head2 Keygen Parameters + +=over 4 + +=item "entropy" (B) + +Supplies values to use for the private seed, private prf and +public seed instead of generating random values. This is used for testing +purposes only. The length of the value supplied must be 3 * B. + +=item "properties" (B) + +Sets properties to be used when fetching algorithm implementations used for +SLH-DSA hashing operations. + +=back + +Use EVP_PKEY_CTX_set_params() after calling EVP_PKEY_keygen_init(). + +=head2 Common SLH-DSA parameters + +In addition to the common parameters that all keytypes should support (see +L), the implementation of these key types +support the following. + +The following parameters are gettable using EVP_PKEY_get_octet_string_param(), +and settable when using EVP_PKEY_fromdata(). + +=over 4 + +=item "pub" (B) + +The public key value of size 2 * B + +=item "priv" (B) + +The private key value of size 2 * B. + +=back + +=head1 CONFORMING TO + +=over 4 + +=item FIPS 205 + +=back + +=head1 EXAMPLES + +An B context can be obtained by calling: + + EVP_PKEY_CTX *pctx = + EVP_PKEY_CTX_new_from_name(NULL, "SLH-DSA-SHA2-128s", NULL); + +An B key can be generated like this: + + pkey = EVP_PKEY_Q_keygen(NULL, NULL, "SLH-DSA-SHA2-128s"); + +The key pair components can be extracted from a key by calling: + + uint8_t priv[64], pub[64]; + size_t priv_len, pub_len; + + EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PRIV_KEY, + priv, sizeof(priv), &priv_len); + EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PUB_KEY, + pub, sizeof(pub), &pub_len)); + +Similar code can be used for the other key types such as "SLH-DSA-SHAKE-256f". + +=head1 SEE ALSO + +L, L, L, +L + +=head1 HISTORY + +This functionality was added in OpenSSL 3.5. + +=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/EVP_SIGNATURE-SLH-DSA.pod b/doc/man7/EVP_SIGNATURE-SLH-DSA.pod new file mode 100644 index 0000000000..7b2bc38971 --- /dev/null +++ b/doc/man7/EVP_SIGNATURE-SLH-DSA.pod @@ -0,0 +1,130 @@ +=pod + +=head1 NAME + +EVP_SIGNATURE-SLH-DSA, +EVP_SIGNATURE-SLH-DSA-SHA2-128s, EVP_SIGNATURE-SLH-DSA-SHA2-128f, +EVP_SIGNATURE-SLH-DSA-SHA2-192s, EVP_SIGNATURE-SLH-DSA-SHA2-192f, +EVP_SIGNATURE-SLH-DSA-SHA2-256s, EVP_SIGNATURE-SLH-DSA-SHA2-256f, +EVP_SIGNATURE-SLH-DSA-SHAKE-128s, EVP_SIGNATURE-SLH-DSA-SHAKE-128f, +EVP_SIGNATURE-SLH-DSA-SHAKE-192s, EVP_SIGNATURE-SLH-DSA-SHAKE-192f, +EVP_SIGNATURE-SLH-DSA-SHAKE-256s, EVP_SIGNATURE-SLH-DSA-SHAKE-256f +- EVP_PKEY SLH-DSA support + +=head1 DESCRIPTION + +The B, B, +B, B, +B, B, +B, B, +B, B, +B and B EVP_PKEY implementations +supports key generation, one-shot sign and verify using the SLH-DSA +signature schemes described in FIPS 205. + +The different algorithms names correspond to the parameter sets defined in +FIPS 205 Section 11 Table 2. +'s' types have smaller signature sizes, and the 'f' variants are faster, +(The signatures range from ~8K to ~50K depending on the type chosen). There are +3 different security categories also depending on the type. + +L can be used to explicitely fetch one of the 12 +algorithms which can then be used with L, +L, L, and +L to sign or verify one-shot messages. + +The normal signing process (called Pure SLH-DSA Signature Generation) +encodes the message internally as 0x00 || len(ctx) || ctx || message. +where B is some optional value of size 0x00..0xFF. +OpenSSL also allows the message to not be encoded which is required for +testing. OpenSSL does not support Pre Hash SLH-DSA Signature Generation, but this +may be done by the user by doing Pre hash encoding externally and then chosing +the option to not encode the message. + +=head2 SLH-DSA Signature Parameters + +The following parameter can be used for both signing and verification. +it may be set by passing an OSSL_PARAM array to L or +L + +=over 4 + +=item "context-string" (B) + +A string of octets with length at most 255. By default it is the empty string. + +=back + +The following parameters can be used when signing: +They can be set by passing an OSSL_PARAM array to L. + +=over 4 + +=item "message-encoding" (B) + +The default value of 1 uses 'Pure SLH-DSA Signature Generation' as described +above. Setting it to 0 does not encode the message, which is used for testing, +but can also be used for 'Pre Hash SLH-DSA Signature Generation'. + +=item "additional-random" (B + +Used for testing to pass a optional random value. + +=item "deterministic" (B) + +The default value of 0 causes an randomly generated additional random value +to be used when processing the message. Setting this to 1 causes the private key +seed to be used instead. This value is ignored if "additional-random" is set. + +=back + +See L for information related to B keys. + + +=head1 EXAMPLES + +To sign a message using an SLH-DSA EVP_PKEY structure: + + void do_sign(EVP_PKEY *key, unsigned char *msg, size_t msg_len) + { + size_t sig_len; + unsigned char *sig = NULL; + const OSSL_PARAM params[] = { + OSSL_PARAM_octet_string("context-string", (unsigned char *)"A context string", 33), + OSSL_PARAM_END + }; + EVP_PKEY_CTX *sctx = EVP_PKEY_CTX_new_from_pkey(NULL, pkey, NULL); + EVP_SIGNATURE *sig_alg = EVP_SIGNATURE_fetch(NULL, "SLH-DSA-SHA2-128s", NULL); + + EVP_PKEY_sign_init_ex2(sctx, sig_alg, params); + /* Calculate the required size for the signature by passing a NULL buffer. */ + EVP_PKEY_sign(sctx, NULL, &sig_len, msg, msg_len); + sig = OPENSSL_zalloc(sig_len); + EVP_PKEY_sign(sctx, sig, &sig_len, msg, msg_len); + ... + OPENSSL_free(sig); + EVP_SIGNATURE(sig_alg); + EVP_PKEY_CTX_free(sctx); + } + +=head1 SEE ALSO + +L +L, +L, +L, + +=head1 HISTORY + +This functionality was added in OpenSSL 3.5. + +=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 d85c65017f..557296846e 100644 --- a/doc/man7/OSSL_PROVIDER-FIPS.pod +++ b/doc/man7/OSSL_PROVIDER-FIPS.pod @@ -172,6 +172,8 @@ for signature generation, but may be used for verification for legacy use cases. =item ML-DSA-87, see L +=item SLH-DSA, see L + =item HMAC, see L =item CMAC, see L diff --git a/doc/man7/OSSL_PROVIDER-default.pod b/doc/man7/OSSL_PROVIDER-default.pod index 6a9410e635..2fd6d105f0 100644 --- a/doc/man7/OSSL_PROVIDER-default.pod +++ b/doc/man7/OSSL_PROVIDER-default.pod @@ -195,6 +195,8 @@ The OpenSSL default provider supports these operations and algorithms: =item ECDSA, see L +=item SLH-DSA, see L + =item SM2 =item ML-DSA-44, see L diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod index 560b528e37..0b3128e5e9 100644 --- a/doc/man7/provider-keymgmt.pod +++ b/doc/man7/provider-keymgmt.pod @@ -509,7 +509,8 @@ L, L, L, L, -L. +L, +L. =head1 HISTORY @@ -523,7 +524,7 @@ OSSL_FUNC_keymgmt_gen_gettable_params() were added in OpenSSL 3.4. The parameters "sign-check" and "fips-indicator" were added in OpenSSL 3.4. -Support for the B and B algorithms was added in OpenSSL 3.5. +Support for the B, B and B algorithms was added in OpenSSL 3.5. =head1 COPYRIGHT