diff options
Diffstat (limited to 'src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3')
-rw-r--r-- | src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 | 582 |
1 files changed, 0 insertions, 582 deletions
diff --git a/src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 b/src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 deleted file mode 100644 index 137e576c46..0000000000 --- a/src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 +++ /dev/null | |||
@@ -1,582 +0,0 @@ | |||
1 | .\" $OpenBSD: EVP_PKEY_CTX_ctrl.3,v 1.28 2024/12/10 14:54:20 schwarze Exp $ | ||
2 | .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 | ||
3 | .\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 | ||
4 | .\" Parts were split out into RSA_pkey_ctx_ctrl(3). | ||
5 | .\" | ||
6 | .\" This file is a derived work. | ||
7 | .\" The changes are covered by the following Copyright and license: | ||
8 | .\" | ||
9 | .\" Copyright (c) 2019, 2023, 2024 Ingo Schwarze <schwarze@openbsd.org> | ||
10 | .\" | ||
11 | .\" Permission to use, copy, modify, and distribute this software for any | ||
12 | .\" purpose with or without fee is hereby granted, provided that the above | ||
13 | .\" copyright notice and this permission notice appear in all copies. | ||
14 | .\" | ||
15 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | ||
16 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | ||
17 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | ||
18 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | ||
19 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | ||
20 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | ||
21 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | ||
22 | .\" | ||
23 | .\" The original file was written by Dr. Stephen Henson <steve@openssl.org> | ||
24 | .\" and Antoine Salon <asalon@vmware.com>. | ||
25 | .\" Copyright (c) 2006, 2009, 2013, 2014, 2015, 2018 The OpenSSL Project. | ||
26 | .\" All rights reserved. | ||
27 | .\" | ||
28 | .\" Redistribution and use in source and binary forms, with or without | ||
29 | .\" modification, are permitted provided that the following conditions | ||
30 | .\" are met: | ||
31 | .\" | ||
32 | .\" 1. Redistributions of source code must retain the above copyright | ||
33 | .\" notice, this list of conditions and the following disclaimer. | ||
34 | .\" | ||
35 | .\" 2. Redistributions in binary form must reproduce the above copyright | ||
36 | .\" notice, this list of conditions and the following disclaimer in | ||
37 | .\" the documentation and/or other materials provided with the | ||
38 | .\" distribution. | ||
39 | .\" | ||
40 | .\" 3. All advertising materials mentioning features or use of this | ||
41 | .\" software must display the following acknowledgment: | ||
42 | .\" "This product includes software developed by the OpenSSL Project | ||
43 | .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" | ||
44 | .\" | ||
45 | .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to | ||
46 | .\" endorse or promote products derived from this software without | ||
47 | .\" prior written permission. For written permission, please contact | ||
48 | .\" openssl-core@openssl.org. | ||
49 | .\" | ||
50 | .\" 5. Products derived from this software may not be called "OpenSSL" | ||
51 | .\" nor may "OpenSSL" appear in their names without prior written | ||
52 | .\" permission of the OpenSSL Project. | ||
53 | .\" | ||
54 | .\" 6. Redistributions of any form whatsoever must retain the following | ||
55 | .\" acknowledgment: | ||
56 | .\" "This product includes software developed by the OpenSSL Project | ||
57 | .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" | ||
58 | .\" | ||
59 | .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY | ||
60 | .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||
61 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR | ||
62 | .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR | ||
63 | .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | ||
64 | .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT | ||
65 | .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; | ||
66 | .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||
67 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, | ||
68 | .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | ||
69 | .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED | ||
70 | .\" OF THE POSSIBILITY OF SUCH DAMAGE. | ||
71 | .\" | ||
72 | .Dd $Mdocdate: December 10 2024 $ | ||
73 | .Dt EVP_PKEY_CTX_CTRL 3 | ||
74 | .Os | ||
75 | .Sh NAME | ||
76 | .Nm EVP_PKEY_CTX_ctrl , | ||
77 | .Nm EVP_PKEY_CTX_ctrl_str , | ||
78 | .Nm EVP_PKEY_CTX_set_signature_md , | ||
79 | .Nm EVP_PKEY_CTX_get_signature_md , | ||
80 | .Nm EVP_PKEY_CTX_set_dsa_paramgen_bits , | ||
81 | .Nm EVP_PKEY_CTX_set_dh_paramgen_prime_len , | ||
82 | .Nm EVP_PKEY_CTX_set_dh_paramgen_generator , | ||
83 | .Nm EVP_PKEY_CTX_set_ec_paramgen_curve_nid , | ||
84 | .Nm EVP_PKEY_CTX_set_ec_param_enc , | ||
85 | .Nm EVP_PKEY_CTX_set_ecdh_cofactor_mode , | ||
86 | .Nm EVP_PKEY_CTX_get_ecdh_cofactor_mode , | ||
87 | .Nm EVP_PKEY_CTX_set_ecdh_kdf_type , | ||
88 | .Nm EVP_PKEY_CTX_get_ecdh_kdf_type , | ||
89 | .Nm EVP_PKEY_CTX_set_ecdh_kdf_md , | ||
90 | .Nm EVP_PKEY_CTX_get_ecdh_kdf_md , | ||
91 | .Nm EVP_PKEY_CTX_set_ecdh_kdf_outlen , | ||
92 | .Nm EVP_PKEY_CTX_get_ecdh_kdf_outlen , | ||
93 | .Nm EVP_PKEY_CTX_set0_ecdh_kdf_ukm , | ||
94 | .Nm EVP_PKEY_CTX_get0_ecdh_kdf_ukm , | ||
95 | .Nm EVP_PKEY_CTX_set1_id , | ||
96 | .Nm EVP_PKEY_CTX_get1_id , | ||
97 | .Nm EVP_PKEY_CTX_get1_id_len | ||
98 | .Nd algorithm specific control operations | ||
99 | .Sh SYNOPSIS | ||
100 | .In openssl/evp.h | ||
101 | .Ft int | ||
102 | .Fo EVP_PKEY_CTX_ctrl | ||
103 | .Fa "EVP_PKEY_CTX *ctx" | ||
104 | .Fa "int keytype" | ||
105 | .Fa "int optype" | ||
106 | .Fa "int cmd" | ||
107 | .Fa "int p1" | ||
108 | .Fa "void *p2" | ||
109 | .Fc | ||
110 | .Ft int | ||
111 | .Fo EVP_PKEY_CTX_ctrl_str | ||
112 | .Fa "EVP_PKEY_CTX *ctx" | ||
113 | .Fa "const char *type" | ||
114 | .Fa "const char *value" | ||
115 | .Fc | ||
116 | .Ft int | ||
117 | .Fo EVP_PKEY_CTX_set_signature_md | ||
118 | .Fa "EVP_PKEY_CTX *ctx" | ||
119 | .Fa "const EVP_MD *md" | ||
120 | .Fc | ||
121 | .Ft int | ||
122 | .Fo EVP_PKEY_CTX_get_signature_md | ||
123 | .Fa "EVP_PKEY_CTX *ctx" | ||
124 | .Fa "const EVP_MD **pmd" | ||
125 | .Fc | ||
126 | .In openssl/dsa.h | ||
127 | .Ft int | ||
128 | .Fo EVP_PKEY_CTX_set_dsa_paramgen_bits | ||
129 | .Fa "EVP_PKEY_CTX *ctx" | ||
130 | .Fa "int nbits" | ||
131 | .Fc | ||
132 | .In openssl/dh.h | ||
133 | .Ft int | ||
134 | .Fo EVP_PKEY_CTX_set_dh_paramgen_prime_len | ||
135 | .Fa "EVP_PKEY_CTX *ctx" | ||
136 | .Fa "int len" | ||
137 | .Fc | ||
138 | .Ft int | ||
139 | .Fo EVP_PKEY_CTX_set_dh_paramgen_generator | ||
140 | .Fa "EVP_PKEY_CTX *ctx" | ||
141 | .Fa "int gen" | ||
142 | .Fc | ||
143 | .In openssl/ec.h | ||
144 | .Ft int | ||
145 | .Fo EVP_PKEY_CTX_set_ec_paramgen_curve_nid | ||
146 | .Fa "EVP_PKEY_CTX *ctx" | ||
147 | .Fa "int nid" | ||
148 | .Fc | ||
149 | .Fa int | ||
150 | .Fo EVP_PKEY_CTX_set_ec_param_enc | ||
151 | .Fa "EVP_PKEY_CTX *ctx" | ||
152 | .Fa "int param_enc" | ||
153 | .Fc | ||
154 | .Ft int | ||
155 | .Fo EVP_PKEY_CTX_set_ecdh_cofactor_mode | ||
156 | .Fa "EVP_PKEY_CTX *ctx" | ||
157 | .Fa "int cofactor_mode" | ||
158 | .Fc | ||
159 | .Ft int | ||
160 | .Fo EVP_PKEY_CTX_get_ecdh_cofactor_mode | ||
161 | .Fa "EVP_PKEY_CTX *ctx" | ||
162 | .Fc | ||
163 | .Ft int | ||
164 | .Fo EVP_PKEY_CTX_set_ecdh_kdf_type | ||
165 | .Fa "EVP_PKEY_CTX *ctx" | ||
166 | .Fa "int kdf" | ||
167 | .Fc | ||
168 | .Ft int | ||
169 | .Fo EVP_PKEY_CTX_get_ecdh_kdf_type | ||
170 | .Fa "EVP_PKEY_CTX *ctx" | ||
171 | .Fc | ||
172 | .Ft int | ||
173 | .Fo EVP_PKEY_CTX_set_ecdh_kdf_md | ||
174 | .Fa "EVP_PKEY_CTX *ctx" | ||
175 | .Fa "const EVP_MD *md" | ||
176 | .Fc | ||
177 | .Ft int | ||
178 | .Fo EVP_PKEY_CTX_get_ecdh_kdf_md | ||
179 | .Fa "EVP_PKEY_CTX *ctx" | ||
180 | .Fa "const EVP_MD **pmd" | ||
181 | .Fc | ||
182 | .Ft int | ||
183 | .Fo EVP_PKEY_CTX_set_ecdh_kdf_outlen | ||
184 | .Fa "EVP_PKEY_CTX *ctx" | ||
185 | .Fa "int len" | ||
186 | .Fc | ||
187 | .Ft int | ||
188 | .Fo EVP_PKEY_CTX_get_ecdh_kdf_outlen | ||
189 | .Fa "EVP_PKEY_CTX *ctx" | ||
190 | .Fa "int *plen" | ||
191 | .Fc | ||
192 | .Ft int | ||
193 | .Fo EVP_PKEY_CTX_set0_ecdh_kdf_ukm | ||
194 | .Fa "EVP_PKEY_CTX *ctx" | ||
195 | .Fa "unsigned char *ukm" | ||
196 | .Fa "int len" | ||
197 | .Fc | ||
198 | .Ft int | ||
199 | .Fo EVP_PKEY_CTX_get0_ecdh_kdf_ukm | ||
200 | .Fa "EVP_PKEY_CTX *ctx" | ||
201 | .Fa "unsigned char **pukm" | ||
202 | .Fc | ||
203 | .Ft int | ||
204 | .Fo EVP_PKEY_CTX_set1_id | ||
205 | .Fa "EVP_PKEY_CTX *ctx" | ||
206 | .Fa "void *id" | ||
207 | .Fa "size_t id_len" | ||
208 | .Fc | ||
209 | .Ft int | ||
210 | .Fo EVP_PKEY_CTX_get1_id | ||
211 | .Fa "EVP_PKEY_CTX *ctx" | ||
212 | .Fa "void *id" | ||
213 | .Fc | ||
214 | .Ft int | ||
215 | .Fo EVP_PKEY_CTX_get1_id_len | ||
216 | .Fa "EVP_PKEY_CTX *ctx" | ||
217 | .Fa "size_t *pid_len" | ||
218 | .Fc | ||
219 | .Sh DESCRIPTION | ||
220 | The function | ||
221 | .Fn EVP_PKEY_CTX_ctrl | ||
222 | sends a control operation to the context | ||
223 | .Fa ctx . | ||
224 | The key type used must match | ||
225 | .Fa keytype | ||
226 | if it is not -1. | ||
227 | The parameter | ||
228 | .Fa optype | ||
229 | is a mask indicating which operations the control can be applied to. | ||
230 | The control command is indicated in | ||
231 | .Fa cmd | ||
232 | and any additional arguments in | ||
233 | .Fa p1 | ||
234 | and | ||
235 | .Fa p2 . | ||
236 | .Pp | ||
237 | Applications will not normally call | ||
238 | .Fn EVP_PKEY_CTX_ctrl | ||
239 | directly but will instead call one of the algorithm specific macros | ||
240 | described below and in | ||
241 | .Xr RSA_pkey_ctx_ctrl 3 . | ||
242 | .Pp | ||
243 | The function | ||
244 | .Fn EVP_PKEY_CTX_ctrl_str | ||
245 | allows an application to send an algorithm specific control operation to | ||
246 | a context | ||
247 | .Fa ctx | ||
248 | in string form. | ||
249 | This is intended to be used for options specified on the command line or | ||
250 | in text files. | ||
251 | The commands supported are documented in the | ||
252 | .Xr openssl 1 | ||
253 | utility command line pages for the option | ||
254 | .Fl pkeyopt | ||
255 | which is supported by the | ||
256 | .Cm pkeyutl , | ||
257 | .Cm genpkey , | ||
258 | and | ||
259 | .Cm req | ||
260 | commands. | ||
261 | .Pp | ||
262 | All the remaining "functions" are implemented as macros. | ||
263 | .Pp | ||
264 | The | ||
265 | .Fn EVP_PKEY_CTX_set_signature_md | ||
266 | and | ||
267 | .Fn EVP_PKEY_CTX_get_signature_md | ||
268 | macros set and get the message digest type used in a signature. | ||
269 | They can be used with the RSA, DSA, and ECDSA algorithms. | ||
270 | If the key is of the type | ||
271 | .Dv EVP_PKEY_RSA_PSS | ||
272 | and has usage restrictions, an error occurs if an attempt is made | ||
273 | to set the digest to anything other than the restricted value. | ||
274 | .Pp | ||
275 | These two macros expand to | ||
276 | .Fn EVP_PKEY_CTX_ctrl | ||
277 | with an | ||
278 | .Fa optype | ||
279 | of | ||
280 | .Dv EVP_PKEY_OP_TYPE_SIG | ||
281 | and the following command arguments: | ||
282 | .Pp | ||
283 | .Bl -column -compact EVP_PKEY_CTRL_GET_MD EVP_PKEY_CTX_get_signature_md() | ||
284 | .It Fa cmd No constant Ta corresponding macro | ||
285 | .It Dv EVP_PKEY_CTRL_MD Ta Fn EVP_PKEY_CTX_set_signature_md | ||
286 | .It Dv EVP_PKEY_CTRL_GET_MD Ta Fn EVP_PKEY_CTX_get_signature_md | ||
287 | .El | ||
288 | .Ss DSA parameters | ||
289 | The macro | ||
290 | .Fn EVP_PKEY_CTX_set_dsa_paramgen_bits | ||
291 | sets the number of bits used for DSA parameter generation to | ||
292 | .Fa nbits . | ||
293 | If not specified, 1024 is used. | ||
294 | .Ss DH parameters | ||
295 | The macro | ||
296 | .Fn EVP_PKEY_CTX_set_dh_paramgen_prime_len | ||
297 | sets the length of the DH prime parameter | ||
298 | .Fa len | ||
299 | for DH parameter generation. | ||
300 | It only accepts lengths greater than or equal to 256. | ||
301 | If this macro is not called, then 1024 is used. | ||
302 | .Pp | ||
303 | The | ||
304 | .Fn EVP_PKEY_CTX_set_dh_paramgen_generator | ||
305 | macro sets DH generator to | ||
306 | .Fa gen | ||
307 | for DH parameter generation. | ||
308 | If not specified, 2 is used. | ||
309 | .Ss EC parameters | ||
310 | The | ||
311 | .Fn EVP_PKEY_CTX_set_ec_paramgen_curve_nid | ||
312 | macro sets the EC curve for EC parameter generation to | ||
313 | .Fa nid . | ||
314 | For EC parameter generation, this macro must be called or an error occurs | ||
315 | because there is no default curve. | ||
316 | .Pp | ||
317 | The | ||
318 | .Fn EVP_PKEY_CTX_set_ec_param_enc | ||
319 | macro sets the EC parameter encoding to | ||
320 | .Fa param_enc | ||
321 | when generating EC parameters or an EC key. | ||
322 | The encoding can be set to 0 for explicit parameters or to | ||
323 | .Dv OPENSSL_EC_NAMED_CURVE | ||
324 | to use named curve form. | ||
325 | .Ss ECDH parameters | ||
326 | The | ||
327 | .Fn EVP_PKEY_CTX_set_ecdh_cofactor_mode | ||
328 | macro sets the cofactor mode to | ||
329 | .Fa cofactor_mode | ||
330 | for ECDH key derivation. | ||
331 | Possible values are 1 to enable cofactor key derivation, 0 to disable | ||
332 | it, or -1 to clear the stored cofactor mode and fall back to the | ||
333 | private key cofactor mode. | ||
334 | .Pp | ||
335 | The | ||
336 | .Fn EVP_PKEY_CTX_get_ecdh_cofactor_mode | ||
337 | macro returns the cofactor mode for | ||
338 | .Fa ctx | ||
339 | used for ECDH key derivation. | ||
340 | Possible return values are 1 when cofactor key derivation is enabled | ||
341 | or 0 otherwise. | ||
342 | .Ss ECDH key derivation function parameters | ||
343 | The | ||
344 | .Fn EVP_PKEY_CTX_set_ecdh_kdf_type | ||
345 | macro sets the key derivation function type to | ||
346 | .Fa kdf | ||
347 | for ECDH key derivation. | ||
348 | Possible values are | ||
349 | .Dv EVP_PKEY_ECDH_KDF_NONE | ||
350 | or | ||
351 | .Dv EVP_PKEY_ECDH_KDF_X9_63 | ||
352 | which uses the key derivation specified in X9.63. | ||
353 | When using key derivation, the | ||
354 | .Fa kdf_md | ||
355 | and | ||
356 | .Fa kdf_outlen | ||
357 | parameters must also be specified. | ||
358 | .Pp | ||
359 | The | ||
360 | .Fn EVP_PKEY_CTX_get_ecdh_kdf_type | ||
361 | macro returns the key derivation function type for | ||
362 | .Fa ctx | ||
363 | used for ECDH key derivation. | ||
364 | Possible return values are | ||
365 | .Dv EVP_PKEY_ECDH_KDF_NONE | ||
366 | or | ||
367 | .Dv EVP_PKEY_ECDH_KDF_X9_63 . | ||
368 | .Pp | ||
369 | The | ||
370 | .Fn EVP_PKEY_CTX_set_ecdh_kdf_md | ||
371 | macro sets the key derivation function message digest to | ||
372 | .Fa md | ||
373 | for ECDH key derivation. | ||
374 | Note that X9.63 specifies that this digest should be SHA1, | ||
375 | but OpenSSL tolerates other digests. | ||
376 | .Pp | ||
377 | The | ||
378 | .Fn EVP_PKEY_CTX_get_ecdh_kdf_md | ||
379 | macro gets the key derivation function message digest for | ||
380 | .Fa ctx | ||
381 | used for ECDH key derivation. | ||
382 | .Pp | ||
383 | The | ||
384 | .Fn EVP_PKEY_CTX_set_ecdh_kdf_outlen | ||
385 | macro sets the key derivation function output length to | ||
386 | .Fa len | ||
387 | for ECDH key derivation. | ||
388 | .Pp | ||
389 | The | ||
390 | .Fn EVP_PKEY_CTX_get_ecdh_kdf_outlen | ||
391 | macro gets the key derivation function output length for | ||
392 | .Fa ctx | ||
393 | used for ECDH key derivation. | ||
394 | .Pp | ||
395 | The | ||
396 | .Fn EVP_PKEY_CTX_set0_ecdh_kdf_ukm | ||
397 | macro sets the user key material to | ||
398 | .Fa ukm | ||
399 | for ECDH key derivation. | ||
400 | This parameter is optional and corresponds to the shared info | ||
401 | in X9.63 terms. | ||
402 | The library takes ownership of the user key material, so the caller | ||
403 | should not free the original memory pointed to by | ||
404 | .Fa ukm . | ||
405 | .Pp | ||
406 | The | ||
407 | .Fn EVP_PKEY_CTX_get0_ecdh_kdf_ukm | ||
408 | macro gets the user key material for | ||
409 | .Fa ctx . | ||
410 | The return value is the user key material length. | ||
411 | The resulting pointer is owned by the library and should not be | ||
412 | freed by the caller. | ||
413 | .Ss CMAC parameters | ||
414 | Application programs normally implement CMAC as described in | ||
415 | .Xr EVP_PKEY_new_CMAC_key 3 | ||
416 | and do not need the control commands documented here. | ||
417 | .Pp | ||
418 | Alternatively, the call to | ||
419 | .Xr EVP_PKEY_new_CMAC_key 3 | ||
420 | can be replaced as follows, | ||
421 | leaving the rest of the example code given there unchanged: | ||
422 | .Pp | ||
423 | .Bl -enum -width 2n -compact | ||
424 | .It | ||
425 | Create an empty | ||
426 | .Vt EVP_PKEY_CTX | ||
427 | object by passing the | ||
428 | .Dv EVP_PKEY_CMAC | ||
429 | constant to | ||
430 | .Xr EVP_PKEY_CTX_new_id 3 . | ||
431 | .It | ||
432 | Initialize it with | ||
433 | .Xr EVP_PKEY_keygen_init 3 . | ||
434 | .It | ||
435 | Select the block cipher by calling | ||
436 | .Fn EVP_PKEY_CTX_ctrl | ||
437 | with an | ||
438 | .Fa optype | ||
439 | of | ||
440 | .Dv EVP_PKEY_OP_KEYGEN , | ||
441 | a | ||
442 | .Fa cmd | ||
443 | of | ||
444 | .Dv EVP_PKEY_CTRL_CIPHER , | ||
445 | and | ||
446 | .Fa p2 | ||
447 | pointing to an | ||
448 | .Vt EVP_CIPHER | ||
449 | object, which can be obtained from the functions in the CIPHER LISTING in | ||
450 | .Xr EVP_EncryptInit 3 . | ||
451 | The | ||
452 | .Fa p1 | ||
453 | argument is ignored; passing 0 is recommended. | ||
454 | .It | ||
455 | Call | ||
456 | .Fn EVP_PKEY_CTX_ctrl | ||
457 | again with an | ||
458 | .Fa optype | ||
459 | of | ||
460 | .Dv EVP_PKEY_OP_KEYGEN , | ||
461 | a | ||
462 | .Fa cmd | ||
463 | of | ||
464 | .Dv EVP_PKEY_CTRL_SET_MAC_KEY , | ||
465 | .Fa p2 | ||
466 | pointing to the symmetric key, and | ||
467 | .Fa p1 | ||
468 | specifying the length of the symmetric key in bytes. | ||
469 | .It | ||
470 | Extract the desired | ||
471 | .Vt EVP_PKEY | ||
472 | object using | ||
473 | .Xr EVP_PKEY_keygen 3 , | ||
474 | making sure the | ||
475 | .Fa ppkey | ||
476 | argument points to a storage location containing a | ||
477 | .Dv NULL | ||
478 | pointer. | ||
479 | .It | ||
480 | Proceed with | ||
481 | .Xr EVP_MD_CTX_new 3 , | ||
482 | .Xr EVP_DigestSignInit 3 , | ||
483 | and | ||
484 | .Xr EVP_DigestSign 3 | ||
485 | as usual. | ||
486 | .El | ||
487 | .Ss HMAC parameters | ||
488 | Application programs normally implement HMAC as described in | ||
489 | .Xr EVP_PKEY_new_raw_private_key 3 . | ||
490 | While it is possible to instead use | ||
491 | .Dv EVP_PKEY_CTRL_SET_MAC_KEY | ||
492 | directly, similar to the above description for CMAC, | ||
493 | that is strongly discouraged. | ||
494 | It's essentially what the deprecated function | ||
495 | .Xr EVP_PKEY_new_mac_key 3 | ||
496 | does internally, and compared to the direct approach with | ||
497 | .Xr EVP_PKEY_new_raw_private_key 3 , | ||
498 | it requires a lot of cumbersome and unnecessary work. | ||
499 | .Ss Other parameters | ||
500 | The | ||
501 | .Fn EVP_PKEY_CTX_set1_id , | ||
502 | .Fn EVP_PKEY_CTX_get1_id , | ||
503 | and | ||
504 | .Fn EVP_PKEY_CTX_get1_id_len | ||
505 | macros manipulate a special identifier field used for some specific | ||
506 | signature algorithms such as SM2. | ||
507 | The | ||
508 | .Fn EVP_PKEY_set1_id | ||
509 | macro sets the ID to a copy of | ||
510 | .Fa id | ||
511 | with the length | ||
512 | .Fa id_len . | ||
513 | The caller can safely free the original memory pointed to by | ||
514 | .Fa id . | ||
515 | The | ||
516 | .Fn EVP_PKEY_CTX_get1_id_len | ||
517 | macro returns the length of the ID set via a previous call to | ||
518 | .Fn EVP_PKEY_set1_id . | ||
519 | That length is typically used to allocate memory for a subsequent call to | ||
520 | .Fn EVP_PKEY_CTX_get1_id , | ||
521 | which copies the previously set ID into | ||
522 | .Pf * Fa id . | ||
523 | The caller is responsible for allocating sufficient memory for | ||
524 | .Fa id | ||
525 | before calling | ||
526 | .Fn EVP_PKEY_CTX_get1_id . | ||
527 | .Sh RETURN VALUES | ||
528 | .Fn EVP_PKEY_CTX_ctrl | ||
529 | and its macros return a positive value for success and 0 or a negative | ||
530 | value for failure. | ||
531 | In particular, a return value of -2 indicates the operation is not | ||
532 | supported by the public key algorithm. | ||
533 | .Sh SEE ALSO | ||
534 | .Xr DH_new 3 , | ||
535 | .Xr EVP_DigestInit 3 , | ||
536 | .Xr EVP_PKEY_CTX_new 3 , | ||
537 | .Xr EVP_PKEY_decrypt 3 , | ||
538 | .Xr EVP_PKEY_derive 3 , | ||
539 | .Xr EVP_PKEY_encrypt 3 , | ||
540 | .Xr EVP_PKEY_get_default_digest_nid 3 , | ||
541 | .Xr EVP_PKEY_keygen 3 , | ||
542 | .Xr EVP_PKEY_sign 3 , | ||
543 | .Xr EVP_PKEY_verify 3 , | ||
544 | .Xr EVP_PKEY_verify_recover 3 , | ||
545 | .Xr RSA_pkey_ctx_ctrl 3 | ||
546 | .Sh HISTORY | ||
547 | The functions | ||
548 | .Fn EVP_PKEY_CTX_ctrl , | ||
549 | .Fn EVP_PKEY_CTX_ctrl_str , | ||
550 | .Fn EVP_PKEY_CTX_set_signature_md , | ||
551 | .Fn EVP_PKEY_CTX_set_dsa_paramgen_bits , | ||
552 | .Fn EVP_PKEY_CTX_set_dh_paramgen_prime_len , | ||
553 | .Fn EVP_PKEY_CTX_set_dh_paramgen_generator , | ||
554 | and | ||
555 | .Fn EVP_PKEY_CTX_set_ec_paramgen_curve_nid | ||
556 | first appeared in OpenSSL 1.0.0 and have been available since | ||
557 | .Ox 4.9 . | ||
558 | .Pp | ||
559 | The functions | ||
560 | .Fn EVP_PKEY_CTX_get_signature_md , | ||
561 | .Fn EVP_PKEY_CTX_set_ec_param_enc , | ||
562 | .Fn EVP_PKEY_CTX_set_ecdh_cofactor_mode , | ||
563 | .Fn EVP_PKEY_CTX_get_ecdh_cofactor_mode , | ||
564 | .Fn EVP_PKEY_CTX_set_ecdh_kdf_type , | ||
565 | .Fn EVP_PKEY_CTX_get_ecdh_kdf_type , | ||
566 | .Fn EVP_PKEY_CTX_set_ecdh_kdf_md , | ||
567 | .Fn EVP_PKEY_CTX_get_ecdh_kdf_md , | ||
568 | .Fn EVP_PKEY_CTX_set_ecdh_kdf_outlen , | ||
569 | .Fn EVP_PKEY_CTX_get_ecdh_kdf_outlen , | ||
570 | .Fn EVP_PKEY_CTX_set0_ecdh_kdf_ukm , | ||
571 | and | ||
572 | .Fn EVP_PKEY_CTX_get0_ecdh_kdf_ukm | ||
573 | first appeared in OpenSSL 1.0.2 and have been available since | ||
574 | .Ox 6.6 . | ||
575 | .Pp | ||
576 | The functions | ||
577 | .Fn EVP_PKEY_CTX_set1_id , | ||
578 | .Fn EVP_PKEY_CTX_get1_id , | ||
579 | and | ||
580 | .Fn EVP_PKEY_CTX_get1_id_len | ||
581 | first appeared in OpenSSL 1.1.1 and have been available since | ||
582 | .Ox 6.6 . | ||