.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" 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 .\" ======================================================================== .\" .IX Title "EVP_PKEY-ML-KEM 7ssl" .TH EVP_PKEY-ML-KEM 7ssl 2025-04-10 3.5.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\-ML\-KEM, EVP_KEYMGMT\-ML\-KEM, EVP_PKEY\-ML\-KEM\-512, EVP_PKEY\-ML\-KEM\-768, EVP_PKEY\-ML\-KEM\-1024, EVP_KEYMGMT\-ML\-KEM\-512, EVP_KEYMGMT\-ML\-KEM\-768, EVP_KEYMGMT\-ML\-KEM\-1024 \&\- ML\-KEM keytype and algorithm support .SH DESCRIPTION .IX Header "DESCRIPTION" The \fBML\-KEM\-512\fR, \fBML\-KEM\-768\fR, and \fBML\-KEM\-1024\fR keytypes are implemented in OpenSSL's default and FIPS providers. .SS "Keygen Parameters" .IX Subsection "Keygen Parameters" No mandatory parameters are required for generating a key pair. To set explicit parameters, use \fBEVP_PKEY_CTX_set_params()\fR after calling \&\fBEVP_PKEY_keygen_init()\fR. .IP """seed"" (\fBOSSL_PKEY_PARAM_ML_KEM_SEED\fR) " 4 .IX Item """seed"" (OSSL_PKEY_PARAM_ML_KEM_SEED) " Internally, ML-KEM generates keys using a 64\-byte random value (seed), which is the concatenation of the 32\-byte \fId\fR and \fIz\fR parameters described in FIPS 203. This optional parameter can be used to set a pre-determined seed prior to keypair generation. .Sp Generated keys default to retaining the seed used. The seed is also by default retained when keys are loaded from \fBPKCS#8\fR files in the seed format. When available, the seed parameter is also used during key export and import, with keys (by default) regenerated from the seed even when also provided on import. See "Provider configuration parameters" below for related controls. .Sp When the seed is retained, it is also available as a \fBgettable\fR parameter, and private key output to \fBPKCS#8\fR files will by default include the seed. When the seed was not initially known, or was not retained, \fBPKCS#8\fR private key files will contain only the private key in FIPS 203 \f(CW\*(C`dk\*(C'\fR format. .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 ML-KEM hashing operations. .Sp Use \fBEVP_PKEY_CTX_set_params\fR\|(3) after calling \fBEVP_PKEY_keygen_init\fR\|(3). .SS "Common parameters" .IX Subsection "Common parameters" In addition to the common parameters that all keytypes should support (see "Common Information Parameters" in \fBprovider\-keymgmt\fR\|(7)), \fBML-KEM\fR keys keys support the parameters listed below. These are gettable using \&\fBEVP_PKEY_get_octet_string_param\fR\|(3) or \fBEVP_PKEY_get_params\fR\|(3). They can be initialised via \fBEVP_PKEY_fromdata\fR\|(3), and are returned by \&\fBEVP_PKEY_todata\fR\|(3) given a suitable \fIselection\fR. Once a public or private key is configured, it can no longer be modified, nor can another key component be added. .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 used when importing or exporting the public key value with the \fBEVP_PKEY_fromdata()\fR and \fBEVP_PKEY_todata()\fR functions. The key length and content is that of the FIPS 203 (Algorithm 16: \&\fBML\-KEM.KeyGen_internal\fR) \fBek\fR public key for the given ML-KEM variant. Initial import aside, this parameter is otherwise only gettable. .IP """priv"" (\fBOSSL_PKEY_PARAM_PRIV_KEY\fR) " 4 .IX Item """priv"" (OSSL_PKEY_PARAM_PRIV_KEY) " The private key value. .Sp This parameter is used when importing or exporting the private key value with the \fBEVP_PKEY_fromdata()\fR and \fBEVP_PKEY_todata()\fR functions. The key length and content is that of the FIPS 203 (Algorithm 16: \&\fBML\-KEM.KeyGen_internal\fR) \fBdk\fR private key for the given ML-KEM variant. Initial import aside, this parameter is otherwise only gettable. .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 a public key. The key format is that of \fBek\fR in FIPS 203, Algorithm 16: \&\fBML\-KEM.KeyGen_internal\fR. Updates of the public and private key components are only allowed on keys that are empty. Once a public or private key component is set, no further changes are allowed. This parameter is gettable and settable (once only). .SS "Provider configuration parameters" .IX Subsection "Provider configuration parameters" See the description of the \fB\-provparam\fR option in \fBopenssl\fR\|(1) to learn how to set provider configuration parameters in the command line tools. See \fBOSSL_PROVIDER_add_conf_parameter\fR\|(3) to learn how to set provider configuration options programmatically. .ie n .IP """ml\-kem.import_pct_type"" (\fBOSSL_PKEY_PARAM_ML_KEM_IMPORT_PCT_TYPE\fR) " 4 .el .IP "\f(CWml\-kem.import_pct_type\fR (\fBOSSL_PKEY_PARAM_ML_KEM_IMPORT_PCT_TYPE\fR) " 4 .IX Item "ml-kem.import_pct_type (OSSL_PKEY_PARAM_ML_KEM_IMPORT_PCT_TYPE) " When an \fBML-KEM\fR key is imported as an explict FIPS 203 \fBdk\fR decapsulation key, rather than a seed, a pairwise consistency test (PCT) is optionally performed. By default, or when this parameter is set explicitly to \f(CW\*(C`random\*(C'\fR, the PCT is performed with a random entropy value for the encapsulation step. Setting the parameter to \f(CW\*(C`fixed\*(C'\fR, still runs the test, but the encapsulation entropy is a fixed 32 byte value. Specifying any other value of the parameter, e.g. \f(CW\*(C`none\*(C'\fR, skips the test. .ie n .IP """ml\-kem.retain_seed"" (\fBOSSL_PKEY_PARAM_ML_KEM_RETAIN_SEED\fR) " 4 .el .IP "\f(CWml\-kem.retain_seed\fR (\fBOSSL_PKEY_PARAM_ML_KEM_RETAIN_SEED\fR) " 4 .IX Item "ml-kem.retain_seed (OSSL_PKEY_PARAM_ML_KEM_RETAIN_SEED) " When set to a string representing a false boolean value (see \&\fBOSSL_PROVIDER_conf_get_bool\fR\|(3)), the seed will not be retained after key generation or key import from a seed value. If the resulting key is then written to a PKCS#8 object, it will contain only the FIPS 203 \f(CW\*(C`dk\*(C'\fR key. .ie n .IP """ml\-kem.prefer_seed"" (\fBOSSL_PKEY_PARAM_ML_KEM_PREFER_SEED\fR) " 4 .el .IP "\f(CWml\-kem.prefer_seed\fR (\fBOSSL_PKEY_PARAM_ML_KEM_PREFER_SEED\fR) " 4 .IX Item "ml-kem.prefer_seed (OSSL_PKEY_PARAM_ML_KEM_PREFER_SEED) " When decoding PKCS#8 objects that contain both a seed and the FIPS 203 \f(CW\*(C`dk\*(C'\fR private key, the seed is by default used to regenerate the key, and the companion key is ignored. When this configuration parameter is set to a string representing a false boolean value (see \fBOSSL_PROVIDER_conf_get_bool\fR\|(3)), the seed is ignored (neither used to regenerate the key, nor retained), and the companion key is used instead. .ie n .IP """ml\-kem.input_formats"" (\fBOSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS\fR) " 4 .el .IP "\f(CWml\-kem.input_formats\fR (\fBOSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS\fR) " 4 .IX Item "ml-kem.input_formats (OSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS) " List of enabled private key input formats when parsing PKCS#8 objects. List elements are separated by commas and/or spaces or tabs. The list of enabled formats can be specified in the configuration file, as seen in the "EXAMPLES" section below, or the via the \fB\-provparam\fR command-line option (see also \fBOSSL_PROVIDER_add_conf_parameter\fR\|(3)). .Sp Values specified on the command-line override any configuration file settings. By default all the supported formats are enabled. The supported formats are: .RS 4 .ie n .IP """seed\-priv"":" 4 .el .IP \f(CWseed\-priv\fR: 4 .IX Item "seed-priv:" This format represents \fBPKCS#8\fR objects in which both the FIPS 203 64\-byte \&\fB(d, z)\fR seed and the decapsulation key \fBdk\fR are present in the private key as part of the DER encoding of the ASN.1 sequence: .Sp .Vb 6 \& ML\-KEM\-PrivateKey ::= CHOICE { \& seed [0] IMPLICIT OCTET STRING (SIZE (64)), \& expandedKey OCTET STRING (SIZE (1632 | 2400 | 3168)), \& both SEQUENCE { \& seed OCTET STRING (SIZE (64)), \& expandedKey OCTET STRING (SIZE (1632 | 2400 | 3168)) } } .Ve .Sp If the \f(CW\*(C`seed\-priv\*(C'\fR format is not included in the list, this format will not be recognised on input. .ie n .IP """seed\-only"":" 4 .el .IP \f(CWseed\-only\fR: 4 .IX Item "seed-only:" This format represents \fBPKCS#8\fR objects in which only the 64\-byte \fB(d, z)\fR seed is present in the above sequence. If the \f(CW\*(C`seed\-only\*(C'\fR format is not included in the list, this format will not be recognised on input. .ie n .IP """priv\-only"":" 4 .el .IP \f(CWpriv\-only\fR: 4 .IX Item "priv-only:" This format represents \fBPKCS#8\fR objects in which only the FIPS 203 decapsulation key \fBdk\fR is present in the above sequence. If the \f(CW\*(C`priv\-only\*(C'\fR format is not included in the list, this format will not be recognised on input. .ie n .IP """oqskeypair"":" 4 .el .IP \f(CWoqskeypair\fR: 4 .IX Item "oqskeypair:" This format represents \fBPKCS#8\fR objects in which the private key is a DER encoding of an octet string containing the concatenaton of the FIPS 203 decapsulation key \fBdk\fR and the encapsulation key \fBek\fR. This encoding is used in some builds of the \f(CW\*(C`oqsprovider\*(C'\fR. If the \f(CW\*(C`oqskeypair\*(C'\fR format is not included in the list, this format will not be recognised on input. .ie n .IP """bare\-seed"":" 4 .el .IP \f(CWbare\-seed\fR: 4 .IX Item "bare-seed:" This format represents \fBPKCS#8\fR objects in which the private key contains the 64\-byte FIPS 204 seed \fB(d, z)\fR without any ASN.1 encapsulation. If the \f(CW\*(C`bare\-seed\*(C'\fR format is not included in the list, this format will not be recognised on input. .ie n .IP """bare\-priv"":" 4 .el .IP \f(CWbare\-priv\fR: 4 .IX Item "bare-priv:" This format represents \fBPKCS#8\fR objects in which the private key contains the FIPS 204 decapsulation key \fBdk\fR without any ASN.1 encapsulation. If the \f(CW\*(C`bare\-priv\*(C'\fR format is not included in the list, this format will not be recognised on input. .RE .RS 4 .RE .ie n .IP """ml\-kem.output_formats"" (\fBOSSL_PKEY_PARAM_ML_KEM_OUTPUT_FORMATS\fR) " 4 .el .IP "\f(CWml\-kem.output_formats\fR (\fBOSSL_PKEY_PARAM_ML_KEM_OUTPUT_FORMATS\fR) " 4 .IX Item "ml-kem.output_formats (OSSL_PKEY_PARAM_ML_KEM_OUTPUT_FORMATS) " Ordered list of enabled private key output formats when writing \fBPKCS#8\fR files. List elements are separated by commas, spaces or tabs. The list of enabled formats can be specified in the configuration file, as seen in the "EXAMPLES" section below, or the via the \fB\-provparam\fR command-line option. .Sp This supports the same set of formats as described under \f(CW\*(C`ml\-kem.input_formats\*(C'\fR above. The order in which elements are listed is important, the selected format will be the first one that is possible to output. If the key seed is known, the first listed format will be selected. If the key seed is not known, the first format that omits the seed will be selected. The default order is equivalent to \f(CW\*(C`seed\-priv\*(C'\fR first and \f(CW\*(C`priv\-only\*(C'\fR second, with both seed and key output when the seed is available, and just the key otherwise. If \f(CW\*(C`seed\-only\*(C'\fR is listed first, then the seed will be output without the key when available, otherwise the output will have just the key. If \f(CW\*(C`priv\-only\*(C'\fR is listed first, then just the key is output regardless of whether the seed is present. The legacy \f(CW\*(C`oqskeypair\*(C'\fR, \f(CW\*(C`bare\-seed\*(C'\fR and \f(CW\*(C`bare\-priv\*(C'\fR formats can also be output, by listing those first. .SH "CONFORMING TO" .IX Header "CONFORMING TO" .IP "FIPS 203" 4 .IX Item "FIPS 203" .SH EXAMPLES .IX Header "EXAMPLES" An \fBEVP_PKEY\fR context can be obtained by calling: .PP .Vb 2 \& EVP_PKEY_CTX *pctx = \& EVP_PKEY_CTX_new_from_name(NULL, "ML\-KEM\-768", NULL); .Ve .PP An \fBML\-KEM\-768\fR key can be generated like this: .PP .Vb 1 \& pkey = EVP_PKEY_Q_keygen(NULL, NULL, "ML\-KEM\-768"); .Ve .PP An \fBML-KEM\fR private key in seed format can be converted to a key in the FIPS 203 \fBdk\fR format by running: .PP .Vb 2 \& $ openssl pkey \-provparam ml\-kem.retain_seed=no \e \& \-in seed\-only.pem \-out priv\-only.pem .Ve .PP To generate an, e.g., \fBML\-KEM\-768\fR key, in FIPS 203 \fBdk\fR format, you can run: .PP .Vb 2 \& $ openssl genpkey \-provparam ml\-kem.retain_seed=no \e \& \-algorithm ml\-kem\-768 \-out priv\-only.pem .Ve .PP If you have a \fBPKCS#8\fR file with both a seed and a key, and prefer to import the companion key rather than the seed, you can run: .PP .Vb 2 \& $ openssl pkey \-provparam ml\-kem.prefer_seed=no \e \& \-in seed\-priv.pem \-out priv\-only.pem .Ve .PP In the \fBopenssl.cnf\fR file, this looks like: .PP .Vb 1 \& openssl_conf = openssl_init \& \& [openssl_init] \& providers = providers_sect \& \& # Can be referenced in one or more provider sections \& [ml_kem_sect] \& prefer_seed = yes \& retain_seed = yes \& # OQS legacy formats disabled \& input_formats = seed\-priv, seed\-only, priv\-only \& # Output either the seed alone, or else the key alone \& output_formats = seed\-only, priv\-only \& \& [providers_sect] \& default = default_sect \& # Or perhaps just: base = default_sect \& base = base_sect \& \& [default_sect] \& ml\-kem = ml_kem_sect \& \& [base_sect] \& ml\-kem = ml_kem_sect .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBopenssl\fR\|(1), \&\fBopenssl\-pkey\fR\|(1), \&\fBopenssl\-genpkey\fR\|(1), \&\fBEVP_KEYMGMT\fR\|(3), \&\fBEVP_PKEY\fR\|(3), \&\fBEVP_PKEY_get_raw_private_key\fR\|(3), \&\fBEVP_PKEY_get_raw_public_key\fR\|(3), \&\fBEVP_PKEY_get1_encoded_public_key\fR\|(3), \&\fBOSSL_PROVIDER_add_conf_parameter\fR\|(3), \&\fBprovider\-keymgmt\fR\|(7), \&\fBEVP_KEM\-ML\-KEM\fR\|(7) .SH HISTORY .IX Header "HISTORY" This functionality was added in OpenSSL 3.5. .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright 2024\-2025 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 .