| blob | 8462da6d46861bd0ba9b57d02f383d0d18970de4 |
1 .\" $OpenBSD: EVP_PKEY_CTX_ctrl.3,v 1.11 2018/03/23 23:18:17 schwarze Exp $
2 .\" OpenSSL EVP_PKEY_CTX_ctrl.pod 1722496f Jun 8 15:18:38 2017 -0400
3 .\" OpenSSL EVP_PKEY_CTX_ctrl.pod e03af178 Dec 11 17:05:57 2014 -0500
4 .\"
5 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
6 .\" Copyright (c) 2006, 2009, 2013, 2014, 2015 The OpenSSL Project.
7 .\" All rights reserved.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\"
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\"
16 .\" 2. Redistributions in binary form must reproduce the above copyright
17 .\" notice, this list of conditions and the following disclaimer in
18 .\" the documentation and/or other materials provided with the
19 .\" distribution.
20 .\"
21 .\" 3. All advertising materials mentioning features or use of this
22 .\" software must display the following acknowledgment:
23 .\" "This product includes software developed by the OpenSSL Project
24 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
25 .\"
26 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
27 .\" endorse or promote products derived from this software without
28 .\" prior written permission. For written permission, please contact
29 .\" openssl-core@openssl.org.
30 .\"
31 .\" 5. Products derived from this software may not be called "OpenSSL"
32 .\" nor may "OpenSSL" appear in their names without prior written
33 .\" permission of the OpenSSL Project.
34 .\"
35 .\" 6. Redistributions of any form whatsoever must retain the following
36 .\" acknowledgment:
37 .\" "This product includes software developed by the OpenSSL Project
38 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
39 .\"
40 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
41 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
42 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
43 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
44 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
45 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
46 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
47 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
48 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
49 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
50 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
51 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
52 .\"
53 .Dd $Mdocdate: March 23 2018 $
54 .Dt EVP_PKEY_CTX_CTRL 3
55 .Os
56 .Sh NAME
57 .Nm EVP_PKEY_CTX_ctrl ,
58 .Nm EVP_PKEY_CTX_ctrl_str ,
59 .Nm EVP_PKEY_CTX_set_signature_md ,
60 .Nm EVP_PKEY_CTX_set_rsa_padding ,
61 .Nm EVP_PKEY_CTX_set_rsa_pss_saltlen ,
62 .Nm EVP_PKEY_CTX_set_rsa_keygen_bits ,
63 .Nm EVP_PKEY_CTX_set_rsa_keygen_pubexp ,
64 .Nm EVP_PKEY_CTX_set_dsa_paramgen_bits ,
65 .Nm EVP_PKEY_CTX_set_dh_paramgen_prime_len ,
66 .Nm EVP_PKEY_CTX_set_dh_paramgen_generator ,
67 .Nm EVP_PKEY_CTX_set_ec_paramgen_curve_nid
68 .Nd algorithm specific control operations
69 .Sh SYNOPSIS
70 .In openssl/evp.h
71 .Ft int
72 .Fo EVP_PKEY_CTX_ctrl
73 .Fa "EVP_PKEY_CTX *ctx"
74 .Fa "int keytype"
75 .Fa "int optype"
76 .Fa "int cmd"
77 .Fa "int p1"
78 .Fa "void *p2"
79 .Fc
80 .Ft int
81 .Fo EVP_PKEY_CTX_ctrl_str
82 .Fa "EVP_PKEY_CTX *ctx"
83 .Fa "const char *type"
84 .Fa "const char *value"
85 .Fc
86 .In openssl/rsa.h
87 .Ft int
88 .Fo EVP_PKEY_CTX_set_signature_md
89 .Fa "EVP_PKEY_CTX *ctx"
90 .Fa "const EVP_MD *md"
91 .Fc
92 .Ft int
93 .Fo EVP_PKEY_CTX_set_rsa_padding
94 .Fa "EVP_PKEY_CTX *ctx"
95 .Fa "int pad"
96 .Fc
97 .Ft int
98 .Fo EVP_PKEY_CTX_set_rsa_pss_saltlen
99 .Fa "EVP_PKEY_CTX *ctx"
100 .Fa "int len"
101 .Fc
102 .Ft int
103 .Fo EVP_PKEY_CTX_set_rsa_keygen_bits
104 .Fa "EVP_PKEY_CTX *ctx"
105 .Fa "int mbits"
106 .Fc
107 .Ft int
108 .Fo EVP_PKEY_CTX_set_rsa_keygen_pubexp
109 .Fa "EVP_PKEY_CTX *ctx"
110 .Fa "BIGNUM *pubexp"
111 .Fc
112 .In openssl/dsa.h
113 .Ft int
114 .Fo EVP_PKEY_CTX_set_dsa_paramgen_bits
115 .Fa "EVP_PKEY_CTX *ctx"
116 .Fa "int nbits"
117 .Fc
118 .In openssl/dh.h
119 .Ft int
120 .Fo EVP_PKEY_CTX_set_dh_paramgen_prime_len
121 .Fa "EVP_PKEY_CTX *ctx"
122 .Fa "int len"
123 .Fc
124 .Ft int
125 .Fo EVP_PKEY_CTX_set_dh_paramgen_generator
126 .Fa "EVP_PKEY_CTX *ctx"
127 .Fa "int gen"
128 .Fc
129 .In openssl/ec.h
130 .Ft int
131 .Fo EVP_PKEY_CTX_set_ec_paramgen_curve_nid
132 .Fa "EVP_PKEY_CTX *ctx"
133 .Fa "int nid"
134 .Fc
135 .Sh DESCRIPTION
136 The function
137 .Fn EVP_PKEY_CTX_ctrl
138 sends a control operation to the context
139 .Fa ctx .
140 The key type used must match
141 .Fa keytype
142 if it is not -1.
143 The parameter
144 .Fa optype
145 is a mask indicating which operations the control can be applied to.
146 The control command is indicated in
147 .Fa cmd
148 and any additional arguments in
149 .Fa p1
150 and
151 .Fa p2 .
152 .Pp
153 Applications will not normally call
154 .Fn EVP_PKEY_CTX_ctrl
155 directly but will instead call one of the algorithm specific macros
156 below.
157 .Pp
158 The function
159 .Fn EVP_PKEY_CTX_ctrl_str
160 allows an application to send an algorithm specific control operation to
161 a context
162 .Fa ctx
163 in string form.
164 This is intended to be used for options specified on the command line or
165 in text files.
166 The commands supported are documented in the
167 .Xr openssl 1
168 utility command line pages for the option
169 .Fl pkeyopt
170 which is supported by the
171 .Cm pkeyutl ,
172 .Cm genpkey ,
173 and
174 .Cm req
175 commands.
176 .Pp
177 All the remaining "functions" are implemented as macros.
178 .Pp
179 The
180 .Fn EVP_PKEY_CTX_set_signature_md
181 macro sets the message digest type used in a signature.
182 It can be used with any public key algorithm supporting signature
183 operations.
184 .Pp
185 The macro
186 .Fn EVP_PKEY_CTX_set_rsa_padding
187 sets the RSA padding mode for
188 .Fa ctx .
189 The
190 .Fa pad
191 parameter can take the value
192 .Dv RSA_PKCS1_PADDING
193 for PKCS#1 padding,
194 .Dv RSA_NO_PADDING
195 for no padding,
196 .Dv RSA_PKCS1_OAEP_PADDING
197 for OAEP padding (encrypt and decrypt only),
198 .Dv RSA_X931_PADDING
199 for X9.31 padding (signature operations only) and
200 .Dv RSA_PKCS1_PSS_PADDING
201 (sign and verify only).
202 .Pp
203 Two RSA padding modes behave differently if
204 .Fn EVP_PKEY_CTX_set_signature_md
205 is used.
206 If this macro is called for PKCS#1 padding, the plaintext buffer is an
207 actual digest value and is encapsulated in a
208 .Vt DigestInfo
209 structure according to PKCS#1 when signing and this structure is
210 expected (and stripped off) when verifying.
211 If this control is not used with RSA and PKCS#1 padding then the
212 supplied data is used directly and not encapsulated.
213 In the case of X9.31 padding for RSA the algorithm identifier byte is
214 added or checked and removed if this control is called.
215 If it is not called then the first byte of the plaintext buffer is
216 expected to be the algorithm identifier byte.
217 .Pp
218 The
219 .Fn EVP_PKEY_CTX_set_rsa_pss_saltlen
220 macro sets the RSA PSS salt length to
221 .Fa len .
222 As its name implies, it is only supported for PSS padding.
223 Two special values are supported: -1 sets the salt length to the digest
224 length.
225 When signing -2 sets the salt length to the maximum permissible value.
226 When verifying -2 causes the salt length to be automatically determined
227 based on the PSS block structure.
228 If this macro is not called a salt length value of -2 is used by
229 default.
230 .Pp
231 The
232 .Fn EVP_PKEY_CTX_set_rsa_keygen_bits
233 macro sets the RSA key length for RSA key generation to
234 .Fa mbits .
235 If not specified, 1024 bits is used.
236 .Pp
237 The
238 .Fn EVP_PKEY_CTX_set_rsa_keygen_pubexp
239 macro sets the public exponent value for RSA key generation to
240 .Fa pubexp .
241 Currently, it should be an odd integer.
242 The
243 .Fa pubexp
244 pointer is used internally by this function, so it should not be modified
245 or freed after the call.
246 If this macro is not called, then 65537 is used.
247 .Pp
248 The macro
249 .Fn EVP_PKEY_CTX_set_dsa_paramgen_bits
250 sets the number of bits used for DSA parameter generation to
251 .Fa nbits .
252 If not specified, 1024 is used.
253 .Pp
254 The macro
255 .Fn EVP_PKEY_CTX_set_dh_paramgen_prime_len
256 sets the length of the DH prime parameter
257 .Fa len
258 for DH parameter generation.
259 If this macro is not called, then 1024 is used.
260 .Pp
261 The
262 .Fn EVP_PKEY_CTX_set_dh_paramgen_generator
263 macro sets DH generator to
264 .Fa gen
265 for DH parameter generation.
266 If not specified, 2 is used.
267 .Pp
268 The
269 .Fn EVP_PKEY_CTX_set_ec_paramgen_curve_nid
270 sets the EC curve for EC parameter generation to
271 .Fa nid .
272 For EC parameter generation, this macro must be called or an error occurs
273 because there is no default curve.
274 .Sh RETURN VALUES
275 .Fn EVP_PKEY_CTX_ctrl
276 and its macros return a positive value for success and 0 or a negative
277 value for failure.
278 In particular, a return value of -2 indicates the operation is not
279 supported by the public key algorithm.
280 .Sh SEE ALSO
281 .Xr EVP_PKEY_CTX_new 3 ,
282 .Xr EVP_PKEY_decrypt 3 ,
283 .Xr EVP_PKEY_derive 3 ,
284 .Xr EVP_PKEY_encrypt 3 ,
285 .Xr EVP_PKEY_get_default_digest_nid 3 ,
286 .Xr EVP_PKEY_keygen 3 ,
287 .Xr EVP_PKEY_meth_set_ctrl 3 ,
288 .Xr EVP_PKEY_sign 3 ,
289 .Xr EVP_PKEY_verify 3 ,
290 .Xr EVP_PKEY_verify_recover 3
291 .Sh HISTORY
292 These functions first appeared in OpenSSL 1.0.0
293 and have been available since
294 .Ox 4.9 .