*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
*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.
*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.
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
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
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 \
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 \
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 \
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 \
L<EVP_PKEY-X25519(7)>,
L<EVP_PKEY-X448(7)>,
L<EVP_PKEY-ML-DSA(7)>,
-L<EVP_PKEY-ML-KEM(7)>.
+L<EVP_PKEY-ML-KEM(7)>,
+L<EVP_PKEY-SLH-DSA(7)>.
=head1 HISTORY
These 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<ML-DSA>, B<ML-KEM> and B<SLH-DSA> was added in OpenSSL 3.5.
=head1 COPYRIGHT
L<EVP_PKEY-X25519(7)>,
L<EVP_PKEY-X448(7)>,
L<EVP_PKEY-ML-DSA(7)>,
-L<EVP_PKEY-ML-KEM(7)>.
+L<EVP_PKEY-ML-KEM(7)>,
+L<EVP_PKEY-SLH-DSA(7)>.
=head1 HISTORY
These functions were added in OpenSSL 3.0.
-Support for B<ML-KEM> and B<ML-DSA> was added in OpenSSL 3.5.
+Support for B<ML-DSA>, B<ML-KEM> and B<SLH-DSA> was added in OpenSSL 3.5.
=head1 COPYRIGHT
--- /dev/null
+=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<SLH-DSA-SHA2-128s>, B<EVP_PKEY-SLH-DSA-SHA2-128f>,
+B<SLH-DSA-SHA2-192s>, B<EVP_PKEY-SLH-DSA-SHA2-192f>,
+B<SLH-DSA-SHA2-256s>, B<EVP_PKEY-SLH-DSA-SHA2-256f>,
+B<SLH-DSA-SHAKE-128s>, B<EVP_PKEY-SLH-DSA-SHAKE-128f>,
+B<SLH-DSA-SHAKE-192s>, B<EVP_PKEY-SLH-DSA-SHAKE-192f>,
+B<SLH-DSA-SHAKE-256s> and B<EVP_PKEY-SLH-DSA-SHAKE-256f> key types are
+implemented in OpenSSL's default and FIPS providers. These implementations
+support the associated key, containing the public key I<pub> and the
+private key I<priv>.
+
+Each of the different key types has an associated security parameter B<n>.
+This value is one of 16, 24 or 32 for key types B<SLH-DSA*128*>, B<SLH-DSA*192*>
+and B<SLH-DSA*256*> respectively.
+
+Both the public and private key contain 2 elements of size B<n>.
+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<OOSSL_PKEY_PARAM_SLH_DSA_ENTROPY>) <octet string>
+
+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<n>.
+
+=item "properties" (B<OSSL_PKEY_PARAM_PROPERTIES>) <utf8_string>
+
+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<provider-keymgmt(7)/Common parameters>), 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<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
+
+The public key value of size 2 * B<n>
+
+=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string>
+
+The private key value of size 2 * B<n>.
+
+=back
+
+=head1 CONFORMING TO
+
+=over 4
+
+=item FIPS 205
+
+=back
+
+=head1 EXAMPLES
+
+An B<EVP_PKEY> context can be obtained by calling:
+
+ EVP_PKEY_CTX *pctx =
+ EVP_PKEY_CTX_new_from_name(NULL, "SLH-DSA-SHA2-128s", NULL);
+
+An B<SLH-DSA> 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<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>,
+L<EVP_SIGNATURE-SLH-DSA(7)>
+
+=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<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=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<SLH-DSA-SHA2-128s>, B<EVP_PKEY-SLH-DSA-SHA2-128f>,
+B<SLH-DSA-SHA2-192s>, B<EVP_PKEY-SLH-DSA-SHA2-192f>,
+B<SLH-DSA-SHA2-256s>, B<EVP_PKEY-SLH-DSA-SHA2-256f>,
+B<SLH-DSA-SHAKE-128s>, B<EVP_PKEY-SLH-DSA-SHAKE-128f>,
+B<SLH-DSA-SHAKE-192s>, B<EVP_PKEY-SLH-DSA-SHAKE-192f>,
+B<SLH-DSA-SHAKE-256s> and B<EVP_PKEY-SLH-DSA-SHAKE-256f> 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<EVP_SIGNATURE_fetch(3)> can be used to explicitely fetch one of the 12
+algorithms which can then be used with L<EVP_PKEY_sign_init_ex2(3)>,
+L<EVP_PKEY_sign(3)>, L<EVP_PKEY_verify_init_ex2(3)>, and
+L<EVP_PKEY_verify(3)> 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<ctx> 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<EVP_PKEY_sign_init_ex2(3)> or
+L<EVP_PKEY_verify_init_ex2(3)>
+
+=over 4
+
+=item "context-string" (B<OSSL_SIGNATURE_PARAM_CONTEXT_STRING>) <octet string>
+
+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<EVP_PKEY_sign_init_ex2(3)>.
+
+=over 4
+
+=item "message-encoding" (B<OSSL_SIGNATURE_PARAM_MESSAGE_ENCODING>) <integer>
+
+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<OSSL_SIGNATURE_PARAM_ADD_RANDOM <octet string>
+
+Used for testing to pass a optional random value.
+
+=item "deterministic" (B<OSSL_SIGNATURE_PARAM_DETERMINISTIC>) <integer>
+
+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<EVP_PKEY-SLH-DSA(7)> for information related to B<SLH-DSA> 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<EVP_PKEY-SLH-DSA(7)>
+L<provider-signature(7)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)>,
+
+=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<https://www.openssl.org/source/license.html>.
+
+=cut
=item ML-DSA-87, see L<EVP_SIGNATURE-ML-DSA(7)>
+=item SLH-DSA, see L<EVP_SIGNATURE-SLH-DSA(7)>
+
=item HMAC, see L<EVP_SIGNATURE-HMAC(7)>
=item CMAC, see L<EVP_SIGNATURE-CMAC(7)>
=item ECDSA, see L<EVP_SIGNATURE-ECDSA(7)>
+=item SLH-DSA, see L<EVP_SIGNATURE-SLH-DSA(7)>
+
=item SM2
=item ML-DSA-44, see L<EVP_SIGNATURE-ML-DSA(7)>
L<EVP_PKEY-DSA(7)>,
L<EVP_PKEY-DH(7)>,
L<EVP_PKEY-ML-DSA(7)>,
-L<EVP_PKEY-ML-KEM(7)>.
+L<EVP_PKEY-ML-KEM(7)>,
+L<EVP_PKEY-SLH-DSA(7)>.
=head1 HISTORY
The parameters "sign-check" and "fips-indicator" were added in OpenSSL 3.4.
-Support for the B<ML-DSA> and B<ML-KEM> algorithms was added in OpenSSL 3.5.
+Support for the B<ML-DSA>, B<ML-KEM> and B<SLH-DSA> algorithms was added in OpenSSL 3.5.
=head1 COPYRIGHT
projects / thirdparty / openssl.git / commitdiff
