.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.48) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "EVP_PKEY-MLX-KEM 7ssl" .TH EVP_PKEY-MLX-KEM 7ssl 2026-10-23 4.1.0 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME EVP_PKEY\-MLX\-KEM, EVP_KEYMGMT\-MLX\-KEM \- Hybrid ML\-KEM key support for TLS 1.3 .SH DESCRIPTION .IX Header "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. .PP 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 \&\fBEVP_PKEY_CTX_new_id()\fR is also not supported as there are no associated EVP_PKEY type identifiers. .PP The following names can be used by \fBEVP_PKEY_CTX_new_from_name()\fR using OpenSSL\*(Aqs default and FIPS providers. .IP \fBX25519MLKEM768\fR 4 .IX Item "X25519MLKEM768" The shared secret is the concatenation of a 32 byte \fBEVP_PKEY\-ML\-KEM\fR\|(7) shared secret followed by a 32 byte \fBEVP_PKEY\-X25519\fR\|(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. .IP \fBX448MLKEM1024\fR 4 .IX Item "X448MLKEM1024" Similar to \fBX25519MLKEM768\fR with a higher security strength, the shared secret is the concatenation of a 32 byte \fBEVP_PKEY\-ML\-KEM\fR\|(7) shared secret followed by a 56 byte \fBEVP_PKEY\-X448\fR\|(7) shared secret. .IP \fBSecP256r1MLKEM768\fR 4 .IX Item "SecP256r1MLKEM768" The shared secret is the concatenation of a 32 byte \fBEVP_PKEY\-EC\fR\|(7) shared secret followed by a 32 byte \fBEVP_PKEY\-ML\-KEM\fR\|(7) shared secret. Both algorithms used are FIPS approved. .IP \fBSecP384r1MLKEM1024\fR 4 .IX Item "SecP384r1MLKEM1024" Similar to \fBSecP256r1MLKEM768\fR with a higher security strength, the shared secret is the concatenation of a 48 byte \fBEVP_PKEY\-EC\fR\|(7) shared secret followed by a 32 byte \fBEVP_PKEY\-ML\-KEM\fR\|(7) shared secret. .PP The following name is supported only in OpenSSL\*(Aqs default provider. .IP \fBcurveSM2MLKEM768\fR 4 .IX Item "curveSM2MLKEM768" The shared secret is the concatenation of a 32 byte \fBEVP_PKEY\-SM2\fR\|(7) shared secret followed by a 32 byte \fBEVP_PKEY\-ML\-KEM\fR\|(7) shared secret. .SS "Keygen Parameters" .IX Subsection "Keygen Parameters" No mandatory parameters are required for generating a key pair. To set the optional parameter, use \fBEVP_PKEY_CTX_set_params\fR\|(3) after calling \&\fBEVP_PKEY_keygen_init\fR\|(3). .IP """properties"" (\fBOSSL_PKEY_PARAM_PROPERTIES\fR) " 4 .IX Item """properties"" (OSSL_PKEY_PARAM_PROPERTIES) " Sets properties to be used when fetching algorithm implementations used for the \fBML\-KEM\fR, \fBECDH\fR or \fBSM2\fR algorithms. .PP The OpenSSL FIPS provider makes the following parameter available from both key generation and KEM operation contexts: .IP """fips\-indicator"" (\fBOSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR\fR or \fBOSSL_KEM_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 .IX Item """fips-indicator"" (OSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR or OSSL_KEM_PARAM_FIPS_APPROVED_INDICATOR) " Returns 0 for X448MLKEM1024, which is advertised with \f(CW\*(C`fips=no\*(C'\fR, and 1 for X25519MLKEM768, SecP256r1MLKEM768 and SecP384r1MLKEM1024. See "FIPS indicators" in \fBfips_module\fR\|(7) for more information. .SS "Common parameters" .IX Subsection "Common parameters" See "Common Information Parameters" in \fBprovider\-keymgmt\fR\|(7)) for common information related to parameters. .PP The following common gettables can be retrieved using \&\fBEVP_PKEY_get_int_param\fR\|(3), they retrieve information related to the ML\-KEM algorithm. .IP "\*(Aqbits\*(Aq (\fBOSSL_PKEY_PARAM_BITS\fR) " 4 .IX Item "'bits' (OSSL_PKEY_PARAM_BITS) " .PD 0 .IP """security\-bits"" (\fBOSSL_PKEY_PARAM_SECURITY_BITS\fR) " 4 .IX Item """security-bits"" (OSSL_PKEY_PARAM_SECURITY_BITS) " .IP """security\-category"" (\fBOSSL_PKEY_PARAM_SECURITY_CATEGORY\fR) " 4 .IX Item """security-category"" (OSSL_PKEY_PARAM_SECURITY_CATEGORY) " .IP """max\-size"" (\fBOSSL_PKEY_PARAM_MAX_SIZE\fR) " 4 .IX Item """max-size"" (OSSL_PKEY_PARAM_MAX_SIZE) " .PD This value is the combined size of the 2 shared secrets as described above. .PP The following parameters are also handled. .IP """encoded\-pub\-key"" (\fBOSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\fR) " 4 .IX Item """encoded-pub-key"" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) " Used for getting and setting the encoding of concatenated public keys. The public keys can not be modified once they are set. .Sp The format of the public keys for the different algorithms is: .RS 4 .IP \fBSecP256r1MLKEM768\fR 4 .IX Item "SecP256r1MLKEM768" A 65 byte EC public key followed by a 1184 byte ML\-KEM\-768 public key. .IP \fBSecP384r1MLKEM1024\fR 4 .IX Item "SecP384r1MLKEM1024" A 97 byte EC public key followed by a 1568 byte ML\-KEM\-1024 public key. .IP \fBX25519MLKEM768\fR 4 .IX Item "X25519MLKEM768" A 1184 byte ML\-KEM\-768 public key followed by a 32 byte X25519 public key. .IP \fBX448MLKEM1024\fR 4 .IX Item "X448MLKEM1024" A 1568 byte ML\-KEM\-1024 public key followed by a 56 byte X448 public key. .IP \fBcurveSM2MLKEM768\fR 4 .IX Item "curveSM2MLKEM768" A 65 byte SM2 public key followed by a 1184 byte ML\-KEM\-768 public key. .RE .RS 4 .RE .IP """pub"" (\fBOSSL_PKEY_PARAM_PUB_KEY\fR) " 4 .IX Item """pub"" (OSSL_PKEY_PARAM_PUB_KEY) " The public key value. .Sp This parameter is only used when importing or exporting the public key value with the \fBEVP_PKEY_fromdata()\fR and \fBEVP_PKEY_todata()\fR functions. The public key format is the same as "encoded\-pub\-key". .IP """priv"" (\fBOSSL_PKEY_PARAM_PRIV_KEY\fR) " 4 .IX Item """priv"" (OSSL_PKEY_PARAM_PRIV_KEY) " The private key value which is the concatenation of 2 internal private keys. .Sp This parameter can be used when importing or exporting the private key value using the \fBEVP_PKEY_fromdata()\fR and \fBEVP_PKEY_todata()\fR functions. Initial import aside, this parameter is otherwise only gettable. .Sp The format of the private keys for the different algorithms is: .RS 4 .IP \fBSecP256r1MLKEM768\fR 4 .IX Item "SecP256r1MLKEM768" 32 byte EC private key followed by a 2400 byte ML\-KEM\-768 private key. .IP \fBSecP384r1MLKEM1024\fR 4 .IX Item "SecP384r1MLKEM1024" 48 byte EC private key followed by a 3168 byte ML\-KEM\-1024 private key. .IP \fBX25519MLKEM768\fR 4 .IX Item "X25519MLKEM768" 2400 byte ML\-KEM\-768 private key followed by a 32 byte X25519 private key. .IP \fBX448MLKEM1024\fR 4 .IX Item "X448MLKEM1024" 3168 byte ML\-KEM\-1024 private key followed by a 56 byte X448 private key. .IP \fBcurveSM2MLKEM768\fR 4 .IX Item "curveSM2MLKEM768" 32 byte SM2 private key followed by a 2400 byte ML\-KEM\-768 private key. .RE .RS 4 .RE .SH "CONFORMING TO" .IX Header "CONFORMING TO" .IP https://datatracker.ietf.org/doc/draft\-ietf\-tls\-ecdhe\-mlkem/ 4 .IX Item "https://datatracker.ietf.org/doc/draft-ietf-tls-ecdhe-mlkem/" Note that \fBX448MLKEM1024\fR is not defined by this document. .IP SP800\-227 4 .IX Item "SP800-227" The general notation used in this document says that outputs are combined/processed in order of the names. \&\fBX25519MLKEM768\fR and \fBX448MLKEM768\fR 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. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBEVP_KEM\-ML\-KEM\fR\|(7), \&\fBEVP_PKEY\-X25519\fR\|(7), \&\fBEVP_PKEY\-EC\fR\|(7), \&\fBEVP_PKEY\-SM2\fR\|(7), \&\fBprovider\-keymgmt\fR\|(7) .SH HISTORY .IX Header "HISTORY" This functionality was added in OpenSSL 3.5. .PP Support for \fBcurveSM2MLKEM768\fR was added in OpenSSL 4.0. .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright 2026 The OpenSSL Project Authors. All Rights Reserved. .PP 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 .