diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man7/EVP_PKEY-ML-KEM.7')
| -rw-r--r-- | secure/lib/libcrypto/man/man7/EVP_PKEY-ML-KEM.7 | 367 |
1 files changed, 367 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/man7/EVP_PKEY-ML-KEM.7 b/secure/lib/libcrypto/man/man7/EVP_PKEY-ML-KEM.7 new file mode 100644 index 000000000000..bb3e59e82f7f --- /dev/null +++ b/secure/lib/libcrypto/man/man7/EVP_PKEY-ML-KEM.7 @@ -0,0 +1,367 @@ +.\" -*- 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 7ossl" +.TH EVP_PKEY-ML-KEM 7ossl 2025-09-30 3.5.4 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) <octet string>" 4 +.IX Item """seed"" (OSSL_PKEY_PARAM_ML_KEM_SEED) <octet string>" +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) <UTF8 string>" 4 +.IX Item """properties"" (OSSL_PKEY_PARAM_PROPERTIES) <UTF8 string>" +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) <octet string>" 4 +.IX Item """pub"" (OSSL_PKEY_PARAM_PUB_KEY) <octet string>" +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) <octet string>" 4 +.IX Item """priv"" (OSSL_PKEY_PARAM_PRIV_KEY) <octet string>" +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) <octet string>" 4 +.IX Item """encoded-pub-key"" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>" +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) <UTF8 string>" 4 +.el .IP "\f(CWml\-kem.import_pct_type\fR (\fBOSSL_PKEY_PARAM_ML_KEM_IMPORT_PCT_TYPE\fR) <UTF8 string>" 4 +.IX Item "ml-kem.import_pct_type (OSSL_PKEY_PARAM_ML_KEM_IMPORT_PCT_TYPE) <UTF8 string>" +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) <UTF8 string>" 4 +.el .IP "\f(CWml\-kem.retain_seed\fR (\fBOSSL_PKEY_PARAM_ML_KEM_RETAIN_SEED\fR) <UTF8 string>" 4 +.IX Item "ml-kem.retain_seed (OSSL_PKEY_PARAM_ML_KEM_RETAIN_SEED) <UTF8 string>" +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) <UTF8 string>" 4 +.el .IP "\f(CWml\-kem.prefer_seed\fR (\fBOSSL_PKEY_PARAM_ML_KEM_PREFER_SEED\fR) <UTF8 string>" 4 +.IX Item "ml-kem.prefer_seed (OSSL_PKEY_PARAM_ML_KEM_PREFER_SEED) <UTF8 string>" +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) <UTF8 string>" 4 +.el .IP "\f(CWml\-kem.input_formats\fR (\fBOSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS\fR) <UTF8 string>" 4 +.IX Item "ml-kem.input_formats (OSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS) <UTF8 string>" +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) <UTF8 string>" 4 +.el .IP "\f(CWml\-kem.output_formats\fR (\fBOSSL_PKEY_PARAM_ML_KEM_OUTPUT_FORMATS\fR) <UTF8 string>" 4 +.IX Item "ml-kem.output_formats (OSSL_PKEY_PARAM_ML_KEM_OUTPUT_FORMATS) <UTF8 string>" +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 +<https://www.openssl.org/source/license.html>. |