]>
Commit | Line | Data |
---|---|---|
90ccf05f DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
d45a97f4 MC |
5 | EVP_PKEY_CTX_ctrl, |
6 | EVP_PKEY_CTX_ctrl_str, | |
ffd89124 AS |
7 | EVP_PKEY_CTX_ctrl_uint64, |
8 | EVP_PKEY_CTX_md, | |
d45a97f4 MC |
9 | EVP_PKEY_CTX_set_signature_md, |
10 | EVP_PKEY_CTX_get_signature_md, | |
11 | EVP_PKEY_CTX_set_mac_key, | |
12 | EVP_PKEY_CTX_set_rsa_padding, | |
ffd89124 | 13 | EVP_PKEY_CTX_get_rsa_padding, |
d45a97f4 | 14 | EVP_PKEY_CTX_set_rsa_pss_saltlen, |
ffd89124 | 15 | EVP_PKEY_CTX_get_rsa_pss_saltlen, |
d45a97f4 MC |
16 | EVP_PKEY_CTX_set_rsa_keygen_bits, |
17 | EVP_PKEY_CTX_set_rsa_keygen_pubexp, | |
ffd89124 AS |
18 | EVP_PKEY_CTX_set_rsa_keygen_primes, |
19 | EVP_PKEY_CTX_set_rsa_mgf1_md, | |
20 | EVP_PKEY_CTX_get_rsa_mgf1_md, | |
21 | EVP_PKEY_CTX_set_rsa_oaep_md, | |
22 | EVP_PKEY_CTX_get_rsa_oaep_md, | |
23 | EVP_PKEY_CTX_set0_rsa_oaep_label, | |
24 | EVP_PKEY_CTX_get0_rsa_oaep_label, | |
d45a97f4 | 25 | EVP_PKEY_CTX_set_dsa_paramgen_bits, |
aafbe1cc | 26 | EVP_PKEY_CTX_set_dh_paramgen_prime_len, |
ffd89124 | 27 | EVP_PKEY_CTX_set_dh_paramgen_subprime_len, |
aafbe1cc | 28 | EVP_PKEY_CTX_set_dh_paramgen_generator, |
ffd89124 AS |
29 | EVP_PKEY_CTX_set_dh_paramgen_type, |
30 | EVP_PKEY_CTX_set_dh_rfc5114, | |
31 | EVP_PKEY_CTX_set_dhx_rfc5114, | |
d45a97f4 MC |
32 | EVP_PKEY_CTX_set_dh_pad, |
33 | EVP_PKEY_CTX_set_dh_nid, | |
ffd89124 AS |
34 | EVP_PKEY_CTX_set_dh_kdf_type, |
35 | EVP_PKEY_CTX_get_dh_kdf_type, | |
36 | EVP_PKEY_CTX_set0_dh_kdf_oid, | |
37 | EVP_PKEY_CTX_get0_dh_kdf_oid, | |
38 | EVP_PKEY_CTX_set_dh_kdf_md, | |
39 | EVP_PKEY_CTX_get_dh_kdf_md, | |
40 | EVP_PKEY_CTX_set_dh_kdf_outlen, | |
41 | EVP_PKEY_CTX_get_dh_kdf_outlen, | |
42 | EVP_PKEY_CTX_set0_dh_kdf_ukm, | |
43 | EVP_PKEY_CTX_get0_dh_kdf_ukm, | |
146ca72c | 44 | EVP_PKEY_CTX_set_ec_paramgen_curve_nid, |
675f4cee | 45 | EVP_PKEY_CTX_set_ec_param_enc, |
ffd89124 AS |
46 | EVP_PKEY_CTX_set_ecdh_cofactor_mode, |
47 | EVP_PKEY_CTX_get_ecdh_cofactor_mode, | |
48 | EVP_PKEY_CTX_set_ecdh_kdf_type, | |
49 | EVP_PKEY_CTX_get_ecdh_kdf_type, | |
50 | EVP_PKEY_CTX_set_ecdh_kdf_md, | |
51 | EVP_PKEY_CTX_get_ecdh_kdf_md, | |
52 | EVP_PKEY_CTX_set_ecdh_kdf_outlen, | |
53 | EVP_PKEY_CTX_get_ecdh_kdf_outlen, | |
54 | EVP_PKEY_CTX_set0_ecdh_kdf_ukm, | |
55 | EVP_PKEY_CTX_get0_ecdh_kdf_ukm, | |
675f4cee PY |
56 | EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len |
57 | - algorithm specific control operations | |
90ccf05f DSH |
58 | |
59 | =head1 SYNOPSIS | |
60 | ||
61 | #include <openssl/evp.h> | |
62 | ||
63 | int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, | |
e9b77246 | 64 | int cmd, int p1, void *p2); |
ffd89124 AS |
65 | int EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype, |
66 | int cmd, uint64_t value); | |
90ccf05f | 67 | int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type, |
e9b77246 | 68 | const char *value); |
90ccf05f | 69 | |
ffd89124 AS |
70 | int EVP_PKEY_CTX_md(EVP_PKEY_CTX *ctx, int optype, int cmd, const char *md); |
71 | ||
90ccf05f | 72 | int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); |
d45a97f4 MC |
73 | int EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD **pmd); |
74 | ||
75 | int EVP_PKEY_CTX_set_mac_key(EVP_PKEY_CTX *ctx, unsigned char *key, int len); | |
76 | ||
77 | #include <openssl/rsa.h> | |
90ccf05f DSH |
78 | |
79 | int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad); | |
ffd89124 | 80 | int EVP_PKEY_CTX_get_rsa_padding(EVP_PKEY_CTX *ctx, int *pad); |
90ccf05f | 81 | int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len); |
ffd89124 | 82 | int EVP_PKEY_CTX_get_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int *len); |
1722496f | 83 | int EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits); |
90ccf05f | 84 | int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); |
ffd89124 AS |
85 | int EVP_PKEY_CTX_set_rsa_keygen_primes(EVP_PKEY_CTX *ctx, int primes); |
86 | int EVP_PKEY_CTX_set_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); | |
87 | int EVP_PKEY_CTX_get_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); | |
88 | int EVP_PKEY_CTX_set_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); | |
89 | int EVP_PKEY_CTX_get_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); | |
90 | int EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char *label, int len); | |
91 | int EVP_PKEY_CTX_get0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char **label); | |
90ccf05f DSH |
92 | |
93 | #include <openssl/dsa.h> | |
ffd89124 | 94 | |
90ccf05f DSH |
95 | int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits); |
96 | ||
97 | #include <openssl/dh.h> | |
ffd89124 | 98 | |
90ccf05f | 99 | int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len); |
ffd89124 | 100 | int EVP_PKEY_CTX_set_dh_paramgen_subprime_len(EVP_PKEY_CTX *ctx, int len); |
90ccf05f | 101 | int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen); |
ffd89124 | 102 | int EVP_PKEY_CTX_set_dh_paramgen_type(EVP_PKEY_CTX *ctx, int type); |
5368bf05 DSH |
103 | int EVP_PKEY_CTX_set_dh_pad(EVP_PKEY_CTX *ctx, int pad); |
104 | int EVP_PKEY_CTX_set_dh_nid(EVP_PKEY_CTX *ctx, int nid); | |
ffd89124 AS |
105 | int EVP_PKEY_CTX_set_dh_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114); |
106 | int EVP_PKEY_CTX_set_dhx_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114); | |
107 | int EVP_PKEY_CTX_set_dh_kdf_type(EVP_PKEY_CTX *ctx, int kdf); | |
108 | int EVP_PKEY_CTX_get_dh_kdf_type(EVP_PKEY_CTX *ctx); | |
109 | int EVP_PKEY_CTX_set0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT *oid); | |
110 | int EVP_PKEY_CTX_get0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT **oid); | |
111 | int EVP_PKEY_CTX_set_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); | |
112 | int EVP_PKEY_CTX_get_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); | |
113 | int EVP_PKEY_CTX_set_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int len); | |
114 | int EVP_PKEY_CTX_get_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len); | |
115 | int EVP_PKEY_CTX_set0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len); | |
116 | int EVP_PKEY_CTX_get0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm); | |
90ccf05f DSH |
117 | |
118 | #include <openssl/ec.h> | |
e5a8712d | 119 | |
90ccf05f | 120 | int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); |
146ca72c | 121 | int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc); |
ffd89124 AS |
122 | int EVP_PKEY_CTX_set_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx, int cofactor_mode); |
123 | int EVP_PKEY_CTX_get_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx); | |
124 | int EVP_PKEY_CTX_set_ecdh_kdf_type(EVP_PKEY_CTX *ctx, int kdf); | |
125 | int EVP_PKEY_CTX_get_ecdh_kdf_type(EVP_PKEY_CTX *ctx); | |
126 | int EVP_PKEY_CTX_set_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); | |
127 | int EVP_PKEY_CTX_get_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); | |
128 | int EVP_PKEY_CTX_set_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int len); | |
129 | int EVP_PKEY_CTX_get_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len); | |
130 | int EVP_PKEY_CTX_set0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len); | |
131 | int EVP_PKEY_CTX_get0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm); | |
90ccf05f | 132 | |
675f4cee PY |
133 | int EVP_PKEY_CTX_set1_id(EVP_PKEY_CTX *ctx, void *id, size_t id_len); |
134 | int EVP_PKEY_CTX_get1_id(EVP_PKEY_CTX *ctx, void *id); | |
135 | int EVP_PKEY_CTX_get1_id_len(EVP_PKEY_CTX *ctx, size_t *id_len); | |
136 | ||
90ccf05f DSH |
137 | =head1 DESCRIPTION |
138 | ||
139 | The function EVP_PKEY_CTX_ctrl() sends a control operation to the context | |
f0288f05 | 140 | B<ctx>. The key type used must match B<keytype> if it is not -1. The parameter |
90ccf05f DSH |
141 | B<optype> is a mask indicating which operations the control can be applied to. |
142 | The control command is indicated in B<cmd> and any additional arguments in | |
143 | B<p1> and B<p2>. | |
144 | ||
52ad5b60 | 145 | For B<cmd> = B<EVP_PKEY_CTRL_SET_MAC_KEY>, B<p1> is the length of the MAC key, |
3f5616d7 | 146 | and B<p2> is MAC key. This is used by Poly1305, SipHash, HMAC and CMAC. |
52ad5b60 | 147 | |
90ccf05f DSH |
148 | Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will |
149 | instead call one of the algorithm specific macros below. | |
150 | ||
ffd89124 AS |
151 | The function EVP_PKEY_CTX_ctrl_uint64() is a wrapper that directly passes a |
152 | uint64 value as B<p2> to EVP_PKEY_CTX_ctrl(). | |
153 | ||
aafbe1cc | 154 | The function EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm |
90ccf05f DSH |
155 | specific control operation to a context B<ctx> in string form. This is |
156 | intended to be used for options specified on the command line or in text | |
157 | files. The commands supported are documented in the openssl utility | |
158 | command line pages for the option B<-pkeyopt> which is supported by the | |
159 | B<pkeyutl>, B<genpkey> and B<req> commands. | |
160 | ||
ffd89124 AS |
161 | The function EVP_PKEY_CTX_md() sends a message digest control operation |
162 | to the context B<ctx>. The message digest is specified by its name B<md>. | |
163 | ||
90ccf05f DSH |
164 | All the remaining "functions" are implemented as macros. |
165 | ||
166 | The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used | |
d45a97f4 MC |
167 | in a signature. It can be used in the RSA, DSA and ECDSA algorithms. |
168 | ||
169 | The EVP_PKEY_CTX_get_signature_md() macro gets the message digest type used in a | |
170 | signature. It can be used in the RSA, DSA and ECDSA algorithms. | |
171 | ||
172 | Key generation typically involves setting up parameters to be used and | |
173 | generating the private and public key data. Some algorithm implementations | |
174 | allow private key data to be set explicitly using the EVP_PKEY_CTX_set_mac_key() | |
175 | macro. In this case key generation is simply the process of setting up the | |
176 | parameters for the key and then setting the raw key data to the value explicitly | |
177 | provided by that macro. Normally applications would call | |
f929439f | 178 | L<EVP_PKEY_new_raw_private_key(3)> or similar functions instead of this macro. |
d45a97f4 MC |
179 | |
180 | The EVP_PKEY_CTX_set_mac_key() macro can be used with any of the algorithms | |
f929439f | 181 | supported by the L<EVP_PKEY_new_raw_private_key(3)> function. |
90ccf05f | 182 | |
ffd89124 AS |
183 | =head2 RSA parameters |
184 | ||
185 | The EVP_PKEY_CTX_set_rsa_padding() macro sets the RSA padding mode for B<ctx>. | |
186 | The B<pad> parameter can take the value B<RSA_PKCS1_PADDING> for PKCS#1 | |
187 | padding, B<RSA_SSLV23_PADDING> for SSLv23 padding, B<RSA_NO_PADDING> for | |
188 | no padding, B<RSA_PKCS1_OAEP_PADDING> for OAEP padding (encrypt and | |
189 | decrypt only), B<RSA_X931_PADDING> for X9.31 padding (signature operations | |
190 | only) and B<RSA_PKCS1_PSS_PADDING> (sign and verify only). | |
90ccf05f DSH |
191 | |
192 | Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() | |
193 | is used. If this macro is called for PKCS#1 padding the plaintext buffer is | |
194 | an actual digest value and is encapsulated in a DigestInfo structure according | |
195 | to PKCS#1 when signing and this structure is expected (and stripped off) when | |
196 | verifying. If this control is not used with RSA and PKCS#1 padding then the | |
197 | supplied data is used directly and not encapsulated. In the case of X9.31 | |
198 | padding for RSA the algorithm identifier byte is added or checked and removed | |
9d22666e F |
199 | if this control is called. If it is not called then the first byte of the plaintext |
200 | buffer is expected to be the algorithm identifier byte. | |
90ccf05f | 201 | |
ffd89124 AS |
202 | The EVP_PKEY_CTX_get_rsa_padding() macro gets the RSA padding mode for B<ctx>. |
203 | ||
90ccf05f | 204 | The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to |
ffd89124 AS |
205 | B<len>. As its name implies it is only supported for PSS padding. Three special |
206 | values are supported: B<RSA_PSS_SALTLEN_DIGEST> sets the salt length to the | |
207 | digest length, B<RSA_PSS_SALTLEN_MAX> sets the salt length to the maximum | |
208 | permissible value. When verifying B<RSA_PSS_SALTLEN_AUTO> causes the salt length | |
137096a7 DSH |
209 | to be automatically determined based on the B<PSS> block structure. If this |
210 | macro is not called maximum salt length is used when signing and auto detection | |
211 | when verifying is used by default. | |
90ccf05f | 212 | |
ffd89124 AS |
213 | The EVP_PKEY_CTX_get_rsa_pss_saltlen() macro gets the RSA PSS salt length |
214 | for B<ctx>. The padding mode must have been set to B<RSA_PKCS1_PSS_PADDING>. | |
215 | ||
1722496f | 216 | The EVP_PKEY_CTX_set_rsa_keygen_bits() macro sets the RSA key length for |
186bb907 | 217 | RSA key generation to B<bits>. If not specified 1024 bits is used. |
90ccf05f DSH |
218 | |
219 | The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value | |
ffd89124 | 220 | for RSA key generation to B<pubexp>. Currently it should be an odd integer. The |
146ca72c | 221 | B<pubexp> pointer is used internally by this function so it should not be |
ffd89124 AS |
222 | modified or freed after the call. If not specified 65537 is used. |
223 | ||
224 | The EVP_PKEY_CTX_set_rsa_keygen_primes() macro sets the number of primes for | |
225 | RSA key generation to B<primes>. If not specified 2 is used. | |
226 | ||
227 | The EVP_PKEY_CTX_set_rsa_mgf1_md() macro sets the MGF1 digest for RSA padding | |
228 | schemes to B<md>. If not explicitly set the signing digest is used. The | |
229 | padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING> | |
230 | or B<RSA_PKCS1_PSS_PADDING>. | |
231 | ||
232 | The EVP_PKEY_CTX_get_rsa_mgf1_md() macro gets the MGF1 digest for B<ctx>. | |
233 | If not explicitly set the signing digest is used. The padding mode must have | |
234 | been set to B<RSA_PKCS1_OAEP_PADDING> or B<RSA_PKCS1_PSS_PADDING>. | |
235 | ||
236 | The EVP_PKEY_CTX_set_rsa_oaep_md() macro sets the message digest type used | |
237 | in RSA OAEP to B<md>. The padding mode must have been set to | |
238 | B<RSA_PKCS1_OAEP_PADDING>. | |
239 | ||
240 | The EVP_PKEY_CTX_get_rsa_oaep_md() macro gets the message digest type used | |
241 | in RSA OAEP to B<md>. The padding mode must have been set to | |
242 | B<RSA_PKCS1_OAEP_PADDING>. | |
243 | ||
244 | The EVP_PKEY_CTX_set0_rsa_oaep_label() macro sets the RSA OAEP label to | |
245 | B<label> and its length to B<len>. If B<label> is NULL or B<len> is 0, | |
246 | the label is cleared. The library takes ownership of the label so the | |
247 | caller should not free the original memory pointed to by B<label>. | |
248 | The padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING>. | |
249 | ||
250 | The EVP_PKEY_CTX_get0_rsa_oaep_label() macro gets the RSA OAEP label to | |
251 | B<label>. The return value is the label length. The padding mode | |
252 | must have been set to B<RSA_PKCS1_OAEP_PADDING>. The resulting pointer is owned | |
253 | by the library and should not be freed by the caller. | |
254 | ||
255 | =head2 DSA parameters | |
90ccf05f | 256 | |
ffd89124 | 257 | The EVP_PKEY_CTX_set_dsa_paramgen_bits() macro sets the number of bits used |
90ccf05f DSH |
258 | for DSA parameter generation to B<bits>. If not specified 1024 is used. |
259 | ||
ffd89124 AS |
260 | =head2 DH parameters |
261 | ||
262 | The EVP_PKEY_CTX_set_dh_paramgen_prime_len() macro sets the length of the DH | |
90ccf05f | 263 | prime parameter B<p> for DH parameter generation. If this macro is not called |
ffd89124 AS |
264 | then 1024 is used. Only accepts lengths greater than or equal to 256. |
265 | ||
266 | The EVP_PKEY_CTX_set_dh_paramgen_subprime_len() macro sets the length of the DH | |
267 | optional subprime parameter B<q> for DH parameter generation. The default is | |
268 | 256 if the prime is at least 2048 bits long or 160 otherwise. The DH | |
269 | paramgen type must have been set to x9.42. | |
90ccf05f DSH |
270 | |
271 | The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B<gen> | |
272 | for DH parameter generation. If not specified 2 is used. | |
273 | ||
ffd89124 AS |
274 | The EVP_PKEY_CTX_set_dh_paramgen_type() macro sets the key type for DH |
275 | parameter generation. Use 0 for PKCS#3 DH and 1 for X9.42 DH. | |
276 | The default is 0. | |
277 | ||
5368bf05 DSH |
278 | The EVP_PKEY_CTX_set_dh_pad() macro sets the DH padding mode. If B<pad> is |
279 | 1 the shared secret is padded with zeroes up to the size of the DH prime B<p>. | |
280 | If B<pad> is zero (the default) then no padding is performed. | |
281 | ||
282 | EVP_PKEY_CTX_set_dh_nid() sets the DH parameters to values corresponding to | |
ffd89124 AS |
283 | B<nid> as defined in RFC7919. The B<nid> parameter must be B<NID_ffdhe2048>, |
284 | B<NID_ffdhe3072>, B<NID_ffdhe4096>, B<NID_ffdhe6144>, B<NID_ffdhe8192> | |
285 | or B<NID_undef> to clear the stored value. This macro can be called during | |
286 | parameter or key generation. | |
287 | The nid parameter and the rfc5114 parameter are mutually exclusive. | |
288 | ||
289 | The EVP_PKEY_CTX_set_dh_rfc5114() and EVP_PKEY_CTX_set_dhx_rfc5114() macros are | |
290 | synonymous. They set the DH parameters to the values defined in RFC5114. The | |
291 | B<rfc5114> parameter must be 1, 2 or 3 corresponding to RFC5114 sections | |
292 | 2.1, 2.2 and 2.3. or 0 to clear the stored value. This macro can be called | |
293 | during parameter generation. The B<ctx> must have a key type of | |
294 | B<EVP_PKEY_DHX>. | |
295 | The rfc5114 parameter and the nid parameter are mutually exclusive. | |
296 | ||
297 | =head2 DH key derivation function parameters | |
298 | ||
299 | Note that all of the following functions require that the B<ctx> parameter has | |
300 | a private key type of B<EVP_PKEY_DHX>. When using key derivation, the output of | |
301 | EVP_PKEY_derive() is the output of the KDF instead of the DH shared secret. | |
302 | The KDF output is typically used as a Key Encryption Key (KEK) that in turn | |
303 | encrypts a Content Encryption Key (CEK). | |
304 | ||
305 | The EVP_PKEY_CTX_set_dh_kdf_type() macro sets the key derivation function type | |
306 | to B<kdf> for DH key derivation. Possible values are B<EVP_PKEY_DH_KDF_NONE> | |
307 | and B<EVP_PKEY_DH_KDF_X9_42> which uses the key derivation specified in RFC2631 | |
308 | (based on the keying algorithm described in X9.42). When using key derivation, | |
309 | the B<kdf_oid>, B<kdf_md> and B<kdf_outlen> parameters must also be specified. | |
310 | ||
311 | The EVP_PKEY_CTX_get_dh_kdf_type() macro gets the key derivation function type | |
312 | for B<ctx> used for DH key derivation. Possible values are B<EVP_PKEY_DH_KDF_NONE> | |
313 | and B<EVP_PKEY_DH_KDF_X9_42>. | |
314 | ||
315 | The EVP_PKEY_CTX_set0_dh_kdf_oid() macro sets the key derivation function | |
316 | object identifier to B<oid> for DH key derivation. This OID should identify | |
317 | the algorithm to be used with the Content Encryption Key. | |
318 | The library takes ownership of the object identifier so the caller should not | |
319 | free the original memory pointed to by B<oid>. | |
320 | ||
321 | The EVP_PKEY_CTX_get0_dh_kdf_oid() macro gets the key derivation function oid | |
322 | for B<ctx> used for DH key derivation. The resulting pointer is owned by the | |
323 | library and should not be freed by the caller. | |
324 | ||
325 | The EVP_PKEY_CTX_set_dh_kdf_md() macro sets the key derivation function | |
326 | message digest to B<md> for DH key derivation. Note that RFC2631 specifies | |
327 | that this digest should be SHA1 but OpenSSL tolerates other digests. | |
328 | ||
329 | The EVP_PKEY_CTX_get_dh_kdf_md() macro gets the key derivation function | |
330 | message digest for B<ctx> used for DH key derivation. | |
331 | ||
332 | The EVP_PKEY_CTX_set_dh_kdf_outlen() macro sets the key derivation function | |
333 | output length to B<len> for DH key derivation. | |
334 | ||
335 | The EVP_PKEY_CTX_get_dh_kdf_outlen() macro gets the key derivation function | |
336 | output length for B<ctx> used for DH key derivation. | |
337 | ||
338 | The EVP_PKEY_CTX_set0_dh_kdf_ukm() macro sets the user key material to | |
339 | B<ukm> and its length to B<len> for DH key derivation. This parameter is optional | |
340 | and corresponds to the partyAInfo field in RFC2631 terms. The specification | |
341 | requires that it is 512 bits long but this is not enforced by OpenSSL. | |
342 | The library takes ownership of the user key material so the caller should not | |
343 | free the original memory pointed to by B<ukm>. | |
344 | ||
345 | The EVP_PKEY_CTX_get0_dh_kdf_ukm() macro gets the user key material for B<ctx>. | |
346 | The return value is the user key material length. The resulting pointer is owned | |
347 | by the library and should not be freed by the caller. | |
348 | ||
349 | =head2 EC parameters | |
5368bf05 | 350 | |
90ccf05f DSH |
351 | The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter |
352 | generation to B<nid>. For EC parameter generation this macro must be called | |
a528d4f0 RS |
353 | or an error occurs because there is no default curve. |
354 | This function can also be called to set the curve explicitly when | |
146ca72c DSH |
355 | generating an EC key. |
356 | ||
ffd89124 | 357 | The EVP_PKEY_CTX_set_ec_param_enc() macro sets the EC parameter encoding to |
146ca72c DSH |
358 | B<param_enc> when generating EC parameters or an EC key. The encoding can be |
359 | B<OPENSSL_EC_EXPLICIT_CURVE> for explicit parameters (the default in versions | |
360 | of OpenSSL before 1.1.0) or B<OPENSSL_EC_NAMED_CURVE> to use named curve form. | |
361 | For maximum compatibility the named curve form should be used. Note: the | |
a528d4f0 | 362 | B<OPENSSL_EC_NAMED_CURVE> value was only added to OpenSSL 1.1.0; previous |
146ca72c | 363 | versions should use 0 instead. |
90ccf05f | 364 | |
ffd89124 AS |
365 | =head2 ECDH parameters |
366 | ||
367 | The EVP_PKEY_CTX_set_ecdh_cofactor_mode() macro sets the cofactor mode to | |
368 | B<cofactor_mode> for ECDH key derivation. Possible values are 1 to enable | |
369 | cofactor key derivation, 0 to disable it and -1 to clear the stored cofactor | |
370 | mode and fallback to the private key cofactor mode. | |
371 | ||
372 | The EVP_PKEY_CTX_get_ecdh_cofactor_mode() macro returns the cofactor mode for | |
373 | B<ctx> used for ECDH key derivation. Possible values are 1 when cofactor key | |
374 | derivation is enabled and 0 otherwise. | |
375 | ||
376 | =head2 ECDH key derivation function parameters | |
377 | ||
378 | The EVP_PKEY_CTX_set_ecdh_kdf_type() macro sets the key derivation function type | |
379 | to B<kdf> for ECDH key derivation. Possible values are B<EVP_PKEY_ECDH_KDF_NONE> | |
380 | and B<EVP_PKEY_ECDH_KDF_X9_63> which uses the key derivation specified in X9.63. | |
381 | When using key derivation, the B<kdf_md> and B<kdf_outlen> parameters must | |
382 | also be specified. | |
383 | ||
384 | The EVP_PKEY_CTX_get_ecdh_kdf_type() macro returns the key derivation function | |
385 | type for B<ctx> used for ECDH key derivation. Possible values are | |
386 | B<EVP_PKEY_ECDH_KDF_NONE> and B<EVP_PKEY_ECDH_KDF_X9_63>. | |
387 | ||
388 | The EVP_PKEY_CTX_set_ecdh_kdf_md() macro sets the key derivation function | |
389 | message digest to B<md> for ECDH key derivation. Note that X9.63 specifies | |
390 | that this digest should be SHA1 but OpenSSL tolerates other digests. | |
391 | ||
392 | The EVP_PKEY_CTX_get_ecdh_kdf_md() macro gets the key derivation function | |
393 | message digest for B<ctx> used for ECDH key derivation. | |
394 | ||
395 | The EVP_PKEY_CTX_set_ecdh_kdf_outlen() macro sets the key derivation function | |
396 | output length to B<len> for ECDH key derivation. | |
397 | ||
398 | The EVP_PKEY_CTX_get_ecdh_kdf_outlen() macro gets the key derivation function | |
399 | output length for B<ctx> used for ECDH key derivation. | |
400 | ||
401 | The EVP_PKEY_CTX_set0_ecdh_kdf_ukm() macro sets the user key material to B<ukm> | |
402 | for ECDH key derivation. This parameter is optional and corresponds to the | |
403 | shared info in X9.63 terms. The library takes ownership of the user key material | |
404 | so the caller should not free the original memory pointed to by B<ukm>. | |
405 | ||
406 | The EVP_PKEY_CTX_get0_ecdh_kdf_ukm() macro gets the user key material for B<ctx>. | |
407 | The return value is the user key material length. The resulting pointer is owned | |
408 | by the library and should not be freed by the caller. | |
409 | ||
410 | =head2 Other parameters | |
411 | ||
675f4cee | 412 | The EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len() |
f922dac8 PY |
413 | macros are used to manipulate the special identifier field for specific signature |
414 | algorithms such as SM2. The EVP_PKEY_CTX_set1_id() sets an ID pointed by B<id> with | |
415 | the length B<id_len> to the library. The library takes a copy of the id so that | |
416 | the caller can safely free the original memory pointed to by B<id>. The | |
417 | EVP_PKEY_CTX_get1_id_len() macro returns the length of the ID set via a previous | |
418 | call to EVP_PKEY_CTX_set1_id(). The length is usually used to allocate adequate | |
419 | memory for further calls to EVP_PKEY_CTX_get1_id(). The EVP_PKEY_CTX_get1_id() | |
420 | macro returns the previously set ID value to caller in B<id>. The caller should | |
421 | allocate adequate memory space for the B<id> before calling EVP_PKEY_CTX_get1_id(). | |
675f4cee | 422 | |
90ccf05f DSH |
423 | =head1 RETURN VALUES |
424 | ||
425 | EVP_PKEY_CTX_ctrl() and its macros return a positive value for success and 0 | |
426 | or a negative value for failure. In particular a return value of -2 | |
427 | indicates the operation is not supported by the public key algorithm. | |
428 | ||
429 | =head1 SEE ALSO | |
430 | ||
9b86974e RS |
431 | L<EVP_PKEY_CTX_new(3)>, |
432 | L<EVP_PKEY_encrypt(3)>, | |
433 | L<EVP_PKEY_decrypt(3)>, | |
434 | L<EVP_PKEY_sign(3)>, | |
435 | L<EVP_PKEY_verify(3)>, | |
436 | L<EVP_PKEY_verify_recover(3)>, | |
ffd89124 | 437 | L<EVP_PKEY_derive(3)>, |
9b86974e | 438 | L<EVP_PKEY_keygen(3)> |
90ccf05f DSH |
439 | |
440 | =head1 HISTORY | |
441 | ||
675f4cee | 442 | EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len() |
f922dac8 | 443 | macros were added in 1.1.1, other functions were first added to OpenSSL 1.0.0. |
90ccf05f | 444 | |
e2f92610 RS |
445 | =head1 COPYRIGHT |
446 | ||
b0edda11 | 447 | Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 448 | |
4746f25a | 449 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
450 | this file except in compliance with the License. You can obtain a copy |
451 | in the file LICENSE in the source distribution or at | |
452 | L<https://www.openssl.org/source/license.html>. | |
453 | ||
454 | =cut |