mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-03-31 20:10:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add SLH-DSA documentation

Browse Source 
Reviewed-by: Paul Dale <ppzgs1@gmail.com>
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/25882)
This commit is contained in:
slontis 2024-11-08 16:16:59 +11:00 committed by Tomas Mraz
parent 5c2b404241
commit 6de411963f
9 changed files with 288 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
CHANGES.md
View File

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

12
doc/build.info
View File

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

5
doc/man3/EVP_PKEY_fromdata.pod
View File

@ -275,13 +275,14 @@ L<EVP_PKEY-DH(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

5
doc/man3/EVP_PKEY_todata.pod
View File

@ -53,13 +53,14 @@ L<EVP_PKEY-DH(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-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

123
doc/man7/EVP_PKEY-SLH-DSA.pod Normal file
View File

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

130
doc/man7/EVP_SIGNATURE-SLH-DSA.pod Normal file
View File

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

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

@ -172,6 +172,8 @@ for signature generation, but may be used for verification for legacy use cases.
=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)>

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

@ -195,6 +195,8 @@ The OpenSSL default provider supports these operations and algorithms:
=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)>

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

@ -509,7 +509,8 @@ L<EVP_PKEY-RSA(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
@ -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<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