otherwise someone would have to type in the password every time the
server needs to access the key.
-For X25519 and X448, it's treated as a distinct algorithm but not as one of
-the curves listed with 'ecparam -list_curves' option. You can use
-the following command to generate an X25519 key:
+X25519, X448, Ed25519 and Ed448 are treated as distinct algorithms and not as
+one of the EC curves listed with 'ecparam -list_curves' option. You can use the
+following command to generate an X25519 key:
openssl genpkey -algorithm X25519 -out xkey.pem
+
+# TODO(ML-KEM) Likewise ML-KEM once we have codecs.
- DSA. Keygen and Signing are no longer approved, verify is still allowed.
- ECDSA B & K curves are deprecated, but still approved according to (IG C.K Resolution 4).\
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/ED448 is now approved.
-- X25519/X448 is not approved currently. keygen and keyexchange would also need an indicator if we allow it?
+- 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)
=over 4
-=item DH, EC, X25519, X448:
+=item DH, EC, X25519, X448, ML-KEM (512, 768 and 1024):
-It's possible to set the encoded public key. This is supported in
+It is possible to set the encoded public key. This is supported in
particular through L<EVP_PKEY_set1_encoded_public_key(3)>.
=item EC:
=head1 SEE ALSO
-L<provider-keymgmt(7)>
+L<provider-keymgmt(7)>,
+L<EVP_PKEY-DH(7)>,
+L<EVP_PKEY-EC(7)>,
+L<EVP_PKEY-X25519(7)>,
+L<EVP_PKEY-ML-KEM(7)>.
=head1 COPYRIGHT
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.
+
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
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.
+
=head1 HISTORY
The ability to use NIST curve names, and to generate an EC key directly,
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.
=head1 COPYRIGHT
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).
+
=item B<-kdf> I<algorithm>
Use key derivation function I<algorithm>. The supported algorithms are
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 ED25519 AND ED448 ALGORITHMS
These algorithms only support signing and verifying. OpenSSL only implements the
EVP_PKEY_encapsulate_init() or EVP_PKEY_decapsulate_init() to select the kem
operation. For the key types that support encapsulation and don't have the
default operation, e.g. RSA, this function must be called before
-EVP_PKEY_encapsulate() or EVP_PKEY_decapsulate(). The supported values for the
-built-in algorithms are enumerated in L<EVP_KEM-RSA(7)>, L<EVP_KEM-EC(7)>,
-L<EVP_KEM-X25519(7)>, and L<EVP_KEM-X448(7)>.
+EVP_PKEY_encapsulate() or EVP_PKEY_decapsulate().
+
+The supported parameters for the built-in algorithms are documented in
+L<EVP_KEM-RSA(7)>, L<EVP_KEM-EC(7)>, L<EVP_KEM-X25519(7)>,
+L<EVP_KEM-X448(7)>, and L<EVP_KEM-ML-KEM(7)>.
=head1 RETURN VALUES
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-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.
+
=head1 COPYRIGHT
Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved.
authenticate data subsequently received from the peer.
If I<unwrapped> is NULL then the size of the output shared secret buffer is
written to I<*unwrappedlen> and no decapsulation is performed, this makes it
-possible to determine the required buffer size at runtime. Otherwise, the
+possible to determine the required buffer size at run time. Otherwise, the
decapsulated secret data is written to I<unwrapped> and the length of shared
secret is written to I<*unwrappedlen>.
Absent detailed prior knowledge of the internals of the specific KEM
algorithm, callers SHOULD NOT assume that the returned shared secret
is necessarily of the maximum possible length.
-The actual length returned via I<*unwrappedlen> SHOULD be used to determine the
-actual length of the output.
+The length returned via I<*unwrappedlen> SHOULD be used to determine the actual
+length of the output.
=head1 NOTES
Absent detailed prior knowledge of the internals of the specific KEM
algorithm, callers SHOULD NOT assume that the returned shared secret and
ciphertext are necessarily of the maximum possible length.
-The actual lengths returned via I<*wrappedkeylen> and I<*genkeylen> SHOULD
+The lengths returned via I<*wrappedkeylen> and I<*genkeylen> SHOULD
be used to determine the actual lengths of the outputs.
=head1 NOTES
given data from I<params>, I<selection> and a context that's been initialized
with EVP_PKEY_fromdata_init(). The result is written to I<*ppkey>.
I<selection> is described in L</Selections>.
-The parameters that can be used for various types of key are as described by the
-diverse "Common parameters" sections of the
+The parameters that can be used for various types of key are as described by
+the various "Common parameters" sections of the
L<B<EVP_PKEY-RSA>(7)|EVP_PKEY-RSA(7)/Common RSA parameters>,
L<B<EVP_PKEY-DSA>(7)|EVP_PKEY-DSA(7)/Common DSA & DH parameters>,
L<B<EVP_PKEY-DH>(7)|EVP_PKEY-DH(7)/Common DH parameters>,
L<B<EVP_PKEY-ED448>(7)|EVP_PKEY-ED448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
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>,
-and L<B<EVP_PKEY-ED25519>(7)|EVP_PKEY-ED25519(7)/Common X25519, X448, ED25519 and ED448 parameters> pages.
+L<B<EVP_PKEY-ED25519>(7)|EVP_PKEY-ED25519(7)/Common X25519, X448, ED25519 and ED448 parameters>,
+and
+L<EVP_PKEY-ML-KEM-512(7)|EVP_PKEY-ML-KEM-768(7)|EVP_PKEY-ML-KEM-1024(7)/Common parameters>
+pages.
=for comment the awful list of links above is made this way so we get nice
rendering as a man-page while still getting proper links in HTML
=head1 SEE ALSO
-L<EVP_PKEY_CTX_new(3)>, L<provider(7)>, L<EVP_PKEY_gettable_params(3)>,
-L<OSSL_PARAM(3)>, L<EVP_PKEY_todata(3)>,
-L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>,
-L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>,
-L<EVP_PKEY-ED25519(7)>, L<EVP_PKEY-ML-DSA(7)>
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_todata(3)>,
+L<EVP_PKEY_gettable_params(3)>,
+L<OSSL_PARAM(3)>,
+L<provider(7)>,
+L<EVP_PKEY-RSA(7)>,
+L<EVP_PKEY-EC(7)>,
+L<EVP_PKEY-ED25519(7)>,
+L<EVP_PKEY-ED448(7)>,
+L<EVP_PKEY-DSA(7)>,
+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)>.
=head1 HISTORY
These functions were added in OpenSSL 3.0.
+Support for B<ML-KEM> was added in OpenSSL 3.5.
+
=head1 COPYRIGHT
Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
a B<size_t> parameter must be given to specify the size of the RSA key.
If I<type> is C<EC>,
a string parameter must be given to specify the name of the EC curve.
-If I<type> is C<X25519>, C<X448>, C<ED25519>, C<ED448>, or C<SM2>
-no further parameter is needed. Starting from OpenSSL version 3.5, other
-key types may be possible if they are supplied by the loaded providers.
-EVP_PKEY_Q_keygen() may be usable with such key types as long as
-they do not require further parameters.
+If I<type> is:
+C<ED25519>,
+C<ED448>,
+C<SM2>,
+C<X25519>,
+C<X448>,
+C<ML-KEM-512>,
+C<ML-KEM-768>, or
+C<ML-KEM-1024>
+no further parameters are needed. Other key types may be possible if they are
+supplied by the loaded providers. EVP_PKEY_Q_keygen() may be usable with such
+key types as long as they do not require further parameters.
=head1 RETURN VALUES
engine should be used for the key type, a provider for the key is found using
the library context I<libctx> and the property query string I<propq>. The
I<keytype> argument indicates what kind of key this is. The value should be a
-string for a public key algorithm that supports raw private keys, i.e one of
-"X25519", "ED25519", "X448" or "ED448". I<key> points to the raw private key
+string for a public key algorithm that supports raw private keys, e.g., one of:
+C<ED25519>,
+C<ED448>,
+C<X25519>,
+C<X448>,
+C<ML-KEM-512>,
+C<ML-KEM-768>,
+or
+C<ML-KEM-1024>.
+I<key> points to the raw private key
data for this B<EVP_PKEY> which should be of length I<keylen>. The length
should be appropriate for the type of the key. The public key data will be
automatically derived from the given private key data (if appropriate for the
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. Algorithm types that support raw public keys are
-"X25519", "ED25519", "X448" or "ED448".
+B<ED25519>,
+B<ED448>,
+B<X25519>,
+B<X448>,
+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<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>.
+B<ED448>.
+B<ED25519>,
+B<X25519>,
+B<X448>
+B<ML-KEM-512>,
+B<ML-KEM-768>,
+and
+B<ML-KEM-1024>.
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.
the number of bytes required to hold the key. The calling application is
responsible for ensuring that the buffer is large enough to receive the private
key data. This function only works for algorithms that support raw private keys.
-Currently this is: B<EVP_PKEY_HMAC>, B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>,
-B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>.
+These include:
+B<ED25519>,
+B<ED448>,
+B<X25519>,
+B<X448>,
+B<HMAC>,
+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_public_key() fills the buffer provided by I<pub> with raw
public key data. The size of the I<pub> buffer should be in I<*len> on entry
the number of bytes required to hold the key. The calling application is
responsible for ensuring that the buffer is large enough to receive the public
key data. This function only works for algorithms that support raw public keys.
-Currently this is: B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or
-B<EVP_PKEY_ED448>.
+These include:
+B<ED25519>,
+B<ED448>,
+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_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
=head1 SEE ALSO
-L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA(3)>, L<EVP_PKEY_set1_DH(3)> or
-L<EVP_PKEY_set1_EC_KEY(3)>
+L<EVP_PKEY_set1_RSA(3)>,
+L<EVP_PKEY_set1_DSA(3)>,
+L<EVP_PKEY_set1_DH(3)>,
+L<EVP_PKEY_set1_EC_KEY(3)>,
+L<EVP_PKEY-ED25519(7)>,
+L<EVP_PKEY-ED448(7)>.
+L<EVP_PKEY-HMAC(7)>,
+L<EVP_PKEY-Poly1305(7)>,
+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)>.
=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.
+
=head1 COPYRIGHT
Copyright 2002-2022 The OpenSSL Project Authors. All Rights Reserved.
=head1 DESCRIPTION
EVP_PKEY_set1_encoded_public_key() can be used to set the public key value
-within an existing EVP_PKEY object. For the built-in OpenSSL algorithms this
-currently only works for those that support key exchange. Parameters are not
-set as part of this operation, so typically an application will create an
-EVP_PKEY first, set the parameters on it, and then call this function.
+within an existing EVP_PKEY object, which does not yet have either a public or
+private key assigned.
+For the built-in OpenSSL algorithms this currently only works for those that
+support key exchange or key encapsulation.
+Parameters are not set as part of this operation, so typically an application
+will create an EVP_PKEY first, set the parameters on it, and then call this
+function.
For example setting the parameters might be done using
L<EVP_PKEY_copy_parameters(3)>.
The format for the encoded public key will depend on the algorithm in use. For
DH it should be encoded as a positive integer in big-endian form. For EC is
should be a point conforming to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic
-Curve Cryptography") standard. For X25519 and X448 it should be encoded in a
-format as defined by RFC7748.
+Curve Cryptography") standard. For B<X25519> and B<X448> it should be encoded
+in the format defined by RFC7748.
+For B<ML-KEM-512>, B<ML-KEM-768> and B<ML-KEM-1024>, this is the public key
+format defined in B<FIPS 203> (the 12-bit per-coefficient encoded public I<t>
+vector and 32-byte matrix seed I<rho>).
The key to be updated is supplied in B<pkey>. The buffer containing the encoded
key is pointed to be B<pub>. The length of the buffer is supplied in B<publen>.
=head1 SEE ALSO
-L<EVP_PKEY_new(3)>, L<EVP_PKEY_copy_parameters(3)>,
-L<EVP_PKEY_derive_init(3)>, L<EVP_PKEY_derive(3)>,
-L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>
+L<EVP_PKEY_new(3)>,
+L<EVP_PKEY_copy_parameters(3)>,
+L<EVP_PKEY_derive_init(3)>,
+L<EVP_PKEY_derive(3)>,
+L<EVP_PKEY-DH(7)>,
+L<EVP_PKEY-EC(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)>.
=head1 HISTORY
EVP_PKEY_set1_tls_encodedpoint() and EVP_PKEY_get1_tls_encodedpoint() were
deprecated in OpenSSL 3.0.
+Support for B<ML-KEM> was added in OpenSSL 3.5.
+
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
=head1 SEE ALSO
-L<OSSL_PARAM(3)>, L<openssl-core.h(7)>,
+L<OSSL_PARAM(3)>,
+L<openssl-core.h(7)>,
L<EVP_PKEY_fromdata(3)>,
-L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>,
-L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>,
-L<EVP_PKEY-ED25519(7)>, L<EVP_PKEY-ML-DSA(7)>
+L<EVP_PKEY-RSA(7)>,
+L<EVP_PKEY-EC(7)>,
+L<EVP_PKEY-DSA(7)>,
+L<EVP_PKEY-ED25519(7)>
+L<EVP_PKEY-ED448(7)>,
+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)>.
=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.
+
=head1 COPYRIGHT
Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved.
the enriched syntax is ultimately equivalent to just a simple ordered list of
groups, as with the simple form above.
-Groups for B<TLSv1.3> in the default provider are B<P-256>, B<P-384>,
-B<P-521>, B<X25519>, B<X448>, B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>,
-B<ffdhe6144>, B<ffdhe8192>, B<brainpoolP256r1tls13>,
-B<brainpoolP384r1tls13> and B<brainpoolP512r1tls13>.
+The supported groups for B<TLSv1.3> include:
+B<secp256r1>,
+B<secp384r1>,
+B<secp521r1>,
+B<x25519>,
+B<x448>,
+B<brainpoolP256r1tls13>,
+B<brainpoolP384r1tls13>,
+B<brainpoolP512r1tls13>,
+B<ffdhe2048>,
+B<ffdhe3072>,
+B<ffdhe4096>,
+B<ffdhe6144>,
+B<ffdhe8192>
+B<MLKEM512>,
+B<MLKEM768>,
+and
+B<MLKEM1024>.
+
Additional providers may make available further algorithms via the
TLS-GROUP capability. See L<provider-base(7)>.
(e.g. B<prime256v1>). Group names are case sensitive. The list should be in
order of preference with the most preferred group first.
-Currently supported groups for B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>,
-B<X25519>, B<X448>, B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>, B<ffdhe6144>,
-B<ffdhe8192>.
+The supported groups for B<TLSv1.3> include:
+B<secp256r1>,
+B<secp384r1>,
+B<secp521r1>,
+B<x25519>,
+B<x448>,
+B<brainpoolP256r1tls13>,
+B<brainpoolP384r1tls13>,
+B<brainpoolP512r1tls13>,
+B<ffdhe2048>,
+B<ffdhe3072>,
+B<ffdhe4096>,
+B<ffdhe6144>,
+B<ffdhe8192>
+B<MLKEM512>,
+B<MLKEM768>,
+and
+B<MLKEM1024>.
=item B<Curves>
B<PreferNoDHEKEX> was added in OpenSSL 3.3.
+Support for B<ML-KEM> was added in OpenSSL 3.5.
+
=head1 COPYRIGHT
Copyright 2012-2024 The OpenSSL Project Authors. All Rights Reserved.
SSL_CTX_set1_groups() sets the supported groups for B<ctx> to B<glistlen>
groups in the array B<glist>. The array consist of all NIDs of supported groups.
-Currently supported groups for B<TLSv1.3> are B<NID_X9_62_prime256v1>,
-B<NID_secp384r1>, B<NID_secp521r1>, B<NID_X25519>, B<NID_X448>,
-B<NID_brainpoolP256r1tls13>, B<NID_brainpoolP384r1tls13>,
-B<NID_brainpoolP512r1tls13>, B<NID_ffdhe2048>, B<NID_ffdhe3072>,
-B<NID_ffdhe4096>, B<NID_ffdhe6144> and B<NID_ffdhe8192>.
-OpenSSL will use this array in different ways depending on TLS role and version:
+The supported groups for B<TLSv1.3> include:
+B<NID_X9_62_prime256v1>,
+B<NID_secp384r1>,
+B<NID_secp521r1>,
+B<NID_X25519>,
+B<NID_X448>,
+B<NID_brainpoolP256r1tls13>,
+B<NID_brainpoolP384r1tls13>,
+B<NID_brainpoolP512r1tls13>,
+B<NID_ffdhe2048>,
+B<NID_ffdhe3072>,
+B<NID_ffdhe4096>,
+B<NID_ffdhe6144>, and
+B<NID_ffdhe8192>.
+OpenSSL will use this array in different ways based on the TLS version, and
+whether the groups are used in a client or server.
For a TLS client, the groups are used directly in the supported groups
extension. The extension's preference order, to be evaluated by the server, is
SSL_CTX_set1_groups_list() sets the supported groups for B<ctx> to
string I<list>. In contrast to SSL_CTX_set1_groups(), the names of the
-groups, rather than their NIDs, are used. Currently supported groups for
-B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>, B<X25519>, B<X448>,
-B<brainpoolP256r1tls13>, B<brainpoolP384r1tls13>, B<brainpoolP512r1tls13>,
-B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>, B<ffdhe6144> and B<ffdhe8192>. Support
-for other groups may be added by external providers.
+groups, rather than their NIDs, are used.
+
+The supported groups for B<TLSv1.3> include:
+B<P-256>,
+B<P-384>,
+B<P-521>,
+B<X25519>,
+B<X448>,
+B<ffdhe2048>,
+B<ffdhe3072>,
+B<ffdhe4096>,
+B<ffdhe6144>
+B<ffdhe8192>,
+B<MLKEM512>,
+B<MLKEM768>,
+B<MLKEM1024>,
+B<brainpoolP256r1tls13>,
+B<brainpoolP384r1tls13>, and
+B<brainpoolP512r1tls13>.
+Support for other groups may be added by external providers.
+
Each group can be either the B<NIST> name (e.g. B<P-256>), some other commonly
used name where applicable (e.g. B<X25519>, B<ffdhe2048>) or an OpenSSL OID name
(e.g. B<prime256v1>). Group names are case sensitive. The preferred group names
Support for ignoring unknown groups in SSL_CTX_set1_groups_list() and
SSL_set1_groups_list() was added in OpenSSL 3.3.
+Support for B<ML-KEM> was added in OpenSSL 3.5.
+
Earlier versions of this document described the list as a preference order.
However, OpenSSL's behavior as a TLS 1.3 server is to consider I<all>
supported groups as comparable in security.
=item X448, see L<EVP_KEYEXCH-X448(7)>
+=for comment TODO(ML-KEM) L<EVP_KEM-ML-KEM(7)> once ML-KEM is supported in the
+ FIPS module.
+
=item TLS1-PRF
=item HKDF
=item ML-DSA-87
+=for comment TODO(ML-KEM): We don't yet have encoders for ML-KEM.
+
=back
In addition to this provider, all of these encoding algorithms are also
=item ML-DSA-87
+=for comment We don't yet have decoders for MLKEM...
+
=back
In addition to this provider, all of these decoding algorithms are also
=over 4
-=item DH, see L<EVP_KEYMGMT-DH(7)>
-
-=item DHX, see L<EVP_KEYMGMT-DHX(7)>
-
=item DSA, see L<EVP_KEYMGMT-DSA(7)>
=item RSA, see L<EVP_KEYMGMT-RSA(7)>
=item EC, see L<EVP_KEYMGMT-EC(7)>
+=item ED25519, see L<EVP_KEYMGMT-ED25519(7)>
+
+=item ED448, see L<EVP_KEYMGMT-ED448(7)>
+
+=item SM2, see L<EVP_KEYMGMT-SM2(7)>
+
+=item DH, see L<EVP_KEYMGMT-DH(7)>
+
+=item DHX, see L<EVP_KEYMGMT-DHX(7)>
+
=item X25519, see L<EVP_KEYMGMT-X25519(7)>
=item X448, see L<EVP_KEYMGMT-X448(7)>
-=item ED25519, see L<EVP_KEYMGMT-ED25519(7)>
+=item ML-DSA-44, see L<EVP_KEYMGMT-ML-DSA(7)>
-=item ED448, see L<EVP_KEYMGMT-ED448(7)>
+=item ML-DSA-65, see L<EVP_KEYMGMT-ML-DSA(7)>
+
+=item ML-DSA-87, see L<EVP_KEYMGMT-ML-DSA(7)>
+
+=item MK-KEM-512, see L<EVP_KEYMGMT-ML-KEM-512(7)>
-=for comment We don't yet have the corresponding MLKEM doc in the works.
+=item MK-KEM-768, see L<EVP_KEYMGMT-ML-KEM-768(7)>
+
+=item MK-KEM-1024, see L<EVP_KEYMGMT-ML-KEM-1024(7)>
=item TLS1-PRF
=item CMAC, see L<EVP_KEYMGMT-CMAC(7)>
-=item SM2, see L<EVP_KEYMGMT-SM2(7)>
-
-=item ML-DSA-44, see L<EVP_KEYMGMT-ML-DSA(7)>
-
-=item ML-DSA-65, see L<EVP_KEYMGMT-ML-DSA(7)>
-
-=item ML-DSA-87, see L<EVP_KEYMGMT-ML-DSA(7)>
-
-=item ML-KEM-512, see L<EVP_KEYMGMT-ML-KEM-512(7)>
-
-=item ML-KEM-768, see L<EVP_KEYMGMT-ML-KEM-768(7)>
-
-=item ML-KEM-1024, see L<EVP_KEYMGMT-ML-KEM-1024(7)>
-
=back
=head2 Random Number Generation
"pkcs1" padding is no longer approved.
-See L<EVP_ASYM_CIPHER-RSA(7)/RSA Asymmetric Cipher parameters> and
+See L<EVP_ASYM_CIPHER-RSA(7)/RSA Asymmetric Cipher parameters> and
L<EVP_KEM-RSA(7)/RSA KEM parameters>
=item RSA Signatures
The unapproved (non FIPS validated) algorithms have a property query value of
"fips=no".
+=for comment TODO(ML-KEM) Once in the FIPS module.
+
The following algorithms use a unique indicator and do not trigger the
indicator callback.
EVP_PKEY_SM2 rather than EVP_PKEY_EC.
Unlike in previous OpenSSL versions, this means that applications cannot
-call C<EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)> to get SM2 computations.
+call B<EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)> to get SM2 computations.
Parameter and key generation is also reworked to make it possible
to generate EVP_PKEY_SM2 parameters and keys. Applications must now generate
=head4 Deprecated low-level key parameter getters
Functions that access low-level objects directly such as L<RSA_get0_n(3)> are now
-deprecated. Applications should use one of L<EVP_PKEY_get_bn_param(3)>,
-L<EVP_PKEY_get_int_param(3)>, l<EVP_PKEY_get_size_t_param(3)>,
-L<EVP_PKEY_get_utf8_string_param(3)>, L<EVP_PKEY_get_octet_string_param(3)> or
-L<EVP_PKEY_get_params(3)> to access fields from an EVP_PKEY.
-Gettable parameters are listed in L<EVP_PKEY-RSA(7)/Common RSA parameters>,
-L<EVP_PKEY-DH(7)/DH parameters>, L<EVP_PKEY-DSA(7)/DSA parameters>,
-L<EVP_PKEY-FFC(7)/FFC parameters>, L<EVP_PKEY-EC(7)/Common EC parameters> and
-L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>.
+deprecated. Applications should use one of:
+L<EVP_PKEY_get_bn_param(3)>,
+L<EVP_PKEY_get_int_param(3)>,
+L<EVP_PKEY_get_size_t_param(3)>,
+L<EVP_PKEY_get_utf8_string_param(3)>,
+L<EVP_PKEY_get_octet_string_param(3)>, or
+L<EVP_PKEY_get_params(3)>,
+to access fields from an EVP_PKEY.
+Gettable parameters are listed in:
+L<EVP_PKEY-RSA(7)/Common RSA parameters>,
+L<EVP_PKEY-EC(7)/Common EC parameters>,
+L<EVP_PKEY-DSA(7)/DSA parameters>,
+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>,
+and
+L<EVP_PKEY-ML-KEM(7)/Common parameters>.
Applications may also use L<EVP_PKEY_todata(3)> to return all fields.
=head4 Deprecated low-level key parameter setters
projects / thirdparty / openssl.git / commitdiff
