Debian Codegraph @

upstream/debian-unstable/man7/EVP_PKEY-ML-KEM.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EVP_PKEY-ML-KEM 7SSL"
58 .TH EVP_PKEY-ML-KEM 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 EVP_PKEY\-ML\-KEM,
65 EVP_KEYMGMT\-ML\-KEM,
66 EVP_PKEY\-ML\-KEM\-512,
67 EVP_PKEY\-ML\-KEM\-768,
68 EVP_PKEY\-ML\-KEM\-1024,
69 EVP_KEYMGMT\-ML\-KEM\-512,
70 EVP_KEYMGMT\-ML\-KEM\-768,
71 EVP_KEYMGMT\-ML\-KEM\-1024
72 \&\- ML\-KEM keytype and algorithm support
73 .SH DESCRIPTION
74 .IX Header "DESCRIPTION"
75 The \fBML\-KEM\-512\fR, \fBML\-KEM\-768\fR, and \fBML\-KEM\-1024\fR keytypes are implemented
76 in OpenSSL's default and FIPS providers.
77 .SS "Keygen Parameters"
78 .IX Subsection "Keygen Parameters"
79 No mandatory parameters are required for generating a key pair.
80 To set explicit parameters, use \fBEVP_PKEY_CTX_set_params()\fR after calling
81 \&\fBEVP_PKEY_keygen_init()\fR.
82 .IP """seed"" (\fBOSSL_PKEY_PARAM_ML_KEM_SEED\fR) <octet string>" 4
83 .IX Item """seed"" (OSSL_PKEY_PARAM_ML_KEM_SEED) <octet string>"
84 Internally, ML-KEM generates keys using a 64\-byte random value (seed), which is
85 the concatenation of the 32\-byte \fId\fR and \fIz\fR parameters described in FIPS 203.
86 This optional parameter can be used to set a pre-determined seed prior to
87 keypair generation.
88 .Sp
89 Generated keys default to retaining the seed used.
90 The seed is also by default retained when keys are loaded from \fBPKCS#8\fR files
91 in the seed format.
92 When available, the seed parameter is also used during key export and import,
93 with keys (by default) regenerated from the seed even when also provided on import.
94 See "Provider configuration parameters" below for related controls.
95 .Sp
96 When the seed is retained, it is also available as a \fBgettable\fR parameter,
97 and private key output to \fBPKCS#8\fR files will by default include the seed.
98 When the seed was not initially known, or was not retained, \fBPKCS#8\fR private
99 key files will contain only the private key in FIPS 203 \f(CW\*(C`dk\*(C'\fR format.
100 .IP """properties"" (\fBOSSL_PKEY_PARAM_PROPERTIES\fR) <UTF8 string>" 4
101 .IX Item """properties"" (OSSL_PKEY_PARAM_PROPERTIES) <UTF8 string>"
102 Sets properties to be used when fetching algorithm implementations used for
103 ML-KEM hashing operations.
104 .Sp
105 Use \fBEVP_PKEY_CTX_set_params\fR\|(3) after calling \fBEVP_PKEY_keygen_init\fR\|(3).
106 .SS "Common parameters"
107 .IX Subsection "Common parameters"
108 In addition to the common parameters that all keytypes should support (see
109 "Common Information Parameters" in \fBprovider\-keymgmt\fR\|(7)), \fBML-KEM\fR keys
110 keys support the parameters listed below.
111 These are gettable using
112 \&\fBEVP_PKEY_get_octet_string_param\fR\|(3) or \fBEVP_PKEY_get_params\fR\|(3).
113 They can be initialised via \fBEVP_PKEY_fromdata\fR\|(3), and are returned by
114 \&\fBEVP_PKEY_todata\fR\|(3) given a suitable \fIselection\fR.
115 Once a public or private key is configured, it can no longer be modified,
116 nor can another key component be added.
117 .IP """pub"" (\fBOSSL_PKEY_PARAM_PUB_KEY\fR) <octet string>" 4
118 .IX Item """pub"" (OSSL_PKEY_PARAM_PUB_KEY) <octet string>"
119 The public key value.
120 .Sp
121 This parameter is used when importing or exporting the public key value with
122 the \fBEVP_PKEY_fromdata()\fR and \fBEVP_PKEY_todata()\fR functions.
123 The key length and content is that of the FIPS 203 (Algorithm 16:
124 \&\fBML\-KEM.KeyGen_internal\fR) \fBek\fR public key for the given ML-KEM variant.
125 Initial import aside, this parameter is otherwise only gettable.
126 .IP """priv"" (\fBOSSL_PKEY_PARAM_PRIV_KEY\fR) <octet string>" 4
127 .IX Item """priv"" (OSSL_PKEY_PARAM_PRIV_KEY) <octet string>"
128 The private key value.
129 .Sp
130 This parameter is used when importing or exporting the private key value with
131 the \fBEVP_PKEY_fromdata()\fR and \fBEVP_PKEY_todata()\fR functions.
132 The key length and content is that of the FIPS 203 (Algorithm 16:
133 \&\fBML\-KEM.KeyGen_internal\fR) \fBdk\fR private key for the given ML-KEM variant.
134 Initial import aside, this parameter is otherwise only gettable.
135 .IP """encoded-pub-key"" (\fBOSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\fR) <octet string>" 4
136 .IX Item """encoded-pub-key"" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>"
137 Used for getting and setting the encoding of a public key.
138 The key format is that of \fBek\fR in FIPS 203, Algorithm 16:
139 \&\fBML\-KEM.KeyGen_internal\fR.
140 Updates of the public and private key components are only allowed on keys that
141 are empty.
142 Once a public or private key component is set, no further changes are allowed.
143 This parameter is gettable and settable (once only).
144 .SS "Provider configuration parameters"
145 .IX Subsection "Provider configuration parameters"
146 See the description of the \fB\-provparam\fR option in \fBopenssl\fR\|(1) to learn
147 how to set provider configuration parameters in the command line tools.
148 See \fBOSSL_PROVIDER_add_conf_parameter\fR\|(3) to learn how to set provider
149 configuration options programmatically.
150 .ie n .IP """ml\-kem.import_pct_type"" (\fBOSSL_PKEY_PARAM_ML_KEM_IMPORT_PCT_TYPE\fR) <UTF8 string>" 4
151 .el .IP "\f(CWml\-kem.import_pct_type\fR (\fBOSSL_PKEY_PARAM_ML_KEM_IMPORT_PCT_TYPE\fR) <UTF8 string>" 4
152 .IX Item "ml-kem.import_pct_type (OSSL_PKEY_PARAM_ML_KEM_IMPORT_PCT_TYPE) <UTF8 string>"
153 When an \fBML-KEM\fR key is imported as an explicit FIPS 203 \fBdk\fR decapsulation
154 key, rather than a seed, a pairwise consistency test (PCT) is optionally
155 performed.
156 By default, or when this parameter is set explicitly to \f(CW\*(C`random\*(C'\fR, the PCT
157 is performed with a random entropy value for the encapsulation step.
158 Setting the parameter to \f(CW\*(C`fixed\*(C'\fR, still runs the test, but the encapsulation
159 entropy is a fixed 32 byte value.
160 Specifying any other value of the parameter, e.g. \f(CW\*(C`none\*(C'\fR, skips the test.
161 .ie n .IP """ml\-kem.retain_seed"" (\fBOSSL_PKEY_PARAM_ML_KEM_RETAIN_SEED\fR) <UTF8 string>" 4
162 .el .IP "\f(CWml\-kem.retain_seed\fR (\fBOSSL_PKEY_PARAM_ML_KEM_RETAIN_SEED\fR) <UTF8 string>" 4
163 .IX Item "ml-kem.retain_seed (OSSL_PKEY_PARAM_ML_KEM_RETAIN_SEED) <UTF8 string>"
164 When set to a string representing a false boolean value (see
165 \&\fBOSSL_PROVIDER_conf_get_bool\fR\|(3)), the seed will not be retained after key
166 generation or key import from a seed value.
167 If the resulting key is then written to a PKCS#8 object, it will contain
168 only the FIPS 203 \f(CW\*(C`dk\*(C'\fR key.
169 .ie n .IP """ml\-kem.prefer_seed"" (\fBOSSL_PKEY_PARAM_ML_KEM_PREFER_SEED\fR) <UTF8 string>" 4
170 .el .IP "\f(CWml\-kem.prefer_seed\fR (\fBOSSL_PKEY_PARAM_ML_KEM_PREFER_SEED\fR) <UTF8 string>" 4
171 .IX Item "ml-kem.prefer_seed (OSSL_PKEY_PARAM_ML_KEM_PREFER_SEED) <UTF8 string>"
172 When decoding PKCS#8 objects that contain both a seed and the FIPS 203 \f(CW\*(C`dk\*(C'\fR
173 private key, the seed is by default used to regenerate the key, and the
174 companion key is ignored.
175 When this configuration parameter is set to a string representing a false
176 boolean value (see \fBOSSL_PROVIDER_conf_get_bool\fR\|(3)), the seed is ignored
177 (neither used to regenerate the key, nor retained), and the companion key is
178 used instead.
179 .ie n .IP """ml\-kem.input_formats"" (\fBOSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS\fR) <UTF8 string>" 4
180 .el .IP "\f(CWml\-kem.input_formats\fR (\fBOSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS\fR) <UTF8 string>" 4
181 .IX Item "ml-kem.input_formats (OSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS) <UTF8 string>"
182 List of enabled private key input formats when parsing PKCS#8 objects.
183 List elements are separated by commas and/or spaces or tabs.
184 The list of enabled formats can be specified in the configuration file, as seen
185 in the "EXAMPLES" section below, or the via the \fB\-provparam\fR command-line
186 option (see also \fBOSSL_PROVIDER_add_conf_parameter\fR\|(3)).
187 .Sp
188 Values specified on the command-line override any configuration file settings.
189 By default all the supported formats are enabled.
190 The supported formats are:
191 .RS 4
192 .ie n .IP """seed\-priv"":" 4
193 .el .IP \f(CWseed\-priv\fR: 4
194 .IX Item "seed-priv:"
195 This format represents \fBPKCS#8\fR objects in which both the FIPS 203 64\-byte
196 \&\fB(d, z)\fR seed and the decapsulation key \fBdk\fR are present in the private key
197 as part of the DER encoding of the ASN.1 sequence:
198 .Sp
199 .Vb 6
200 \& ML\-KEM\-PrivateKey ::= CHOICE {
201 \& seed [0] IMPLICIT OCTET STRING (SIZE (64)),
202 \& expandedKey OCTET STRING (SIZE (1632 | 2400 | 3168)),
203 \& both SEQUENCE {
204 \& seed OCTET STRING (SIZE (64)),
205 \& expandedKey OCTET STRING (SIZE (1632 | 2400 | 3168)) } }
206 .Ve
207 .Sp
208 If the \f(CW\*(C`seed\-priv\*(C'\fR format is not included in the list, this format will not be
209 recognised on input.
210 .ie n .IP """seed\-only"":" 4
211 .el .IP \f(CWseed\-only\fR: 4
212 .IX Item "seed-only:"
213 This format represents \fBPKCS#8\fR objects in which only the 64\-byte \fB(d, z)\fR
214 seed is present in the above sequence.
215 If the \f(CW\*(C`seed\-only\*(C'\fR format is not included in the list, this format will not be
216 recognised on input.
217 .ie n .IP """priv\-only"":" 4
218 .el .IP \f(CWpriv\-only\fR: 4
219 .IX Item "priv-only:"
220 This format represents \fBPKCS#8\fR objects in which only the FIPS 203
221 decapsulation key \fBdk\fR is present in the above sequence.
222 If the \f(CW\*(C`priv\-only\*(C'\fR format is not included in the list, this format will not be
223 recognised on input.
224 .ie n .IP """oqskeypair"":" 4
225 .el .IP \f(CWoqskeypair\fR: 4
226 .IX Item "oqskeypair:"
227 This format represents \fBPKCS#8\fR objects in which the private key is a DER
228 encoding of an octet string containing the concatenaton of the FIPS 203
229 decapsulation key \fBdk\fR and the encapsulation key \fBek\fR.
230 This encoding is used in some builds of the \f(CW\*(C`oqsprovider\*(C'\fR.
231 If the \f(CW\*(C`oqskeypair\*(C'\fR format is not included in the list, this format will not be
232 recognised on input.
233 .ie n .IP """bare\-seed"":" 4
234 .el .IP \f(CWbare\-seed\fR: 4
235 .IX Item "bare-seed:"
236 This format represents \fBPKCS#8\fR objects in which the private key contains
237 the 64\-byte FIPS 204 seed \fB(d, z)\fR without any ASN.1 encapsulation.
238 If the \f(CW\*(C`bare\-seed\*(C'\fR format is not included in the list, this format will not be
239 recognised on input.
240 .ie n .IP """bare\-priv"":" 4
241 .el .IP \f(CWbare\-priv\fR: 4
242 .IX Item "bare-priv:"
243 This format represents \fBPKCS#8\fR objects in which the private key contains
244 the FIPS 204 decapsulation key \fBdk\fR without any ASN.1 encapsulation.
245 If the \f(CW\*(C`bare\-priv\*(C'\fR format is not included in the list, this format will not be
246 recognised on input.
247 .RE
248 .RS 4
249 .RE
250 .ie n .IP """ml\-kem.output_formats"" (\fBOSSL_PKEY_PARAM_ML_KEM_OUTPUT_FORMATS\fR) <UTF8 string>" 4
251 .el .IP "\f(CWml\-kem.output_formats\fR (\fBOSSL_PKEY_PARAM_ML_KEM_OUTPUT_FORMATS\fR) <UTF8 string>" 4
252 .IX Item "ml-kem.output_formats (OSSL_PKEY_PARAM_ML_KEM_OUTPUT_FORMATS) <UTF8 string>"
253 Ordered list of enabled private key output formats when writing \fBPKCS#8\fR files.
254 List elements are separated by commas, spaces or tabs.
255 The list of enabled formats can be specified in the configuration file, as seen
256 in the "EXAMPLES" section below, or the via the \fB\-provparam\fR command-line
257 option.
258 .Sp
259 This supports the same set of formats as described under \f(CW\*(C`ml\-kem.input_formats\*(C'\fR
260 above.
261 The order in which elements are listed is important, the selected format will be
262 the first one that is possible to output.
263 If the key seed is known, the first listed format will be selected.
264 If the key seed is not known, the first format that omits the seed will be selected.
265 The default order is equivalent to \f(CW\*(C`seed\-priv\*(C'\fR first and \f(CW\*(C`priv\-only\*(C'\fR second, with
266 both seed and key output when the seed is available, and just the
267 key otherwise.
268 If \f(CW\*(C`seed\-only\*(C'\fR is listed first, then the seed will be output without the key
269 when available, otherwise the output will have just the key.
270 If \f(CW\*(C`priv\-only\*(C'\fR is listed first, then just the key is output regardless of
271 whether the seed is present.
272 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
273 output, by listing those first.
274 .SH "CONFORMING TO"
275 .IX Header "CONFORMING TO"
276 .IP "FIPS 203" 4
277 .IX Item "FIPS 203"
278 .SH EXAMPLES
279 .IX Header "EXAMPLES"
280 An \fBEVP_PKEY\fR context can be obtained by calling:
281 .PP
282 .Vb 2
283 \& EVP_PKEY_CTX *pctx =
284 \& EVP_PKEY_CTX_new_from_name(NULL, "ML\-KEM\-768", NULL);
285 .Ve
286 .PP
287 An \fBML\-KEM\-768\fR key can be generated like this:
288 .PP
289 .Vb 1
290 \& pkey = EVP_PKEY_Q_keygen(NULL, NULL, "ML\-KEM\-768");
291 .Ve
292 .PP
293 An \fBML-KEM\fR private key in seed format can be converted to a key in the FIPS
294 203 \fBdk\fR format by running:
295 .PP
296 .Vb 2
297 \& $ openssl pkey \-provparam ml\-kem.retain_seed=no \e
298 \& \-in seed\-only.pem \-out priv\-only.pem
299 .Ve
300 .PP
301 To generate an, e.g., \fBML\-KEM\-768\fR key, in FIPS 203 \fBdk\fR format, you can run:
302 .PP
303 .Vb 2
304 \& $ openssl genpkey \-provparam ml\-kem.retain_seed=no \e
305 \& \-algorithm ml\-kem\-768 \-out priv\-only.pem
306 .Ve
307 .PP
308 If you have a \fBPKCS#8\fR file with both a seed and a key, and prefer to import the
309 companion key rather than the seed, you can run:
310 .PP
311 .Vb 2
312 \& $ openssl pkey \-provparam ml\-kem.prefer_seed=no \e
313 \& \-in seed\-priv.pem \-out priv\-only.pem
314 .Ve
315 .PP
316 In the \fBopenssl.cnf\fR file, this looks like:
317 .PP
318 .Vb 1
319 \& openssl_conf = openssl_init
320 \&
321 \& [openssl_init]
322 \& providers = providers_sect
323 \&
324 \& # Can be referenced in one or more provider sections
325 \& [ml_kem_sect]
326 \& prefer_seed = yes
327 \& retain_seed = yes
328 \& # OQS legacy formats disabled
329 \& input_formats = seed\-priv, seed\-only, priv\-only
330 \& # Output either the seed alone, or else the key alone
331 \& output_formats = seed\-only, priv\-only
332 \&
333 \& [providers_sect]
334 \& default = default_sect
335 \& # Or perhaps just: base = default_sect
336 \& base = base_sect
337 \&
338 \& [default_sect]
339 \& ml\-kem = ml_kem_sect
340 \&
341 \& [base_sect]
342 \& ml\-kem = ml_kem_sect
343 .Ve
344 .SH "SEE ALSO"
345 .IX Header "SEE ALSO"
346 \&\fBopenssl\fR\|(1),
347 \&\fBopenssl\-pkey\fR\|(1),
348 \&\fBopenssl\-genpkey\fR\|(1),
349 \&\fBEVP_KEYMGMT\fR\|(3),
350 \&\fBEVP_PKEY\fR\|(3),
351 \&\fBEVP_PKEY_get_raw_private_key\fR\|(3),
352 \&\fBEVP_PKEY_get_raw_public_key\fR\|(3),
353 \&\fBEVP_PKEY_get1_encoded_public_key\fR\|(3),
354 \&\fBOSSL_PROVIDER_add_conf_parameter\fR\|(3),
355 \&\fBprovider\-keymgmt\fR\|(7),
356 \&\fBEVP_KEM\-ML\-KEM\fR\|(7)
357 .SH HISTORY
358 .IX Header "HISTORY"
359 This functionality was added in OpenSSL 3.5.
360 .SH COPYRIGHT
361 .IX Header "COPYRIGHT"
362 Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved.
363 .PP
364 Licensed under the Apache License 2.0 (the "License"). You may not use
365 this file except in compliance with the License. You can obtain a copy
366 in the file LICENSE in the source distribution or at
367 <https://www.openssl.org/source/license.html>.