summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3')
-rw-r--r--src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3466
1 files changed, 0 insertions, 466 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 7714cb0558..0000000000
--- a/src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3
+++ /dev/null
@@ -1,466 +0,0 @@
1.\" $OpenBSD: EVP_PKEY_CTX_ctrl.3,v 1.22 2019/11/01 13:53:25 schwarze Exp $
2.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
3.\" selective merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100
4.\" Parts were split out into RSA_pkey_ctx_ctrl(3).
5.\"
6.\" This file was written by Dr. Stephen Henson <steve@openssl.org>
7.\" and Antoine Salon <asalon@vmware.com>.
8.\" Copyright (c) 2006, 2009, 2013, 2014, 2015, 2018 The OpenSSL Project.
9.\" All rights reserved.
10.\"
11.\" Redistribution and use in source and binary forms, with or without
12.\" modification, are permitted provided that the following conditions
13.\" are met:
14.\"
15.\" 1. Redistributions of source code must retain the above copyright
16.\" notice, this list of conditions and the following disclaimer.
17.\"
18.\" 2. Redistributions in binary form must reproduce the above copyright
19.\" notice, this list of conditions and the following disclaimer in
20.\" the documentation and/or other materials provided with the
21.\" distribution.
22.\"
23.\" 3. All advertising materials mentioning features or use of this
24.\" software must display the following acknowledgment:
25.\" "This product includes software developed by the OpenSSL Project
26.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
27.\"
28.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
29.\" endorse or promote products derived from this software without
30.\" prior written permission. For written permission, please contact
31.\" openssl-core@openssl.org.
32.\"
33.\" 5. Products derived from this software may not be called "OpenSSL"
34.\" nor may "OpenSSL" appear in their names without prior written
35.\" permission of the OpenSSL Project.
36.\"
37.\" 6. Redistributions of any form whatsoever must retain the following
38.\" acknowledgment:
39.\" "This product includes software developed by the OpenSSL Project
40.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
41.\"
42.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
43.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
44.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
45.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
46.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
47.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
48.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
49.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
50.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
51.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
52.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
53.\" OF THE POSSIBILITY OF SUCH DAMAGE.
54.\"
55.Dd $Mdocdate: November 1 2019 $
56.Dt EVP_PKEY_CTX_CTRL 3
57.Os
58.Sh NAME
59.Nm EVP_PKEY_CTX_ctrl ,
60.Nm EVP_PKEY_CTX_ctrl_str ,
61.Nm EVP_PKEY_CTX_set_signature_md ,
62.Nm EVP_PKEY_CTX_get_signature_md ,
63.Nm EVP_PKEY_CTX_set_dsa_paramgen_bits ,
64.Nm EVP_PKEY_CTX_set_dh_paramgen_prime_len ,
65.Nm EVP_PKEY_CTX_set_dh_paramgen_generator ,
66.Nm EVP_PKEY_CTX_set_ec_paramgen_curve_nid ,
67.Nm EVP_PKEY_CTX_set_ec_param_enc ,
68.Nm EVP_PKEY_CTX_set_ecdh_cofactor_mode ,
69.Nm EVP_PKEY_CTX_get_ecdh_cofactor_mode ,
70.Nm EVP_PKEY_CTX_set_ecdh_kdf_type ,
71.Nm EVP_PKEY_CTX_get_ecdh_kdf_type ,
72.Nm EVP_PKEY_CTX_set_ecdh_kdf_md ,
73.Nm EVP_PKEY_CTX_get_ecdh_kdf_md ,
74.Nm EVP_PKEY_CTX_set_ecdh_kdf_outlen ,
75.Nm EVP_PKEY_CTX_get_ecdh_kdf_outlen ,
76.Nm EVP_PKEY_CTX_set0_ecdh_kdf_ukm ,
77.Nm EVP_PKEY_CTX_get0_ecdh_kdf_ukm ,
78.Nm EVP_PKEY_CTX_set1_id ,
79.Nm EVP_PKEY_CTX_get1_id ,
80.Nm EVP_PKEY_CTX_get1_id_len
81.Nd algorithm specific control operations
82.Sh SYNOPSIS
83.In openssl/evp.h
84.Ft int
85.Fo EVP_PKEY_CTX_ctrl
86.Fa "EVP_PKEY_CTX *ctx"
87.Fa "int keytype"
88.Fa "int optype"
89.Fa "int cmd"
90.Fa "int p1"
91.Fa "void *p2"
92.Fc
93.Ft int
94.Fo EVP_PKEY_CTX_ctrl_str
95.Fa "EVP_PKEY_CTX *ctx"
96.Fa "const char *type"
97.Fa "const char *value"
98.Fc
99.Ft int
100.Fo EVP_PKEY_CTX_set_signature_md
101.Fa "EVP_PKEY_CTX *ctx"
102.Fa "const EVP_MD *md"
103.Fc
104.Ft int
105.Fo EVP_PKEY_CTX_get_signature_md
106.Fa "EVP_PKEY_CTX *ctx"
107.Fa "const EVP_MD **pmd"
108.Fc
109.In openssl/dsa.h
110.Ft int
111.Fo EVP_PKEY_CTX_set_dsa_paramgen_bits
112.Fa "EVP_PKEY_CTX *ctx"
113.Fa "int nbits"
114.Fc
115.In openssl/dh.h
116.Ft int
117.Fo EVP_PKEY_CTX_set_dh_paramgen_prime_len
118.Fa "EVP_PKEY_CTX *ctx"
119.Fa "int len"
120.Fc
121.Ft int
122.Fo EVP_PKEY_CTX_set_dh_paramgen_generator
123.Fa "EVP_PKEY_CTX *ctx"
124.Fa "int gen"
125.Fc
126.In openssl/ec.h
127.Ft int
128.Fo EVP_PKEY_CTX_set_ec_paramgen_curve_nid
129.Fa "EVP_PKEY_CTX *ctx"
130.Fa "int nid"
131.Fc
132.Fa int
133.Fo EVP_PKEY_CTX_set_ec_param_enc
134.Fa "EVP_PKEY_CTX *ctx"
135.Fa "int param_enc"
136.Fc
137.Ft int
138.Fo EVP_PKEY_CTX_set_ecdh_cofactor_mode
139.Fa "EVP_PKEY_CTX *ctx"
140.Fa "int cofactor_mode"
141.Fc
142.Ft int
143.Fo EVP_PKEY_CTX_get_ecdh_cofactor_mode
144.Fa "EVP_PKEY_CTX *ctx"
145.Fc
146.Ft int
147.Fo EVP_PKEY_CTX_set_ecdh_kdf_type
148.Fa "EVP_PKEY_CTX *ctx"
149.Fa "int kdf"
150.Fc
151.Ft int
152.Fo EVP_PKEY_CTX_get_ecdh_kdf_type
153.Fa "EVP_PKEY_CTX *ctx"
154.Fc
155.Ft int
156.Fo EVP_PKEY_CTX_set_ecdh_kdf_md
157.Fa "EVP_PKEY_CTX *ctx"
158.Fa "const EVP_MD *md"
159.Fc
160.Ft int
161.Fo EVP_PKEY_CTX_get_ecdh_kdf_md
162.Fa "EVP_PKEY_CTX *ctx"
163.Fa "const EVP_MD **pmd"
164.Fc
165.Ft int
166.Fo EVP_PKEY_CTX_set_ecdh_kdf_outlen
167.Fa "EVP_PKEY_CTX *ctx"
168.Fa "int len"
169.Fc
170.Ft int
171.Fo EVP_PKEY_CTX_get_ecdh_kdf_outlen
172.Fa "EVP_PKEY_CTX *ctx"
173.Fa "int *plen"
174.Fc
175.Ft int
176.Fo EVP_PKEY_CTX_set0_ecdh_kdf_ukm
177.Fa "EVP_PKEY_CTX *ctx"
178.Fa "unsigned char *ukm"
179.Fa "int len"
180.Fc
181.Ft int
182.Fo EVP_PKEY_CTX_get0_ecdh_kdf_ukm
183.Fa "EVP_PKEY_CTX *ctx"
184.Fa "unsigned char **pukm"
185.Fc
186.Ft int
187.Fo EVP_PKEY_CTX_set1_id
188.Fa "EVP_PKEY_CTX *ctx"
189.Fa "void *id"
190.Fa "size_t id_len"
191.Fc
192.Ft int
193.Fo EVP_PKEY_CTX_get1_id
194.Fa "EVP_PKEY_CTX *ctx"
195.Fa "void *id"
196.Fc
197.Ft int
198.Fo EVP_PKEY_CTX_get1_id_len
199.Fa "EVP_PKEY_CTX *ctx"
200.Fa "size_t *pid_len"
201.Fc
202.Sh DESCRIPTION
203The function
204.Fn EVP_PKEY_CTX_ctrl
205sends a control operation to the context
206.Fa ctx .
207The key type used must match
208.Fa keytype
209if it is not -1.
210The parameter
211.Fa optype
212is a mask indicating which operations the control can be applied to.
213The control command is indicated in
214.Fa cmd
215and any additional arguments in
216.Fa p1
217and
218.Fa p2 .
219.Pp
220Applications will not normally call
221.Fn EVP_PKEY_CTX_ctrl
222directly but will instead call one of the algorithm specific macros
223described below and in
224.Xr RSA_pkey_ctx_ctrl 3 .
225.Pp
226The function
227.Fn EVP_PKEY_CTX_ctrl_str
228allows an application to send an algorithm specific control operation to
229a context
230.Fa ctx
231in string form.
232This is intended to be used for options specified on the command line or
233in text files.
234The commands supported are documented in the
235.Xr openssl 1
236utility command line pages for the option
237.Fl pkeyopt
238which is supported by the
239.Cm pkeyutl ,
240.Cm genpkey ,
241and
242.Cm req
243commands.
244.Pp
245All the remaining "functions" are implemented as macros.
246.Pp
247The
248.Fn EVP_PKEY_CTX_set_signature_md
249and
250.Fn EVP_PKEY_CTX_get_signature_md
251macros set and get the message digest type used in a signature.
252They can be used with the RSA, DSA, and ECDSA algorithms.
253If the key is of the type
254.Dv EVP_PKEY_RSA_PSS
255and has usage restrictions, an error occurs if an attempt is made
256to set the digest to anything other than the restricted value.
257.Ss DSA parameters
258The macro
259.Fn EVP_PKEY_CTX_set_dsa_paramgen_bits
260sets the number of bits used for DSA parameter generation to
261.Fa nbits .
262If not specified, 1024 is used.
263.Ss DH parameters
264The macro
265.Fn EVP_PKEY_CTX_set_dh_paramgen_prime_len
266sets the length of the DH prime parameter
267.Fa len
268for DH parameter generation.
269It only accepts lengths greater than or equal to 256.
270If this macro is not called, then 1024 is used.
271.Pp
272The
273.Fn EVP_PKEY_CTX_set_dh_paramgen_generator
274macro sets DH generator to
275.Fa gen
276for DH parameter generation.
277If not specified, 2 is used.
278.Ss EC parameters
279The
280.Fn EVP_PKEY_CTX_set_ec_paramgen_curve_nid
281macro sets the EC curve for EC parameter generation to
282.Fa nid .
283For EC parameter generation, this macro must be called or an error occurs
284because there is no default curve.
285.Pp
286The
287.Fn EVP_PKEY_CTX_set_ec_param_enc
288macro sets the EC parameter encoding to
289.Fa param_enc
290when generating EC parameters or an EC key.
291The encoding can be set to 0 for explicit parameters or to
292.Dv OPENSSL_EC_NAMED_CURVE
293to use named curve form.
294.Ss ECDH parameters
295The
296.Fn EVP_PKEY_CTX_set_ecdh_cofactor_mode
297macro sets the cofactor mode to
298.Fa cofactor_mode
299for ECDH key derivation.
300Possible values are 1 to enable cofactor key derivation, 0 to disable
301it, or -1 to clear the stored cofactor mode and fall back to the
302private key cofactor mode.
303.Pp
304The
305.Fn EVP_PKEY_CTX_get_ecdh_cofactor_mode
306macro returns the cofactor mode for
307.Fa ctx
308used for ECDH key derivation.
309Possible return values are 1 when cofactor key derivation is enabled
310or 0 otherwise.
311.Ss ECDH key derivation function parameters
312The
313.Fn EVP_PKEY_CTX_set_ecdh_kdf_type
314macro sets the key derivation function type to
315.Fa kdf
316for ECDH key derivation.
317Possible values are
318.Dv EVP_PKEY_ECDH_KDF_NONE
319or
320.Dv EVP_PKEY_ECDH_KDF_X9_63
321which uses the key derivation specified in X9.63.
322When using key derivation, the
323.Fa kdf_md
324and
325.Fa kdf_outlen
326parameters must also be specified.
327.Pp
328The
329.Fn EVP_PKEY_CTX_get_ecdh_kdf_type
330macro returns the key derivation function type for
331.Fa ctx
332used for ECDH key derivation.
333Possible return values are
334.Dv EVP_PKEY_ECDH_KDF_NONE
335or
336.Dv EVP_PKEY_ECDH_KDF_X9_63 .
337.Pp
338The
339.Fn EVP_PKEY_CTX_set_ecdh_kdf_md
340macro sets the key derivation function message digest to
341.Fa md
342for ECDH key derivation.
343Note that X9.63 specifies that this digest should be SHA1,
344but OpenSSL tolerates other digests.
345.Pp
346The
347.Fn EVP_PKEY_CTX_get_ecdh_kdf_md
348macro gets the key derivation function message digest for
349.Fa ctx
350used for ECDH key derivation.
351.Pp
352The
353.Fn EVP_PKEY_CTX_set_ecdh_kdf_outlen
354macro sets the key derivation function output length to
355.Fa len
356for ECDH key derivation.
357.Pp
358The
359.Fn EVP_PKEY_CTX_get_ecdh_kdf_outlen
360macro gets the key derivation function output length for
361.Fa ctx
362used for ECDH key derivation.
363.Pp
364The
365.Fn EVP_PKEY_CTX_set0_ecdh_kdf_ukm
366macro sets the user key material to
367.Fa ukm
368for ECDH key derivation.
369This parameter is optional and corresponds to the shared info
370in X9.63 terms.
371The library takes ownership of the user key material, so the caller
372should not free the original memory pointed to by
373.Fa ukm .
374.Pp
375The
376.Fn EVP_PKEY_CTX_get0_ecdh_kdf_ukm
377macro gets the user key material for
378.Fa ctx .
379The return value is the user key material length.
380The resulting pointer is owned by the library and should not be
381freed by the caller.
382.Ss Other parameters
383The
384.Fn EVP_PKEY_CTX_set1_id ,
385.Fn EVP_PKEY_CTX_get1_id ,
386and
387.Fn EVP_PKEY_CTX_get1_id_len
388macros manipulate a special identifier field used for some specific
389signature algorithms such as SM2.
390The
391.Fn EVP_PKEY_set1_id
392macro sets the ID to a copy of
393.Fa id
394with the length
395.Fa id_len .
396The caller can safely free the original memory pointed to by
397.Fa id .
398The
399.Fn EVP_PKEY_CTX_get1_id_len
400macro returns the length of the ID set via a previous call to
401.Fn EVP_PKEY_set1_id .
402That length is typically used to allocate memory for a subsequent call to
403.Fn EVP_PKEY_CTX_get1_id ,
404which copies the previously set ID into
405.Pf * Fa id .
406The caller is responsible for allocating sufficient memory for
407.Fa id
408before calling
409.Fn EVP_PKEY_CTX_get1_id .
410.Sh RETURN VALUES
411.Fn EVP_PKEY_CTX_ctrl
412and its macros return a positive value for success and 0 or a negative
413value for failure.
414In particular, a return value of -2 indicates the operation is not
415supported by the public key algorithm.
416.Sh SEE ALSO
417.Xr DH_new 3 ,
418.Xr EVP_DigestInit 3 ,
419.Xr EVP_PKEY_CTX_new 3 ,
420.Xr EVP_PKEY_decrypt 3 ,
421.Xr EVP_PKEY_derive 3 ,
422.Xr EVP_PKEY_encrypt 3 ,
423.Xr EVP_PKEY_get_default_digest_nid 3 ,
424.Xr EVP_PKEY_keygen 3 ,
425.Xr EVP_PKEY_meth_set_ctrl 3 ,
426.Xr EVP_PKEY_sign 3 ,
427.Xr EVP_PKEY_verify 3 ,
428.Xr EVP_PKEY_verify_recover 3 ,
429.Xr RSA_pkey_ctx_ctrl 3
430.Sh HISTORY
431The functions
432.Fn EVP_PKEY_CTX_ctrl ,
433.Fn EVP_PKEY_CTX_ctrl_str ,
434.Fn EVP_PKEY_CTX_set_signature_md ,
435.Fn EVP_PKEY_CTX_set_dsa_paramgen_bits ,
436.Fn EVP_PKEY_CTX_set_dh_paramgen_prime_len ,
437.Fn EVP_PKEY_CTX_set_dh_paramgen_generator ,
438and
439.Fn EVP_PKEY_CTX_set_ec_paramgen_curve_nid
440first appeared in OpenSSL 1.0.0 and have been available since
441.Ox 4.9 .
442.Pp
443The functions
444.Fn EVP_PKEY_CTX_get_signature_md ,
445.Fn EVP_PKEY_CTX_set_ec_param_enc ,
446.Fn EVP_PKEY_CTX_set_ecdh_cofactor_mode ,
447.Fn EVP_PKEY_CTX_get_ecdh_cofactor_mode ,
448.Fn EVP_PKEY_CTX_set_ecdh_kdf_type ,
449.Fn EVP_PKEY_CTX_get_ecdh_kdf_type ,
450.Fn EVP_PKEY_CTX_set_ecdh_kdf_md ,
451.Fn EVP_PKEY_CTX_get_ecdh_kdf_md ,
452.Fn EVP_PKEY_CTX_set_ecdh_kdf_outlen ,
453.Fn EVP_PKEY_CTX_get_ecdh_kdf_outlen ,
454.Fn EVP_PKEY_CTX_set0_ecdh_kdf_ukm ,
455and
456.Fn EVP_PKEY_CTX_get0_ecdh_kdf_ukm
457first appeared in OpenSSL 1.0.2 and have been available since
458.Ox 6.6 .
459.Pp
460The functions
461.Fn EVP_PKEY_CTX_set1_id ,
462.Fn EVP_PKEY_CTX_get1_id ,
463and
464.Fn EVP_PKEY_CTX_get1_id_len
465first appeared in OpenSSL 1.1.1 and have been available since
466.Ox 6.6 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-02-13 22:41:31 +0000