Debian Codegraph @

upstream/debian-unstable/man7/EVP_PKEY-ML-DSA.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-DSA 7SSL"
58 .TH EVP_PKEY-ML-DSA 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\-DSA, EVP_KEYMGMT\-ML\-DSA,
65 EVP_PKEY\-ML\-DSA\-44, EVP_PKEY\-ML\-DSA\-65, EVP_PKEY\-ML\-DSA\-87
66 \&\- EVP_PKEY ML\-DSA keytype and algorithm support
67 .SH DESCRIPTION
68 .IX Header "DESCRIPTION"
69 ML-DSA implements the algorithms \fBML\-DSA\-44\fR, \fBML\-DSA\-65\fR and \fBML\-DSA\-87\fR.
70 The key types \fBEVP_PKEY_ML_DSA_44\fR, \fBEVP_PKEY_ML_DSA_65\fR and
71 \&\fBEVP_PKEY_ML_DSA_87\fR are implemented in OpenSSL's default and FIPS providers.
72 These implementations support the associated key, containing the public key \fIpub\fR
73 and the private key \fIpriv\fR.
74 .PP
75 Each of the different key types has an associated security category.
76 This value is one of 2, 3 or 5 for key types \fBML\-DSA\-44\fR, \fBML\-DSA\-65\fR
77 and \fBML\-DSA\-87\fR respectively, which correspond to security strengths of
78 128, 192 and 256 respectively.
79 .SS "Keygen Parameters"
80 .IX Subsection "Keygen Parameters"
81 .IP """seed"" (\fBOSSL_PKEY_PARAM_ML_DSA_SEED\fR) <octet string>" 4
82 .IX Item """seed"" (OSSL_PKEY_PARAM_ML_DSA_SEED) <octet string>"
83 The seed can be used to generate the private and public key components in a
84 deterministic manner.
85 The length of the value supplied must be 32 bytes.
86 When this value is not supplied the seed is generated randomly using a DRBG.
87 .Sp
88 Generated keys default to retaining the seed used.
89 The seed is also by default retained when keys are loaded from \fBPKCS#8\fR files
90 in the seed format.
91 When available, the seed parameter is also used during key export and import,
92 with keys (by default) regenerated from the seed even when also provided on import.
93 See "Provider configuration parameters" below for related controls.
94 .Sp
95 When the seed is retained, it is also available as a \fBgettable\fR parameter,
96 and private key output to \fBPKCS#8\fR files will by default include the seed.
97 When the seed was not initially known, or was not retained, \fBPKCS#8\fR private
98 key files will contain only the private key in FIPS 204 \f(CW\*(C`sk\*(C'\fR format.
99 .IP """properties"" (\fBOSSL_PKEY_PARAM_PROPERTIES\fR) <UTF8 string>" 4
100 .IX Item """properties"" (OSSL_PKEY_PARAM_PROPERTIES) <UTF8 string>"
101 Sets properties to be used when fetching algorithm implementations used for
102 ML-DSA hashing operations.
103 .PP
104 Use \fBEVP_PKEY_CTX_set_params\fR\|(3) after calling \fBEVP_PKEY_keygen_init\fR\|(3).
105 .SS "Common ML-DSA parameters"
106 .IX Subsection "Common ML-DSA parameters"
107 In addition to the common parameters that all keytypes should support (see
108 "Common Information Parameters" in \fBprovider\-keymgmt\fR\|(7), the implementation of
109 these key types support the parameters listed below.
110 These are gettable using
111 \&\fBEVP_PKEY_get_octet_string_param\fR\|(3) or \fBEVP_PKEY_get_params\fR\|(3).
112 They can be initialised via \fBEVP_PKEY_fromdata\fR\|(3), and are returned by
113 \&\fBEVP_PKEY_todata\fR\|(3) given a suitable \fIselection\fR.
114 Once a public or private key is configured, it can no longer be modified,
115 nor can another key component be added.
116 .IP """pub"" (\fBOSSL_PKEY_PARAM_PUB_KEY\fR) <octet string>" 4
117 .IX Item """pub"" (OSSL_PKEY_PARAM_PUB_KEY) <octet string>"
118 The encoded public key value of size 1312, 1952 or 2592 bytes depending on the
119 respective key type of \fBML\-DSA\-44\fR, \fBML\-DSA\-65\fR or \fBML\-DSA\-87\fR.
120 .IP """priv"" (\fBOSSL_PKEY_PARAM_PRIV_KEY\fR) <octet string>" 4
121 .IX Item """priv"" (OSSL_PKEY_PARAM_PRIV_KEY) <octet string>"
122 The encoded private key value of size 2560, 4032 or 4896 bytes depending on the
123 respective key type of \fBML\-DSA\-44\fR, \fBML\-DSA\-65\fR or \fBML\-DSA\-87\fR.
124 .SS "Provider configuration parameters"
125 .IX Subsection "Provider configuration parameters"
126 See the description of the \fB\-provparam\fR option in \fBopenssl\fR\|(1) to learn
127 how to set provider configuration parameters in the command line tools.
128 See \fBOSSL_PROVIDER_add_conf_parameter\fR\|(3) to learn how to set provider
129 configuration options programmatically.
130 .ie n .IP """ml\-dsa.retain_seed"" (\fBOSSL_PKEY_PARAM_ML_DSA_RETAIN_SEED\fR) <UTF8 string>" 4
131 .el .IP "\f(CWml\-dsa.retain_seed\fR (\fBOSSL_PKEY_PARAM_ML_DSA_RETAIN_SEED\fR) <UTF8 string>" 4
132 .IX Item "ml-dsa.retain_seed (OSSL_PKEY_PARAM_ML_DSA_RETAIN_SEED) <UTF8 string>"
133 When set to a string representing a false boolean value (see
134 \&\fBOSSL_PROVIDER_conf_get_bool\fR\|(3)), the seed will not be retained after key
135 generation or key import from a seed value.
136 If the resulting key is then written to a PKCS#8 object, it will contain
137 only the FIPS 204 \f(CW\*(C`sk\*(C'\fR key.
138 .ie n .IP """ml\-dsa.prefer_seed"" (\fBOSSL_PKEY_PARAM_ML_DSA_PREFER_SEED\fR) <UTF8 string>" 4
139 .el .IP "\f(CWml\-dsa.prefer_seed\fR (\fBOSSL_PKEY_PARAM_ML_DSA_PREFER_SEED\fR) <UTF8 string>" 4
140 .IX Item "ml-dsa.prefer_seed (OSSL_PKEY_PARAM_ML_DSA_PREFER_SEED) <UTF8 string>"
141 When decoding PKCS#8 objects that contain both a seed and the FIPS 204 \f(CW\*(C`sk\*(C'\fR
142 private key, the seed is by default used to regenerate the key, and the
143 companion private key is ignored.
144 When this configuration parameter is set to a string representing a false
145 boolean value (see \fBOSSL_PROVIDER_conf_get_bool\fR\|(3)), the seed is ignored
146 (neither used to regenerate the key, nor retained), and the companion key is
147 used instead.
148 .ie n .IP """ml\-dsa.input_formats"" (\fBOSSL_PKEY_PARAM_ML_DSA_INPUT_FORMATS\fR) <UTF8 string>" 4
149 .el .IP "\f(CWml\-dsa.input_formats\fR (\fBOSSL_PKEY_PARAM_ML_DSA_INPUT_FORMATS\fR) <UTF8 string>" 4
150 .IX Item "ml-dsa.input_formats (OSSL_PKEY_PARAM_ML_DSA_INPUT_FORMATS) <UTF8 string>"
151 List of enabled private key input formats when parsing PKCS#8 objects.
152 List elements are separated by commas, spaces or tabs.
153 The list of enabled formats can be specified in the configuration file, as seen
154 in the "EXAMPLES" section below, or the via the \fB\-provparam\fR command-line
155 option (see also \fBOSSL_PROVIDER_add_conf_parameter\fR\|(3)).
156 .Sp
157 Values specified on the command-line override any configuration file settings.
158 By default all the supported formats are enabled.
159 The supported formats are:
160 .RS 4
161 .ie n .IP """seed\-priv"":" 4
162 .el .IP \f(CWseed\-priv\fR: 4
163 .IX Item "seed-priv:"
164 This format represents \fBPKCS#8\fR objects in which both the FIPS 204 32\-byte
165 \&\fBξ\fR seed and the secret key \fBsk\fR are present in the private key as part of
166 the DER encoding of the ASN.1 sequence:
167 .Sp
168 .Vb 6
169 \& ML\-DSA\-PrivateKey ::= CHOICE {
170 \& seed [0] IMPLICIT OCTET STRING (SIZE (32)),
171 \& expandedKey OCTET STRING (SIZE (2560 | 4032 | 4896)),
172 \& both SEQUENCE {
173 \& seed OCTET STRING (SIZE (32)),
174 \& expandedKey OCTET STRING (SIZE (2560 | 4032 | 4896)) } }
175 .Ve
176 .Sp
177 If the \f(CW\*(C`seed\-priv\*(C'\fR format is not included in the list, this format will not be
178 recognised on input.
179 .ie n .IP """seed\-only"":" 4
180 .el .IP \f(CWseed\-only\fR: 4
181 .IX Item "seed-only:"
182 This format represents \fBPKCS#8\fR objects in which only the 32\-byte FIPS 204
183 \&\fBξ\fR seed is present in the above sequence.
184 If the \f(CW\*(C`seed\-only\*(C'\fR format is not included in the list, this format will not be
185 recognised on input.
186 .ie n .IP """priv\-only"":" 4
187 .el .IP \f(CWpriv\-only\fR: 4
188 .IX Item "priv-only:"
189 This format represents \fBPKCS#8\fR objects in which only the FIPS 204
190 private key \fBsk\fR is present in the above sequence.
191 If the \f(CW\*(C`priv\-only\*(C'\fR format is not included in the list, this format will not be
192 recognised on input.
193 .ie n .IP """oqskeypair"":" 4
194 .el .IP \f(CWoqskeypair\fR: 4
195 .IX Item "oqskeypair:"
196 This format represents \fBPKCS#8\fR objects in which the private key is a DER
197 encoding of an octet string containing the concatenaton of the FIPS 204 private
198 key \fBsk\fR and the public key \fBpk\fR.
199 This encoding is used in some builds of the \f(CW\*(C`oqsprovider\*(C'\fR.
200 If the \f(CW\*(C`oqskeypair\*(C'\fR format is not included in the list, this format will not be
201 recognised on input.
202 .ie n .IP """bare\-seed"":" 4
203 .el .IP \f(CWbare\-seed\fR: 4
204 .IX Item "bare-seed:"
205 This format represents \fBPKCS#8\fR objects in which the private key contains
206 the 32\-byte FIPS 204 seed \fBξ\fR without any ASN.1 encapsulation.
207 If the \f(CW\*(C`bare\-seed\*(C'\fR format is not included in the list, this format will not be
208 recognised on input.
209 .ie n .IP """bare\-priv"":" 4
210 .el .IP \f(CWbare\-priv\fR: 4
211 .IX Item "bare-priv:"
212 This format represents \fBPKCS#8\fR objects in which the private key contains
213 the FIPS 204 secret key \fBsk\fR without any ASN.1 encapsulation.
214 If the \f(CW\*(C`bare\-priv\*(C'\fR format is not included in the list, this format will not be
215 recognised on input.
216 .RE
217 .RS 4
218 .RE
219 .ie n .IP """ml\-dsa.output_formats"" (\fBOSSL_PKEY_PARAM_ML_DSA_OUTPUT_FORMATS\fR) <UTF8 string>" 4
220 .el .IP "\f(CWml\-dsa.output_formats\fR (\fBOSSL_PKEY_PARAM_ML_DSA_OUTPUT_FORMATS\fR) <UTF8 string>" 4
221 .IX Item "ml-dsa.output_formats (OSSL_PKEY_PARAM_ML_DSA_OUTPUT_FORMATS) <UTF8 string>"
222 Ordered list of enabled private key output formats when writing \fBPKCS#8\fR files.
223 List elements are separated by commas, spaces or tabs.
224 The list of enabled formats can be specified in the configuration file, as seen
225 in the "EXAMPLES" section below, or the via the \fB\-provparam\fR command-line
226 option.
227 .Sp
228 This supports the same set of formats as described under \f(CW\*(C`ml\-dsa.input_formats\*(C'\fR
229 above.
230 The order in which elements are listed is important, the selected format will be
231 the first one that is possible to output.
232 If the key seed is known, the first listed format will be selected.
233 If the key seed is not known, the first format that omits the seed will be selected.
234 The default order is equivalent to \f(CW\*(C`seed\-priv\*(C'\fR first and \f(CW\*(C`priv\-only\*(C'\fR second, with
235 both seed and key output when the seed is available, and just the
236 key otherwise.
237 If \f(CW\*(C`seed\-only\*(C'\fR is listed first, then the seed will be output without the key
238 when available, otherwise the output will have just the key.
239 If \f(CW\*(C`priv\-only\*(C'\fR is listed first, then just the key is output regardless of
240 whether the seed is present.
241 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
242 output, by listing those first.
243 .SH "CONFORMING TO"
244 .IX Header "CONFORMING TO"
245 .IP "FIPS 204" 4
246 .IX Item "FIPS 204"
247 .SH EXAMPLES
248 .IX Header "EXAMPLES"
249 An \fBEVP_PKEY\fR context can be obtained by calling:
250 .PP
251 .Vb 2
252 \& EVP_PKEY_CTX *pctx =
253 \& EVP_PKEY_CTX_new_from_name(NULL, "ML\-DSA\-44", NULL);
254 .Ve
255 .PP
256 An \fBML\-DSA\-44\fR key can be generated like this:
257 .PP
258 .Vb 1
259 \& pkey = EVP_PKEY_Q_keygen(NULL, NULL, "ML\-DSA\-44");
260 .Ve
261 .PP
262 The key pair components can be extracted from a key by calling:
263 .PP
264 .Vb 3
265 \& /* Sizes large enough for ML\-DSA\-87 */
266 \& uint8_t pub[2592], priv[4896], seed[32]:
267 \& size_t priv_len, pub_len, seed_len;
268 \&
269 \& EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_ML_DSA_SEED,
270 \& seed, sizeof(seed), &seed_len);
271 \& EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PRIV_KEY,
272 \& priv, sizeof(priv), &priv_len);
273 \& EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PUB_KEY,
274 \& pub, sizeof(pub), &pub_len));
275 .Ve
276 .PP
277 An \fBML-DSA\fR private key in seed format can be converted to a key in the FIPS
278 204 \fBsk\fR format by running:
279 .PP
280 .Vb 2
281 \& $ openssl pkey \-provparam ml\-dsa.retain_seed=no \e
282 \& \-in seed\-only.pem \-out priv\-only.pem
283 .Ve
284 .PP
285 To generate an, e.g., \fBML\-DSA\-65\fR key, in FIPS 204 \fBsk\fR format, you can run:
286 .PP
287 .Vb 2
288 \& $ openssl genpkey \-provparam ml\-dsa.retain_seed=no \e
289 \& \-algorithm ml\-dsa\-65 \-out priv\-only.pem
290 .Ve
291 .PP
292 If you have a \fBPKCS#8\fR file with both a seed and a key, and prefer to import the
293 companion key rather than the seed, you can run:
294 .PP
295 .Vb 2
296 \& $ openssl pkey \-provparam ml\-dsa.prefer_seed=no \e
297 \& \-in seed\-priv.pem \-out priv\-only.pem
298 .Ve
299 .PP
300 In the \fBopenssl.cnf\fR file, this looks like:
301 .PP
302 .Vb 1
303 \& openssl_conf = openssl_init
304 \&
305 \& [openssl_init]
306 \& providers = providers_sect
307 \&
308 \& # Can be referenced in one or more provider sections
309 \& [ml_dsa_sect]
310 \& prefer_seed = yes
311 \& retain_seed = yes
312 \& # OQS legacy formats disabled
313 \& input_formats = seed\-priv, seed\-only, priv\-only
314 \& # Output either the seed alone, or else the key alone
315 \& output_formats = seed\-only, priv\-only
316 \&
317 \& [providers_sect]
318 \& default = default_sect
319 \& # Or perhaps just: base = default_sect
320 \& base = base_sect
321 \&
322 \& [default_sect]
323 \& ml\-dsa = ml_dsa_sect
324 \&
325 \& [base_sect]
326 \& ml\-dsa = ml_dsa_sect
327 .Ve
328 .SH "SEE ALSO"
329 .IX Header "SEE ALSO"
330 \&\fBEVP_KEYMGMT\fR\|(3),
331 \&\fBEVP_PKEY\fR\|(3),
332 \&\fBprovider\-keymgmt\fR\|(7),
333 \&\fBEVP_PKEY_get_raw_private_key\fR\|(3),
334 \&\fBEVP_PKEY_get_raw_public_key\fR\|(3),
335 \&\fBEVP_PKEY_get1_encoded_public_key\fR\|(3),
336 \&\fBOSSL_PROVIDER_add_conf_parameter\fR\|(3),
337 \&\fBprovider\-keymgmt\fR\|(7),
338 \&\fBEVP_SIGNATURE\-ML\-DSA\fR\|(7)
339 .SH HISTORY
340 .IX Header "HISTORY"
341 This functionality was added in OpenSSL 3.5.
342 .SH COPYRIGHT
343 .IX Header "COPYRIGHT"
344 Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.
345 .PP
346 Licensed under the Apache License 2.0 (the "License"). You may not use
347 this file except in compliance with the License. You can obtain a copy
348 in the file LICENSE in the source distribution or at
349 <https://www.openssl.org/source/license.html>.