GENERATE[html/man7/EVP_PKEY-ML-KEM.html]=man7/EVP_PKEY-ML-KEM.pod
DEPEND[man/man7/EVP_PKEY-ML-KEM.7]=man7/EVP_PKEY-ML-KEM.pod
GENERATE[man/man7/EVP_PKEY-ML-KEM.7]=man7/EVP_PKEY-ML-KEM.pod
+DEPEND[html/man7/EVP_PKEY-MLX-KEM.html]=man7/EVP_PKEY-MLX-KEM.pod
+GENERATE[html/man7/EVP_PKEY-MLX-KEM.html]=man7/EVP_PKEY-MLX-KEM.pod
+DEPEND[man/man7/EVP_PKEY-MLX-KEM.7]=man7/EVP_PKEY-MLX-KEM.pod
+GENERATE[man/man7/EVP_PKEY-MLX-KEM.7]=man7/EVP_PKEY-MLX-KEM.pod
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
html/man7/EVP_PKEY-LMS.html \
html/man7/EVP_PKEY-ML-DSA.html \
html/man7/EVP_PKEY-ML-KEM.html \
+html/man7/EVP_PKEY-MLX-KEM.html \
html/man7/EVP_PKEY-RSA.html \
html/man7/EVP_PKEY-SLH-DSA.html \
html/man7/EVP_PKEY-SM2.html \
man/man7/EVP_PKEY-LMS.7 \
man/man7/EVP_PKEY-ML-DSA.7 \
man/man7/EVP_PKEY-ML-KEM.7 \
+man/man7/EVP_PKEY-MLX-KEM.7 \
man/man7/EVP_PKEY-RSA.7 \
man/man7/EVP_PKEY-SLH-DSA.7 \
man/man7/EVP_PKEY-SM2.7 \
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY-MLX-KEM, EVP_KEYMGMT-MLX-KEM - Hybrid ML-KEM key support for TLS 1.3
+
+=head1 DESCRIPTION
+
+These hybrid ML_KEM algorithms derive the session secret from both a
+ECDH (classical) algorithm (such as X25519, or P-256) and a post-quantum
+algorithm (ML_KEM), ensuring that key agreement remains secure unless both
+schemes are broken.
+
+The algorithms supported here are specifically for use in TLS 1.3 and are not
+suitable for other purposes. There is no encoder/decoder support, and
+EVP_PKEY_CTX_new_id() is also not supported as there are no associated EVP_PKEY
+type identifiers.
+
+The following names can be used by EVP_PKEY_CTX_new_from_name() using OpenSSL's
+default and FIPS providers.
+
+=over 4
+
+=item B<X25519MLKEM768>
+
+The shared secret is the concatenation of a 32 byte L<EVP_PKEY-ML-KEM(7)> shared
+secret followed by a 32 byte L<EVP_PKEY-X25519(7)> shared secret. X25519 is not an
+approved FIPS algorithm, but this combination is still allowed by FIPS 140-3
+since ML-KEM is FIPS approved.
+
+=item B<X448MLKEM1024>
+
+Similar to B<X25519MLKEM768> with a higher security strength, the shared secret
+is the concatenation of a 32 byte L<EVP_PKEY-ML-KEM(7)> shared secret followed
+by a 56 byte L<EVP_PKEY-X448(7)> shared secret.
+
+=item B<SecP256r1MLKEM768>
+
+The shared secret is the concatenation of a 32 byte L<EVP_PKEY-EC(7)> shared
+secret followed by a 32 byte L<EVP_PKEY-ML-KEM(7)> shared secret.
+Both algorithms used are FIPS approved.
+
+=item B<SecP384r1MLKEM1024>
+
+Similar to B<SecP256r1MLKEM768> with a higher security strength, the shared
+secret is the concatenation of a 48 byte L<EVP_PKEY-EC(7)> shared
+secret followed by a 32 byte L<EVP_PKEY-ML-KEM(7)> shared secret.
+
+=back
+
+The following name is supported only in OpenSSL's default provider.
+
+=over 4
+
+=item B<curveSM2MLKEM768>
+
+The shared secret is the concatenation of a 32 byte L<EVP_PKEY-SM2(7)> shared
+secret followed by a 32 byte L<EVP_PKEY-ML-KEM(7)> shared secret.
+
+=back
+
+=head2 Keygen Parameters
+
+No mandatory parameters are required for generating a key pair.
+To set the optional parameter, use L<EVP_PKEY_CTX_set_params(3)> after calling
+L<EVP_PKEY_keygen_init(3)>.
+
+=over 4
+
+=item "properties" (B<OSSL_PKEY_PARAM_PROPERTIES>) <UTF8 string>
+
+Sets properties to be used when fetching algorithm implementations used for
+the B<ML-KEM>, B<ECDH> or B<SM2> algorithms.
+
+=back
+
+=head2 Common parameters
+
+See L<provider-keymgmt(7)/Common Information Parameters>)
+for common information related to parameters.
+
+The following common gettables can be retrieved using
+L<EVP_PKEY_get_int_param(3)>, they retrieve information related to the ML-KEM
+algorithm.
+
+=over 4
+
+=item 'bits' (B<OSSL_PKEY_PARAM_BITS>) <integer>
+
+=item "security-bits" (B<OSSL_PKEY_PARAM_SECURITY_BITS>) <integer>
+
+=item "security-category" (B<OSSL_PKEY_PARAM_SECURITY_CATEGORY>) <integer>
+
+=item "max-size" (B<OSSL_PKEY_PARAM_MAX_SIZE>) <integer>
+
+This value is the combined size of the 2 shared secrets as described above.
+
+=back
+
+The following parameters are also handled.
+
+=over 4
+
+=item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string>
+
+Used for getting and setting the encoding of concatenated public keys.
+The public keys can not be modified once they are set.
+
+The format of the public keys for the different algorithms is:
+
+=over 4
+
+=item B<SecP256r1MLKEM768>
+
+A 65 byte EC public key followed by a 1184 byte ML-KEM-768 public key.
+
+=item B<SecP384r1MLKEM1024>
+
+A 97 byte EC public key followed by a 1568 byte ML-KEM-1024 public key.
+
+=item B<X25519MLKEM768>
+
+A 1184 byte ML-KEM-768 public key followed by a 32 byte X25519 public key.
+
+=item B<X448MLKEM1024>
+
+A 1568 byte ML-KEM-1024 public key followed by a 56 byte X448 public key.
+
+=item B<curveSM2MLKEM768>
+
+A 65 byte SM2 public key followed by a 1184 byte ML-KEM-768 public key.
+
+=back
+
+=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
+
+The public key value.
+
+This parameter is only used when importing or exporting the public key value with
+the EVP_PKEY_fromdata() and EVP_PKEY_todata() functions.
+The public key format format is the same as "encoded-pub-key".
+
+=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string>
+
+The private key value which is the concatenation of 2 internal private keys.
+
+This parameter can be used when importing or exporting the private key value
+using the EVP_PKEY_fromdata() and EVP_PKEY_todata() functions.
+Initial import aside, this parameter is otherwise only gettable.
+
+The format of the private keys for the different algorithms is:
+
+=over 4
+
+=item B<SecP256r1MLKEM768>
+
+32 byte EC private key followed by a 2400 byte ML-KEM-768 private key.
+
+=item B<SecP384r1MLKEM1024>
+
+48 byte EC private key followed by a 3168 byte ML-KEM-1024 private key.
+
+=item B<X25519MLKEM768>
+
+2400 byte ML-KEM-768 private key followed by a 32 byte X25519 private key.
+
+=item B<X448MLKEM1024>
+
+3168 byte ML-KEM-1024 private key followed by a 56 byte X448 private key.
+
+=item B<curveSM2MLKEM768>
+
+32 byte SM2 private key followed by a 2400 byte ML-KEM-768 private key.
+
+=back
+
+=back
+
+=head1 CONFORMING TO
+
+=over 4
+
+=item https://datatracker.ietf.org/doc/draft-ietf-tls-ecdhe-mlkem/
+
+Note that B<X448MLKEM1024> is not defined by this document.
+
+=item SP800-227
+
+The general notation used in this document says that outputs are
+combined/processed in order of the names.
+B<X25519MLKEM768> and B<X448MLKEM768> however use the reverse order since
+X25519 and X448 are not FIPS approved algorithms.
+Even though they are not FIPS approved the hybrid combination is still allowed
+since MLKEM is FIPS approved.
+
+=back
+
+=head1 SEE ALSO
+
+L<EVP_KEM-ML-KEM(7)>,
+L<EVP_PKEY-X25519(7)>,
+L<EVP_PKEY-EC(7)>,
+L<EVP_PKEY-SM2(7)>,
+L<provider-keymgmt(7)>
+
+=head1 HISTORY
+
+This functionality was added in OpenSSL 3.5.
+
+Support for B<curveSM2MLKEM768> was added in OpenSSL 4.0.
+
+=head1 COPYRIGHT
+
+Copyright 2026 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 X448, see L<EVP_KEYEXCH-X448(7)>
-=item ML-KEM, see L<EVP_KEM-ML-KEM(7)>
+=item ML-KEM-512, see L<EVP_KEM-ML-KEM-512(7)>
+
+=item ML-KEM-768, see L<EVP_KEM-ML-KEM-768(7)>
+
+=item ML-KEM-1024, see L<EVP_KEM-ML-KEM-1024(7)>
+
+=item X25519MLKEM768, see L<EVP_PKEY-MLX-KEM(7)>
+
+=item X448MLKEM1024, see L<EVP_PKEY-MLX-KEM(7)>
+
+=item SecP256r1MLKEM768, see L<EVP_PKEY-MLX-KEM(7)>
+
+=item SecP384r1MLKEM1024, see L<EVP_PKEY-MLX-KEM(7)>
=item TLS1-PRF
=item ML-DSA-87, see L<EVP_KEYMGMT-ML-DSA(7)>
+=item MK-KEM-512, see L<EVP_KEYMGMT-ML-KEM-512(7)>
+
+=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 X25519MLKEM768, see L<EVP_KEYMGMT-MLX-KEM(7)>
+
+=item X448MLKEM1024, see L<EVP_KEYMGMT-MLX-KEM(7)>
+
+=item SecP256r1MLKEM768, see L<EVP_KEYMGMT-MLX-KEM(7)>
+
+=item SecP384r1MLKEM1024, see L<EVP_KEYMGMT-MLX-KEM(7)>
+
=item SLH-DSA-SHA2-128s, see L<EVP_KEYMGMT-SLH-DSA(7)>
=item SLH-DSA-SHA2-128f, see L<EVP_KEYMGMT-SLH-DSA(7)>
=item ML-KEM-1024, see L<EVP_KEM-ML-KEM-1024(7)>
+=item X25519MLKEM768, see L<EVP_PKEY-MLX-KEM(7)>
+
+=item X448MLKEM1024, see L<EVP_PKEY-MLX-KEM(7)>
+
+=item SecP256r1MLKEM768, see L<EVP_PKEY-MLX-KEM(7)>
+
+=item SecP384r1MLKEM1024, see L<EVP_PKEY-MLX-KEM(7)>
+
+=item curveSM2MLKEM768, see L<EVP_PKEY-MLX-KEM(7)>
+
=item TLS1-PRF
=item HKDF
=item MK-KEM-1024, see L<EVP_KEYMGMT-ML-KEM-1024(7)>
+=item X25519MLKEM768, see L<EVP_KEYMGMT-MLX-KEM(7)>
+
+=item X448MLKEM1024, see L<EVP_KEYMGMT-MLX-KEM(7)>
+
+=item SecP256r1MLKEM768, see L<EVP_KEYMGMT-MLX-KEM(7)>
+
+=item SecP384r1MLKEM1024, see L<EVP_KEYMGMT-MLX-KEM(7)>
+
+=item curveSM2MLKEM768, see L<EVP_PKEY-MLX-KEM(7)>
+
=item SLH-DSA-SHA2-128s, see L<EVP_KEYMGMT-SLH-DSA(7)>
=item SLH-DSA-SHA2-128f, see L<EVP_KEYMGMT-SLH-DSA(7)>
=head1 HISTORY
-Support for B<LMS> Public Key (SubjectPublicKeyInfo) encoders and decoders
-was added in OpenSSL 4.0.
+Base functionality was added in OpenSSL 3.0.
The RIPEMD160 digest was added to the default provider in OpenSSL 3.0.7.
+Support for B<X25519MLKEM768>, B<X448MLKEM1024>, B<SecP256r1MLKEM768> and
+B<SecP384r1MLKEM1024> was added in OpenSSL 3.5.
+
The HKDF-SHA256, HKDF-SHA384 and HKDF-SHA512 algorithms were added in OpenSSL 3.6.
-The CSHAKE-128 and CSHAKE-256 algorithms were added in OpenSSL 4.0.
+Support for B<LMS> Public Key (SubjectPublicKeyInfo) encoders and decoders
+was added in OpenSSL 4.0.
+
+Support for B<curveSM2MLKEM768> was added in OpenSSL 4.0.
-All other functionality was added in OpenSSL 3.0.
+Support for CSHAKE-128 and CSHAKE-256 was added in OpenSSL 4.0.
=head1 COPYRIGHT
projects / thirdparty / openssl.git / commitdiff
