### Changes between 3.4 and 3.5 [xx XXX xxxx]
+* 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.
### no-{algorithm}
no-{aria|bf|blake2|camellia|cast|chacha|cmac|
- des|dh|dsa|ecdh|ecdsa|idea|md4|mdc2|ml-kem|
- ocb|poly1305|rc2|rc4|rmd160|scrypt|seed|
- siphash|siv|sm2|sm3|sm4|whirlpool}
+ des|dh|dsa|ecdh|ecdsa|idea|md4|mdc2|ml-dsa|
+ ml-kem|ocb|poly1305|rc2|rc4|rmd160|scrypt|
+ seed|siphash|siv|sm2|sm3|sm4|whirlpool}
Build without support for the specified algorithm.
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256
+5. To generate an ML-DSA key
-5. NOTE
+An ML-DSA key can be used for signing (and verification via the public key)
+only.
+
+Generating a key for the ML-DSA algorithm is a one-step process.
+
+ openssl genpkey -algorithm ML-DSA-44 -out key.pem
+ openssl genpkey -algorithm ML-DSA-65 -out key.pem
+ openssl genpkey -algorithm ML-DSA-87 -out key.pem
+
+See L<EVP_PKEY-ML-DSA(7)> for more detail.
+
+6. To generate an ML-KEM key
+
+An ML-KEM key can be used for decapsulation (and encapsulation via the public
+key) only.
+
+Generating a key for the ML-KEM algorithm is a one-step process.
+
+ openssl genpkey -algorithm ML-KEM-512 -out key.pem
+ openssl genpkey -algorithm ML-KEM-768 -out key.pem
+ openssl genpkey -algorithm ML-KEM-1024 -out key.pem
+
+See L<EVP_PKEY-ML-KEM(7)> for more detail.
+
+7. NOTE
If you intend to use the key together with a server certificate,
it may be reasonable to avoid protecting it with a password, since
following command to generate an X25519 key:
openssl genpkey -algorithm X25519 -out xkey.pem
-
-# TODO(ML-KEM) Likewise ML-KEM once we have codecs.
If we chose not to remove them , then we need to check that OSSL_PKEY_PARAM_USE_COFACTOR_ECDH is set for key agreement if the cofactor is not 1.
- ED25519 and ED448 are now approved.
- X25519 and X448 are not approved currently. keygen and keyexchange would also need an indicator if we allow them?
-- ML-KEM-512/768/1024 are not yet included in the FIPS module.
- RSA encryption(for key agreement/key transport) using PKCSV15 is no longer allowed. (Note that this breaks TLS 1.2 using RSA for KeyAgreement),
Padding mode updates required. Check RSA KEM also.
- RSA signing using PKCS1 is still allowed (i.e. signature uses shaXXXWithRSAEncryption)
pseudo code for all its algorithms.
The base code for OpenSSL has been derived from the BoringSSL C++ code.
-As OpenSSL is c code, templates can not be used. The OpenSSL code instead uses
+As OpenSSL is C code, templates can not be used. The OpenSSL code instead uses
parameters to pass algorithm specific constants, and also uses these constants
to run different conditional functions when required.
-ML_DSA Parameters & Per algorithm Functions
+ML-DSA Parameters & Per algorithm Functions
-------------------------------------------
FIPS 204 contains 3 algorithms for different security strengths.
FIPS 204 Section 4 Table 1 & Table 2 specifies different constants that are
-stored in a table of ML_DSA_PARAM objects.
+stored in a table of `ML_DSA_PARAM` objects.
The constants include key sizes and coefficient ranges.
OpenSSL uses 3 key managers and 3 signature functions corresponding to the algorithms
ML-DSA-44, ML-DSA-65 and ML-DSA-87.
-ML-DSA only uses SHAKE-128 and SHAKE-256 for digest operations, so these values
-are pre-fetched and stored within a ML_DSA key. Any functions that require these
-pre-fetched objects must pass either the key or the pre-fetched object within the key
-as a parameter. A temporary EVP_MD_CTX is created as needed and the shake object(s)
-are set into this ctx.
+ML-DSA only uses SHAKE-128 and SHAKE-256 for digest operations, so these digest
+algorithms are pre-fetched and stored within a `ML_DSA` key.
+Any functions that require these pre-fetched objects must pass either the key
+or the pre-fetched object within the key as a parameter.
+A temporary `EVP_MD_CTX` is created as needed and the shake object(s) are set
+into this ctx.
-Initially a separate object called ML_DSA_CTX object was passed around that
-contained 2 EVP_MD_CTX's containing the pre-fetched EVP_MD shake objects. It was
+Initially a separate object called `ML_DSA_CTX` object was passed around that
+contained 2 `EVP_MD_CTXs` with the pre-fetched `EVP_MD` shake objects. It was
modified to match the ML-KEM code.
ML-DSA keys
that the public key is also supplied, an error will occur if the generated public
key does not match the supplied public key.
-An ML_DSA polynomial contains 256 32 bit values which is 1K of space.
+An `ML_DSA` polynomial contains 256 32 bit values which is 1K of space.
Keys store vectors of size 'k' or 'l' plus a matrix of size 'k' * 'l',
where (k, l) correspond to (4,4), (6,5) or (8,7). The key data could be large
if buffers of the maximum size of (8,7) are used for the (4,4) use case.
Keys are not allowed to mutate, so checks are done during load to check that the
public and private key components are not changed once set.
-ossl_ml_dsa_key_get_pub() and ossl_ml_dsa_key_get_priv() return the
+`ossl_ml_dsa_key_get_pub()` and `ossl_ml_dsa_key_get_priv()` return the
encoded forms of the key components (which are stored within the key).
The hash of the encoded public key is also stored in the key.
This will be controlled by settable parameters.
Pre Hash ML-DSA Signature Generation encode the message as
+
+```text
0x01 || len(ctx) || ctx || digest_OID || H(message).
+```
+
The scenario that is stated that this is useful for is when this encoded message
is supplied from an external source.
This ensures domain separation between signature variants
-Currently I do not support the Pre Hash variant as this does not sit well with the
-OpenSSL API's. The user could do the encoding themselves and then set the settable
-to not encode the passed in message.
+Currently OpenSSL does not support the Pre Hash variant as this does not sit
+well with the OpenSSL API's.
+The user could do the encoding themselves and then set the settable to not
+encode the passed in message.
Signing API
-------------
As only the one-shot implementation is required and the message is not digested
the API's used should be
-EVP_PKEY_sign_message_init(), EVP_PKEY_sign(),
-EVP_PKEY_verify_message_init(), EVP_PKEY_verify().
+`EVP_PKEY_sign_message_init()`, `EVP_PKEY_sign()`,
+`EVP_PKEY_verify_message_init()`, `EVP_PKEY_verify()`.
OpenSSL command line support
----------------------------
-For backwards compatability reasons EVP_DigestSignInit_ex(), EVP_DigestSign(),
-EVP_DigestVerifyInit_ex() and EVP_DigestVerify() may also be used, but the digest
-passed in `mdname` must be NULL (i.e. it effectively behaves the same as above).
+For backwards compatability reasons `EVP_DigestSignInit_ex()`,
+`EVP_DigestSign()`, `EVP_DigestVerifyInit_ex()` and `EVP_DigestVerify()` may
+also be used, but the digest passed in `mdname` must be NULL (i.e. it
+effectively behaves the same as above).
Passing a non NULL digest results in an error.
-OSSL_PKEY_PARAM_MANDATORY_DIGEST must return "" in the key manager getter and
-OSSL_SIGNATURE_PARAM_ALGORITHM_ID in the signature context getter.
+`OSSL_PKEY_PARAM_MANDATORY_DIGEST` must return "" in the key manager getter and
+`OSSL_SIGNATURE_PARAM_ALGORITHM_ID` in the signature context getter.
Encoding/Decoding
-----------------
Differences between BoringSSL and FIPS 204 pseudo code
------------------------------------------------------
-The symmetric modulus operation normally gives a result in the range -a/2 ... a/2.
-BoringSSL chose to keep the result positive by adding q and reducing once is required.
+The symmetric modulus operation normally gives a result in the range -a/2 ...
+a/2.
+BoringSSL chose to keep the result positive by adding q and reducing once as
+required.
-Montgomery multiplication is used to speed up multiplications (See FIPS 204 Appendix A).
+Montgomery multiplication is used to speed up multiplications (See FIPS 204
+Appendix A).
L<EVP_PKEY-DH(7)>,
L<EVP_PKEY-EC(7)>,
L<EVP_PKEY-X25519(7)>,
+L<EVP_PKEY-ML-DSA(7)>,
L<EVP_PKEY-ML-KEM(7)>.
=head1 COPYRIGHT
the standard built-in ones.
Valid built-in algorithm names for private key generation are RSA, RSA-PSS, EC,
-X25519, X448, ED25519 and ED448.
-
-=for comment TODO(ML-KEM) Soon also ML-KEM, once we have a standard private key
- format (and a PEM header name) and encoders/decoders.
+X25519, X448, ED25519, ED448, ML-DSA and ML-KEM.
Valid built-in algorithm names for parameter generation (see the B<-genparam>
option) are DH, DSA and EC.
below. There are no key generation options defined for the X25519, X448, ED25519
or ED448 algorithms.
-=for comment TODO(ML-KEM) Soon also ML-KEM, once we have a standard private key
- format (and a PEM header name) and encoders/decoders.
-
=head2 RSA Key Generation Options
=over 4
=back
+=head2 ML-DSA Key Generation Options
+
+=over 4
+
+=item B<hexseed>:I<seed>
+
+This specifies the optional ML-DSA I<seed> in hexadecimal form. The seed is 32
+bytes, giving 64 hexadecimal digits.
+When generated from an explicit seed the key is completely determined by the
+seed value.
+If other users can see the command-line arguments of the running process, this
+option may compromise the secret key, it is best avoided, tests-aside.
+
+See L<EVP_PKEY-ML-DSA(7)> for more detail.
+
+=back
+
+=head2 ML-KEM Key Generation Options
+
+=over 4
+
+=item B<hexseed>:I<seed>
+
+This specifies the optional ML-KEM I<seed> in hexadecimal form. The seed is 64
+bytes, giving 128 hexadecimal digits.
+When generated from an explicit seed the key is completely determined by the
+seed value.
+If other users can see the command-line arguments of the running process, this
+option may compromise the secret key, it is best avoided, tests-aside.
+
+See L<EVP_PKEY-ML-KEM(7)> for more detail.
+
+=back
+
=head2 DH Key Generation Options
=over 4
openssl genpkey -algorithm ED448 -out xkey.pem
-=for comment TODO(ML-KEM) Soon also ML-KEM, once we have a standard private key
- format (and a PEM header name) and encoders/decoders.
+Generate an ML-DSA-65 private key:
+
+ openssl genpkey -algorithm ML-DSA-65 -out ml-dsa-key.pem
+
+Generate an ML-KEM-768 private key:
+
+ openssl genpkey -algorithm ML-KEM-768 -out ml-kem-key.pem
=head1 HISTORY
The ability to generate X25519 keys was added in OpenSSL 1.1.0.
The ability to generate X448, ED25519 and ED448 keys was added in OpenSSL 1.1.1.
-=for comment TODO(ML-KEM) Soon also ML-KEM, once we have a standard private key
- format (and a PEM header name) and encoders/decoders.
-
The B<-engine> option was deprecated in OpenSSL 3.0.
+Support for B<ML-DSA> and B<ML-KEM> was added in OpenSSL 3.5.
+
=head1 COPYRIGHT
Copyright 2006-2024 The OpenSSL Project Authors. All Rights Reserved.
to encapsulate and decapsulate shared secrets with the chosen key type.
This is needed only for RSA, where B<RSASVE>, is not the default mode, even
though it is presently the only RSA KEM supported.
-See L<EVP_PKEY_CTX_set_kem_op(3)> and L<EVP_KEM-RSA(7)>.
-
-=for comment TODO(ML-KEM) Add ML-KEM, once we have encoder/decoder support the
- associated keys. Specifically, the private key format is yet to
- be decided (may need to support two versions, the full FIPS203
- encoding or just the seed).
+See L<EVP_PKEY_CTX_set_kem_op(3)>, L<EVP_KEM-RSA(7)> and L<EVP_KEM-ML-KEM(7)>.
=item B<-kdf> I<algorithm>
The X25519 and X448 algorithms support key derivation only. Currently there are
no additional options.
-=for comment TODO(ML-KEM) Likewise for ML-KEM, once we have encoders/decoders.
+=head1 ML-DSA-44, ML-DSA-65 AND ML-DSA-87 ALGORITHMS
+
+The B<ML-DSA> algorithms support signing and verification of "raw" messages.
+No preliminary hashing is performed.
+
+The signing operation supports a B<deterministic>:I<bool> option,
+with I<bool> set to C<1> if a deterministic signature is to be generated
+with a fixed all zero random input.
+By default, or if the I<bool> is C<0> a random entropy value is used.
+A deterministic result can also be obtained by specifying an explicit
+entropy value via the B<hextest-entropy>:I<value> parameter.
+Deterministic B<ML-DSA> signing should only be used in tests.
+
+See L<EVP_SIGNATURE-ML-DSA(7)> for additional options and detail.
+
+=head1 ML-KEM-512, ML-KEM-768 AND ML-KEM-1024 ALGORITHMS
+
+The ML-KEM algorithms support encapsulation and decapsulation only.
+The encapsulation operation supports a B<hexikme>:I<entropy> option,
+with I<entropy> the 64 hexadecimal digit encoding of a 32-byte value.
+This should only be used in tests, known or leaked values of the option may
+compromise the generated shared secret.
+
+See L<EVP_KEM-ML-KEM(7)> for additional detail.
=head1 ED25519 AND ED448 ALGORITHMS
L<EVP_PKEY-DH(7)/DH key generation parameters>
L<EVP_PKEY-EC(7)/Common EC parameters>
L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>
+L<EVP_PKEY-ML-DSA(7)/Common parameters>
L<EVP_PKEY-ML-KEM(7)/Common parameters>
=head1 RETURN VALUES
All functions were added in OpenSSL 3.0.
-Support for B<ML-KEM> was added in OpenSSL 3.5.
+Support for B<ML-DSA>> and B<ML-KEM> was added in OpenSSL 3.5.
=head1 COPYRIGHT
L<B<EVP_PKEY-X25519>(7)|EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>,
L<B<EVP_PKEY-X448>(7)|EVP_PKEY-X448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
L<B<EVP_PKEY-ED25519>(7)|EVP_PKEY-ED25519(7)/Common X25519, X448, ED25519 and ED448 parameters>,
+L<B<EVP_PKEY-ML-DSA(7)>|EVP_PKEY-ML-DSA(7)/Common parameters>
and
-L<EVP_PKEY-ML-KEM-512(7)|EVP_PKEY-ML-KEM-768(7)|EVP_PKEY-ML-KEM-1024(7)/Common parameters>
+L<B<EVP_PKEY-ML-KEM(7)>|EVP_PKEY-ML-KEM(7)/Common parameters>
pages.
=for comment the awful list of links above is made this way so we get nice
These functions were added in OpenSSL 3.0.
-Support for B<ML-KEM> was added in OpenSSL 3.5.
+Support for B<ML-DSA> and B<ML-KEM> was added in OpenSSL 3.5.
=head1 COPYRIGHT
C<SM2>,
C<X25519>,
C<X448>,
+C<ML-DSA-44>,
+C<ML-DSA-65>,
+C<ML-DSA-87>,
C<ML-KEM-512>,
C<ML-KEM-768>, or
C<ML-KEM-1024>
C<ED448>,
C<X25519>,
C<X448>,
+C<ML-DSA-44>,
+C<ML-DSA-65>,
+C<ML-DSA-87>,
C<ML-KEM-512>,
C<ML-KEM-768>,
or
B<ED448>,
B<X25519>,
B<X448>,
+C<ML-DSA-44>,
+C<ML-DSA-65>,
+C<ML-DSA-87>,
B<ML-KEM-512>,
B<ML-KEM-768>,
and
B<ML-KEM-1024>.
EVP_PKEY_new_raw_public_key() works in the same way as
-EVP_PKEY_new_raw_private_key() except that I<key> points to the raw public key
-data. The B<EVP_PKEY> structure will be initialised without any private key
-information. Algorithm types that support raw public keys are
-B<ED448>.
-B<ED25519>,
-B<X25519>,
-B<X448>
-B<ML-KEM-512>,
-B<ML-KEM-768>,
-and
-B<ML-KEM-1024>.
+EVP_PKEY_new_raw_private_key_ex() except that I<key> points to the raw public
+key data.
+The B<EVP_PKEY> structure will be initialised without any private key
+information.
EVP_PKEY_new_mac_key() works in the same way as EVP_PKEY_new_raw_private_key().
New applications should use EVP_PKEY_new_raw_private_key() instead.
B<POLY1305>,
and
B<SIPHASH>.
-EVP_PKEY_get_raw_private_key() also works with B<ML-KEM-512>, B<ML-KEM-768> and
-B<ML-KEM-1024> keys, which don't have legacy numeric I<NID> assigments, but
-their raw form is nevertheless available.
+EVP_PKEY_get_raw_private_key() also works with
+C<ML-DSA-44>,
+C<ML-DSA-65>,
+C<ML-DSA-87>,
+B<ML-KEM-512>,
+B<ML-KEM-768> and
+B<ML-KEM-1024>
+keys, which don't have legacy numeric I<NID> assigments, but their raw form is
+nevertheless available.
EVP_PKEY_get_raw_public_key() fills the buffer provided by I<pub> with raw
B<X25519>,
and
B<X448>
-EVP_PKEY_get_raw_public_key() also works with B<ML-KEM-512>, B<ML-KEM-768> and
-B<ML-KEM-1024> keys, which don't have legacy numeric I<NID> assigments, but
-their raw form is nevertheless available.
+EVP_PKEY_get_raw_public_key() also works with
+C<ML-DSA-44>,
+C<ML-DSA-65>,
+C<ML-DSA-87>,
+B<ML-KEM-512>,
+B<ML-KEM-768> and
+B<ML-KEM-1024>
+keys, which don't have legacy numeric I<NID> assigments, but their raw form is
+nevertheless available.
EVP_PKEY_new_CMAC_key() works in the same way as EVP_PKEY_new_raw_private_key()
except it is only for the B<EVP_PKEY_CMAC> algorithm type. In addition to the
L<EVP_PKEY-Siphash(7)>,
L<EVP_PKEY-X25519(7)>,
L<EVP_PKEY-X448(7)>,
-L<EVP_PKEY-ML-KEM-512(7)>,
-L<EVP_PKEY-ML-KEM-768(7)>,
-L<EVP_PKEY-ML-KEM-1024(7)>.
+L<EVP_PKEY-ML-DSA(7)>,
+L<EVP_PKEY-ML-KEM(7)>.
=head1 HISTORY
be the private part of the keypair without the public part, where this was
previously implied to be disallowed.
-Support for B<ML-KEM> was added in OpenSSL 3.5.
+Support for B<ML-DSA> and B<ML-KEM> was added in OpenSSL 3.5.
=head1 COPYRIGHT
FIPS 203, section 6.2, algorithm 17.
This parameter should not be used for purposes other than testing.
-This parameter is disabled for use in the FIPS provider (TODO(ML-KEM)).
When this parameter is not set, encapsulation proceeds as per FIPS 203,
section 7.2
=item ML-DSA-87
-=for comment TODO(ML-KEM): We don't yet have encoders for ML-KEM.
+=item ML-KEM-512
+
+=item ML-KEM-768
+
+=item ML-KEM-1024
=back
=item ML-DSA-87
-=for comment We don't yet have decoders for MLKEM...
+=item ML-KEM-512
+
+=item ML-KEM-768
+
+=item ML-KEM-1024
=back
This functionality was added in OpenSSL 3.0.
+Support for B<ML-DSA> and <ML-KEM> was added in OpenSSL 3.5.
+
=head1 COPYRIGHT
Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved.
=item ML-DSA-87
-=for comment Some day encoders for MLKEM...
+=item ML-KEM-512
+
+=item ML-KEM-768
+
+=item ML-KEM-1024
=back
=item ML-DSA-87
-=item DER
+=item ML-KEM-512
+
+=item ML-KEM-768
-=for comment Some day decoders for MLKEM...
+=item ML-KEM-1024
=back
L<EVP_PKEY-DH(7)/DH parameters>,
L<EVP_PKEY-FFC(7)/FFC parameters>,
L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>,
+L<EVP_PKEY-ML-DSA(7)/Common parameters>,
and
L<EVP_PKEY-ML-KEM(7)/Common parameters>.
Applications may also use L<EVP_PKEY_todata(3)> to return all fields.
/*
- * Copyright 2020 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
+/*
+ * 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
+ * https://www.openssl.org/source/license.html
+ */
+
#ifndef OSSL_MLX_KEM_H
# define OSSL_MLX_KEM_H
# pragma once
/*
* ML-KEM has no support for PEM_write_bio_PrivateKey_traditional(), so no
* legacy tests.
- * TODO(ML-KEM): FIPS
*/
KEYS(ML_KEM_512);
IMPLEMENT_TEST_SUITE(ML_KEM_512, "ML-KEM-512", 1)
#!/usr/bin/env python
+# 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
+# https://www.openssl.org/source/license.html
# A python program written to parse (version 42) of the ACVP test vectors for
# ML_DSA. The 3 files that can be processed by this utility can be downloaded
projects / thirdparty / openssl.git / commitdiff
