]>
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, | |
11a1b341 MC |
12 | EVP_PKEY_CTX_set_group_name, |
13 | EVP_PKEY_CTX_get_group_name, | |
d45a97f4 | 14 | EVP_PKEY_CTX_set_rsa_padding, |
ffd89124 | 15 | EVP_PKEY_CTX_get_rsa_padding, |
d45a97f4 | 16 | EVP_PKEY_CTX_set_rsa_pss_saltlen, |
ffd89124 | 17 | EVP_PKEY_CTX_get_rsa_pss_saltlen, |
d45a97f4 MC |
18 | EVP_PKEY_CTX_set_rsa_keygen_bits, |
19 | EVP_PKEY_CTX_set_rsa_keygen_pubexp, | |
3786d748 | 20 | EVP_PKEY_CTX_set1_rsa_keygen_pubexp, |
ffd89124 | 21 | EVP_PKEY_CTX_set_rsa_keygen_primes, |
d8fef6da | 22 | EVP_PKEY_CTX_set_rsa_mgf1_md_name, |
ffd89124 AS |
23 | EVP_PKEY_CTX_set_rsa_mgf1_md, |
24 | EVP_PKEY_CTX_get_rsa_mgf1_md, | |
d8fef6da MC |
25 | EVP_PKEY_CTX_get_rsa_mgf1_md_name, |
26 | EVP_PKEY_CTX_set_rsa_oaep_md_name, | |
ffd89124 AS |
27 | EVP_PKEY_CTX_set_rsa_oaep_md, |
28 | EVP_PKEY_CTX_get_rsa_oaep_md, | |
d8fef6da | 29 | EVP_PKEY_CTX_get_rsa_oaep_md_name, |
ffd89124 AS |
30 | EVP_PKEY_CTX_set0_rsa_oaep_label, |
31 | EVP_PKEY_CTX_get0_rsa_oaep_label, | |
d45a97f4 | 32 | EVP_PKEY_CTX_set_dsa_paramgen_bits, |
a97faad7 DB |
33 | EVP_PKEY_CTX_set_dsa_paramgen_q_bits, |
34 | EVP_PKEY_CTX_set_dsa_paramgen_md, | |
b03ec3b5 SL |
35 | EVP_PKEY_CTX_set_dsa_paramgen_md_props, |
36 | EVP_PKEY_CTX_set_dsa_paramgen_gindex, | |
37 | EVP_PKEY_CTX_set_dsa_paramgen_type, | |
38 | EVP_PKEY_CTX_set_dsa_paramgen_seed, | |
aafbe1cc | 39 | EVP_PKEY_CTX_set_dh_paramgen_prime_len, |
ffd89124 | 40 | EVP_PKEY_CTX_set_dh_paramgen_subprime_len, |
aafbe1cc | 41 | EVP_PKEY_CTX_set_dh_paramgen_generator, |
ffd89124 | 42 | EVP_PKEY_CTX_set_dh_paramgen_type, |
7165593c SL |
43 | EVP_PKEY_CTX_set_dh_paramgen_gindex, |
44 | EVP_PKEY_CTX_set_dh_paramgen_seed, | |
ffd89124 AS |
45 | EVP_PKEY_CTX_set_dh_rfc5114, |
46 | EVP_PKEY_CTX_set_dhx_rfc5114, | |
d45a97f4 MC |
47 | EVP_PKEY_CTX_set_dh_pad, |
48 | EVP_PKEY_CTX_set_dh_nid, | |
ffd89124 AS |
49 | EVP_PKEY_CTX_set_dh_kdf_type, |
50 | EVP_PKEY_CTX_get_dh_kdf_type, | |
51 | EVP_PKEY_CTX_set0_dh_kdf_oid, | |
52 | EVP_PKEY_CTX_get0_dh_kdf_oid, | |
53 | EVP_PKEY_CTX_set_dh_kdf_md, | |
54 | EVP_PKEY_CTX_get_dh_kdf_md, | |
55 | EVP_PKEY_CTX_set_dh_kdf_outlen, | |
56 | EVP_PKEY_CTX_get_dh_kdf_outlen, | |
57 | EVP_PKEY_CTX_set0_dh_kdf_ukm, | |
58 | EVP_PKEY_CTX_get0_dh_kdf_ukm, | |
146ca72c | 59 | EVP_PKEY_CTX_set_ec_paramgen_curve_nid, |
675f4cee | 60 | EVP_PKEY_CTX_set_ec_param_enc, |
ffd89124 AS |
61 | EVP_PKEY_CTX_set_ecdh_cofactor_mode, |
62 | EVP_PKEY_CTX_get_ecdh_cofactor_mode, | |
63 | EVP_PKEY_CTX_set_ecdh_kdf_type, | |
64 | EVP_PKEY_CTX_get_ecdh_kdf_type, | |
65 | EVP_PKEY_CTX_set_ecdh_kdf_md, | |
66 | EVP_PKEY_CTX_get_ecdh_kdf_md, | |
67 | EVP_PKEY_CTX_set_ecdh_kdf_outlen, | |
68 | EVP_PKEY_CTX_get_ecdh_kdf_outlen, | |
69 | EVP_PKEY_CTX_set0_ecdh_kdf_ukm, | |
70 | EVP_PKEY_CTX_get0_ecdh_kdf_ukm, | |
80f4fd18 SL |
71 | EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len, |
72 | EVP_PKEY_CTX_set_kem_op | |
675f4cee | 73 | - algorithm specific control operations |
90ccf05f DSH |
74 | |
75 | =head1 SYNOPSIS | |
76 | ||
77 | #include <openssl/evp.h> | |
78 | ||
79 | int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, | |
e9b77246 | 80 | int cmd, int p1, void *p2); |
ffd89124 AS |
81 | int EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype, |
82 | int cmd, uint64_t value); | |
90ccf05f | 83 | int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type, |
e9b77246 | 84 | const char *value); |
90ccf05f | 85 | |
ffd89124 AS |
86 | int EVP_PKEY_CTX_md(EVP_PKEY_CTX *ctx, int optype, int cmd, const char *md); |
87 | ||
90ccf05f | 88 | int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); |
d45a97f4 MC |
89 | int EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD **pmd); |
90 | ||
9fdcc21f DO |
91 | int EVP_PKEY_CTX_set_mac_key(EVP_PKEY_CTX *ctx, const unsigned char *key, |
92 | int len); | |
11a1b341 MC |
93 | int EVP_PKEY_CTX_set_group_name(EVP_PKEY_CTX *ctx, const char *name); |
94 | int EVP_PKEY_CTX_get_group_name(EVP_PKEY_CTX *ctx, char *name, size_t namelen); | |
d45a97f4 | 95 | |
80f4fd18 SL |
96 | int EVP_PKEY_CTX_set_kem_op(EVP_PKEY_CTX *ctx, const char *op); |
97 | ||
d45a97f4 | 98 | #include <openssl/rsa.h> |
90ccf05f DSH |
99 | |
100 | int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad); | |
ffd89124 | 101 | int EVP_PKEY_CTX_get_rsa_padding(EVP_PKEY_CTX *ctx, int *pad); |
6f4b7663 RL |
102 | int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int saltlen); |
103 | int EVP_PKEY_CTX_get_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int *saltlen); | |
1722496f | 104 | int EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits); |
3786d748 | 105 | int EVP_PKEY_CTX_set1_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); |
ffd89124 | 106 | int EVP_PKEY_CTX_set_rsa_keygen_primes(EVP_PKEY_CTX *ctx, int primes); |
d8fef6da MC |
107 | int EVP_PKEY_CTX_set_rsa_mgf1_md_name(EVP_PKEY_CTX *ctx, const char *mdname, |
108 | const char *mdprops); | |
ffd89124 AS |
109 | int EVP_PKEY_CTX_set_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); |
110 | int EVP_PKEY_CTX_get_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); | |
d8fef6da MC |
111 | int EVP_PKEY_CTX_get_rsa_mgf1_md_name(EVP_PKEY_CTX *ctx, char *name, |
112 | size_t namelen); | |
113 | int EVP_PKEY_CTX_set_rsa_oaep_md_name(EVP_PKEY_CTX *ctx, const char *mdname, | |
114 | const char *mdprops); | |
ffd89124 AS |
115 | int EVP_PKEY_CTX_set_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); |
116 | int EVP_PKEY_CTX_get_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); | |
d8fef6da | 117 | int EVP_PKEY_CTX_get_rsa_oaep_md_name(EVP_PKEY_CTX *ctx, char *name, |
f64f17c3 SL |
118 | size_t namelen); |
119 | int EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char *label, | |
120 | int len); | |
ffd89124 | 121 | int EVP_PKEY_CTX_get0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char **label); |
90ccf05f DSH |
122 | |
123 | #include <openssl/dsa.h> | |
ffd89124 | 124 | |
90ccf05f | 125 | int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits); |
a97faad7 DB |
126 | int EVP_PKEY_CTX_set_dsa_paramgen_q_bits(EVP_PKEY_CTX *ctx, int qbits); |
127 | int EVP_PKEY_CTX_set_dsa_paramgen_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); | |
b03ec3b5 SL |
128 | int EVP_PKEY_CTX_set_dsa_paramgen_md_props(EVP_PKEY_CTX *ctx, |
129 | const char *md_name, | |
130 | const char *md_properties); | |
131 | int EVP_PKEY_CTX_set_dsa_paramgen_type(EVP_PKEY_CTX *ctx, const char *name); | |
132 | int EVP_PKEY_CTX_set_dsa_paramgen_gindex(EVP_PKEY_CTX *ctx, int gindex); | |
133 | int EVP_PKEY_CTX_set_dsa_paramgen_seed(EVP_PKEY_CTX *ctx, | |
134 | const unsigned char *seed, | |
135 | size_t seedlen); | |
90ccf05f DSH |
136 | |
137 | #include <openssl/dh.h> | |
ffd89124 | 138 | |
90ccf05f | 139 | int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len); |
ffd89124 | 140 | int EVP_PKEY_CTX_set_dh_paramgen_subprime_len(EVP_PKEY_CTX *ctx, int len); |
90ccf05f | 141 | int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen); |
ffd89124 | 142 | int EVP_PKEY_CTX_set_dh_paramgen_type(EVP_PKEY_CTX *ctx, int type); |
5368bf05 DSH |
143 | int EVP_PKEY_CTX_set_dh_pad(EVP_PKEY_CTX *ctx, int pad); |
144 | int EVP_PKEY_CTX_set_dh_nid(EVP_PKEY_CTX *ctx, int nid); | |
ffd89124 AS |
145 | int EVP_PKEY_CTX_set_dh_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114); |
146 | int EVP_PKEY_CTX_set_dhx_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114); | |
7165593c SL |
147 | int EVP_PKEY_CTX_set_dh_paramgen_gindex(EVP_PKEY_CTX *ctx, int gindex); |
148 | int EVP_PKEY_CTX_set_dh_paramgen_seed(EVP_PKEY_CTX *ctx, | |
149 | const unsigned char *seed, | |
150 | size_t seedlen); | |
ffd89124 AS |
151 | int EVP_PKEY_CTX_set_dh_kdf_type(EVP_PKEY_CTX *ctx, int kdf); |
152 | int EVP_PKEY_CTX_get_dh_kdf_type(EVP_PKEY_CTX *ctx); | |
153 | int EVP_PKEY_CTX_set0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT *oid); | |
154 | int EVP_PKEY_CTX_get0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT **oid); | |
155 | int EVP_PKEY_CTX_set_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); | |
156 | int EVP_PKEY_CTX_get_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); | |
157 | int EVP_PKEY_CTX_set_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int len); | |
158 | int EVP_PKEY_CTX_get_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len); | |
159 | int EVP_PKEY_CTX_set0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len); | |
90ccf05f DSH |
160 | |
161 | #include <openssl/ec.h> | |
e5a8712d | 162 | |
90ccf05f | 163 | int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); |
146ca72c | 164 | int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc); |
ffd89124 AS |
165 | int EVP_PKEY_CTX_set_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx, int cofactor_mode); |
166 | int EVP_PKEY_CTX_get_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx); | |
167 | int EVP_PKEY_CTX_set_ecdh_kdf_type(EVP_PKEY_CTX *ctx, int kdf); | |
168 | int EVP_PKEY_CTX_get_ecdh_kdf_type(EVP_PKEY_CTX *ctx); | |
169 | int EVP_PKEY_CTX_set_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); | |
170 | int EVP_PKEY_CTX_get_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); | |
171 | int EVP_PKEY_CTX_set_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int len); | |
172 | int EVP_PKEY_CTX_get_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len); | |
173 | int EVP_PKEY_CTX_set0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len); | |
90ccf05f | 174 | |
675f4cee PY |
175 | int EVP_PKEY_CTX_set1_id(EVP_PKEY_CTX *ctx, void *id, size_t id_len); |
176 | int EVP_PKEY_CTX_get1_id(EVP_PKEY_CTX *ctx, void *id); | |
177 | int EVP_PKEY_CTX_get1_id_len(EVP_PKEY_CTX *ctx, size_t *id_len); | |
178 | ||
3786d748 | 179 | Deprecated since OpenSSL 3.0, can be hidden entirely by defining |
180 | B<OPENSSL_API_COMPAT> with a suitable version value, see | |
181 | L<openssl_user_macros(7)>: | |
182 | ||
183 | #include <openssl/rsa.h> | |
184 | ||
185 | int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); | |
186 | ||
76e48c9d TM |
187 | #include <openssl/dh.h> |
188 | ||
189 | int EVP_PKEY_CTX_get0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm); | |
190 | ||
191 | #include <openssl/ec.h> | |
192 | ||
193 | int EVP_PKEY_CTX_get0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm); | |
194 | ||
90ccf05f DSH |
195 | =head1 DESCRIPTION |
196 | ||
96bb4ff9 SL |
197 | EVP_PKEY_CTX_ctrl() sends a control operation to the context I<ctx>. The key |
198 | type used must match I<keytype> if it is not -1. The parameter I<optype> is a | |
199 | mask indicating which operations the control can be applied to. | |
e72467d3 RL |
200 | The control command is indicated in I<cmd> and any additional arguments in |
201 | I<p1> and I<p2>. | |
90ccf05f | 202 | |
6f4b7663 RL |
203 | For I<cmd> = B<EVP_PKEY_CTRL_SET_MAC_KEY>, I<p1> is the length of the MAC key, |
204 | and I<p2> is the MAC key. This is used by Poly1305, SipHash, HMAC and CMAC. | |
52ad5b60 | 205 | |
90ccf05f | 206 | Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will |
96bb4ff9 | 207 | instead call one of the algorithm specific functions below. |
90ccf05f | 208 | |
96bb4ff9 | 209 | EVP_PKEY_CTX_ctrl_uint64() is a wrapper that directly passes a |
e72467d3 | 210 | uint64 value as I<p2> to EVP_PKEY_CTX_ctrl(). |
ffd89124 | 211 | |
96bb4ff9 | 212 | EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm |
e72467d3 | 213 | specific control operation to a context I<ctx> in string form. This is |
90ccf05f DSH |
214 | intended to be used for options specified on the command line or in text |
215 | files. The commands supported are documented in the openssl utility | |
e72467d3 RL |
216 | command line pages for the option I<-pkeyopt> which is supported by the |
217 | I<pkeyutl>, I<genpkey> and I<req> commands. | |
90ccf05f | 218 | |
96bb4ff9 SL |
219 | EVP_PKEY_CTX_md() sends a message digest control operation to the context |
220 | I<ctx>. The message digest is specified by its name I<md>. | |
ffd89124 | 221 | |
96bb4ff9 | 222 | EVP_PKEY_CTX_set_signature_md() sets the message digest type used |
9c45222d | 223 | in a signature. It can be used in the RSA, DSA and ECDSA algorithms. |
90ccf05f | 224 | |
96bb4ff9 | 225 | EVP_PKEY_CTX_get_signature_md()gets the message digest type used |
d45a97f4 MC |
226 | in a signature. It can be used in the RSA, DSA and ECDSA algorithms. |
227 | ||
d45a97f4 MC |
228 | Key generation typically involves setting up parameters to be used and |
229 | generating the private and public key data. Some algorithm implementations | |
96bb4ff9 SL |
230 | allow private key data to be set explicitly using EVP_PKEY_CTX_set_mac_key(). |
231 | In this case key generation is simply the process of setting up the | |
232 | parameters for the key and then setting the raw key data to the value explicitly. | |
233 | Normally applications would call L<EVP_PKEY_new_raw_private_key(3)> or similar | |
234 | functions instead. | |
d45a97f4 | 235 | |
96bb4ff9 SL |
236 | EVP_PKEY_CTX_set_mac_key() can be used with any of the algorithms supported by |
237 | the L<EVP_PKEY_new_raw_private_key(3)> function. | |
90ccf05f | 238 | |
11a1b341 MC |
239 | EVP_PKEY_CTX_set_group_name() sets the group name to I<name> for parameter and |
240 | key generation. For example for EC keys this will set the curve name and for | |
241 | DH keys it will set the name of the finite field group. | |
242 | ||
243 | EVP_PKEY_CTX_get_group_name() finds the group name that's currently | |
244 | set with I<ctx>, and writes it to the location that I<name> points at, as long | |
245 | as its size I<namelen> is large enough to store that name, including a | |
246 | terminating NUL byte. | |
247 | ||
ffd89124 AS |
248 | =head2 RSA parameters |
249 | ||
96bb4ff9 | 250 | EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for I<ctx>. |
e72467d3 | 251 | The I<pad> parameter can take the value B<RSA_PKCS1_PADDING> for PKCS#1 |
b0aae913 | 252 | padding, B<RSA_NO_PADDING> for |
ffd89124 AS |
253 | no padding, B<RSA_PKCS1_OAEP_PADDING> for OAEP padding (encrypt and |
254 | decrypt only), B<RSA_X931_PADDING> for X9.31 padding (signature operations | |
350c9235 MC |
255 | only), B<RSA_PKCS1_PSS_PADDING> (sign and verify only) and |
256 | B<RSA_PKCS1_WITH_TLS_PADDING> for TLS RSA ClientKeyExchange message padding | |
257 | (decryption only). | |
90ccf05f DSH |
258 | |
259 | Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() | |
96bb4ff9 | 260 | is used. If this function is called for PKCS#1 padding the plaintext buffer is |
90ccf05f DSH |
261 | an actual digest value and is encapsulated in a DigestInfo structure according |
262 | to PKCS#1 when signing and this structure is expected (and stripped off) when | |
263 | verifying. If this control is not used with RSA and PKCS#1 padding then the | |
264 | supplied data is used directly and not encapsulated. In the case of X9.31 | |
265 | padding for RSA the algorithm identifier byte is added or checked and removed | |
9d22666e F |
266 | if this control is called. If it is not called then the first byte of the plaintext |
267 | buffer is expected to be the algorithm identifier byte. | |
90ccf05f | 268 | |
96bb4ff9 | 269 | EVP_PKEY_CTX_get_rsa_padding() gets the RSA padding mode for I<ctx>. |
ffd89124 | 270 | |
96bb4ff9 SL |
271 | EVP_PKEY_CTX_set_rsa_pss_saltlen() sets the RSA PSS salt length to I<saltlen>. |
272 | As its name implies it is only supported for PSS padding. If this function is | |
273 | not called then the maximum salt length is used when signing and auto detection | |
274 | when verifying. Three special values are supported: | |
90ccf05f | 275 | |
6f4b7663 RL |
276 | =over 4 |
277 | ||
278 | =item B<RSA_PSS_SALTLEN_DIGEST> | |
279 | ||
280 | sets the salt length to the digest length. | |
281 | ||
282 | =item B<RSA_PSS_SALTLEN_MAX> | |
283 | ||
284 | sets the salt length to the maximum permissible value. | |
285 | ||
286 | =item B<RSA_PSS_SALTLEN_AUTO> | |
287 | ||
288 | causes the salt length to be automatically determined based on the | |
289 | B<PSS> block structure when verifying. When signing, it has the same | |
290 | meaning as B<RSA_PSS_SALTLEN_MAX>. | |
291 | ||
292 | =back | |
293 | ||
96bb4ff9 SL |
294 | EVP_PKEY_CTX_get_rsa_pss_saltlen() gets the RSA PSS salt length for I<ctx>. |
295 | The padding mode must already have been set to B<RSA_PKCS1_PSS_PADDING>. | |
ffd89124 | 296 | |
96bb4ff9 | 297 | EVP_PKEY_CTX_set_rsa_keygen_bits() sets the RSA key length for |
6f4b7663 | 298 | RSA key generation to I<bits>. If not specified 2048 bits is used. |
90ccf05f | 299 | |
3786d748 | 300 | EVP_PKEY_CTX_set1_rsa_keygen_pubexp() sets the public exponent value for RSA key |
301 | generation to the value stored in I<pubexp>. Currently it should be an odd | |
302 | integer. In accordance with the OpenSSL naming convention, the I<pubexp> pointer | |
303 | must be freed independently of the EVP_PKEY_CTX (ie, it is internally copied). | |
304 | If not specified 65537 is used. | |
305 | ||
306 | EVP_PKEY_CTX_set_rsa_keygen_pubexp() does the same as | |
307 | EVP_PKEY_CTX_set1_rsa_keygen_pubexp() except that there is no internal copy and | |
308 | therefore I<pubexp> should not be modified or freed after the call. | |
ffd89124 | 309 | |
96bb4ff9 | 310 | EVP_PKEY_CTX_set_rsa_keygen_primes() sets the number of primes for |
e72467d3 | 311 | RSA key generation to I<primes>. If not specified 2 is used. |
ffd89124 | 312 | |
96bb4ff9 | 313 | EVP_PKEY_CTX_set_rsa_mgf1_md_name() sets the MGF1 digest for RSA |
e72467d3 | 314 | padding schemes to the digest named I<mdname>. If the RSA algorithm |
d8fef6da | 315 | implementation for the selected provider supports it then the digest will be |
e72467d3 | 316 | fetched using the properties I<mdprops>. If not explicitly set the signing |
d8fef6da | 317 | digest is used. The padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING> |
ffd89124 AS |
318 | or B<RSA_PKCS1_PSS_PADDING>. |
319 | ||
96bb4ff9 | 320 | EVP_PKEY_CTX_set_rsa_mgf1_md() does the same as |
d8fef6da | 321 | EVP_PKEY_CTX_set_rsa_mgf1_md_name() except that the name of the digest is |
e72467d3 | 322 | inferred from the supplied I<md> and it is not possible to specify any |
d8fef6da MC |
323 | properties. |
324 | ||
96bb4ff9 | 325 | EVP_PKEY_CTX_get_rsa_mgf1_md_name() gets the name of the MGF1 |
e72467d3 | 326 | digest algorithm for I<ctx>. If not explicitly set the signing digest is used. |
d8fef6da MC |
327 | The padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING> or |
328 | B<RSA_PKCS1_PSS_PADDING>. | |
329 | ||
96bb4ff9 | 330 | EVP_PKEY_CTX_get_rsa_mgf1_md() does the same as |
d8fef6da MC |
331 | EVP_PKEY_CTX_get_rsa_mgf1_md_name() except that it returns a pointer to an |
332 | EVP_MD object instead. Note that only known, built-in EVP_MD objects will be | |
333 | returned. The EVP_MD object may be NULL if the digest is not one of these (such | |
334 | as a digest only implemented in a third party provider). | |
335 | ||
96bb4ff9 | 336 | EVP_PKEY_CTX_set_rsa_oaep_md_name() sets the message digest type |
e72467d3 | 337 | used in RSA OAEP to the digest named I<mdname>. If the RSA algorithm |
d8fef6da | 338 | implementation for the selected provider supports it then the digest will be |
e72467d3 | 339 | fetched using the properties I<mdprops>. The padding mode must have been set to |
ffd89124 AS |
340 | B<RSA_PKCS1_OAEP_PADDING>. |
341 | ||
96bb4ff9 | 342 | EVP_PKEY_CTX_set_rsa_oaep_md() does the same as |
d8fef6da | 343 | EVP_PKEY_CTX_set_rsa_oaep_md_name() except that the name of the digest is |
e72467d3 | 344 | inferred from the supplied I<md> and it is not possible to specify any |
d8fef6da MC |
345 | properties. |
346 | ||
96bb4ff9 | 347 | EVP_PKEY_CTX_get_rsa_oaep_md_name() gets the message digest |
e72467d3 RL |
348 | algorithm name used in RSA OAEP and stores it in the buffer I<name> which is of |
349 | size I<namelen>. The padding mode must have been set to | |
d8fef6da MC |
350 | B<RSA_PKCS1_OAEP_PADDING>. The buffer should be sufficiently large for any |
351 | expected digest algorithm names or the function will fail. | |
ffd89124 | 352 | |
96bb4ff9 | 353 | EVP_PKEY_CTX_get_rsa_oaep_md() does the same as |
d8fef6da MC |
354 | EVP_PKEY_CTX_get_rsa_oaep_md_name() except that it returns a pointer to an |
355 | EVP_MD object instead. Note that only known, built-in EVP_MD objects will be | |
356 | returned. The EVP_MD object may be NULL if the digest is not one of these (such | |
357 | as a digest only implemented in a third party provider). | |
358 | ||
96bb4ff9 | 359 | EVP_PKEY_CTX_set0_rsa_oaep_label() sets the RSA OAEP label to |
e72467d3 | 360 | I<label> and its length to I<len>. If I<label> is NULL or I<len> is 0, |
ffd89124 | 361 | the label is cleared. The library takes ownership of the label so the |
e72467d3 | 362 | caller should not free the original memory pointed to by I<label>. |
ffd89124 AS |
363 | The padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING>. |
364 | ||
96bb4ff9 | 365 | EVP_PKEY_CTX_get0_rsa_oaep_label() gets the RSA OAEP label to |
e72467d3 | 366 | I<label>. The return value is the label length. The padding mode |
ffd89124 AS |
367 | must have been set to B<RSA_PKCS1_OAEP_PADDING>. The resulting pointer is owned |
368 | by the library and should not be freed by the caller. | |
369 | ||
350c9235 MC |
370 | B<RSA_PKCS1_WITH_TLS_PADDING> is used when decrypting an RSA encrypted TLS |
371 | pre-master secret in a TLS ClientKeyExchange message. It is the same as | |
372 | RSA_PKCS1_PADDING except that it additionally verifies that the result is the | |
373 | correct length and the first two bytes are the protocol version initially | |
374 | requested by the client. If the encrypted content is publicly invalid then the | |
375 | decryption will fail. However, if the padding checks fail then decryption will | |
376 | still appear to succeed but a random TLS premaster secret will be returned | |
377 | instead. This padding mode accepts two parameters which can be set using the | |
378 | L<EVP_PKEY_CTX_set_params(3)> function. These are | |
379 | OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION and | |
380 | OSSL_ASYM_CIPHER_PARAM_TLS_NEGOTIATED_VERSION, both of which are expected to be | |
381 | unsigned integers. Normally only the first of these will be set and represents | |
382 | the TLS protocol version that was first requested by the client (e.g. 0x0303 for | |
383 | TLSv1.2, 0x0302 for TLSv1.1 etc). Historically some buggy clients would use the | |
384 | negotiated protocol version instead of the protocol version first requested. If | |
385 | this behaviour should be tolerated then | |
386 | OSSL_ASYM_CIPHER_PARAM_TLS_NEGOTIATED_VERSION should be set to the actual | |
387 | negotiated protocol version. Otherwise it should be left unset. | |
388 | ||
ffd89124 | 389 | =head2 DSA parameters |
90ccf05f | 390 | |
31d2daec SL |
391 | EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used for DSA |
392 | parameter generation to B<nbits>. If not specified, 2048 is used. | |
a97faad7 | 393 | |
31d2daec SL |
394 | EVP_PKEY_CTX_set_dsa_paramgen_q_bits() sets the number of bits in the subprime |
395 | parameter I<q> for DSA parameter generation to I<qbits>. If not specified, 224 | |
396 | is used. If a digest function is specified below, this parameter is ignored and | |
397 | instead, the number of bits in I<q> matches the size of the digest. | |
a97faad7 | 398 | |
31d2daec SL |
399 | EVP_PKEY_CTX_set_dsa_paramgen_md() sets the digest function used for DSA |
400 | parameter generation to I<md>. If not specified, one of SHA-1, SHA-224, or | |
e72467d3 | 401 | SHA-256 is selected to match the bit length of I<q> above. |
90ccf05f | 402 | |
31d2daec SL |
403 | EVP_PKEY_CTX_set_dsa_paramgen_md_props() sets the digest function used for DSA |
404 | parameter generation using I<md_name> and I<md_properties> to retrieve the | |
405 | digest from a provider. | |
b03ec3b5 SL |
406 | If not specified, I<md_name> will be set to one of SHA-1, SHA-224, or |
407 | SHA-256 depending on the bit length of I<q> above. I<md_properties> is a | |
408 | property query string that has a default value of '' if not specified. | |
409 | ||
31d2daec SL |
410 | EVP_PKEY_CTX_set_dsa_paramgen_gindex() sets the I<gindex> used by the generator |
411 | G. The default value is -1 which uses unverifiable g, otherwise a positive value | |
412 | uses verifiable g. This value must be saved if key validation of g is required, | |
413 | since it is not part of a persisted key. | |
b03ec3b5 | 414 | |
31d2daec SL |
415 | EVP_PKEY_CTX_set_dsa_paramgen_seed() sets the I<seed> to use for generation |
416 | rather than using a randomly generated value for the seed. This is useful for | |
417 | testing purposes only and can fail if the seed does not produce primes for both | |
418 | p & q on its first iteration. This value must be saved if key validation of | |
419 | p, q, and verifiable g are required, since it is not part of a persisted key. | |
b03ec3b5 | 420 | |
31d2daec SL |
421 | EVP_PKEY_CTX_set_dsa_paramgen_type() sets the generation type to use FIPS186-4 |
422 | generation if I<name> is "fips186_4", or FIPS186-2 generation if I<name> is | |
c2bd8d27 MC |
423 | "fips186_2". The default value for the default provider is "fips186_2". The |
424 | default value for the FIPS provider is "fips186_4". | |
b03ec3b5 | 425 | |
ffd89124 AS |
426 | =head2 DH parameters |
427 | ||
96bb4ff9 SL |
428 | EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH prime |
429 | parameter I<p> for DH parameter generation. If this function is not called then | |
430 | 2048 is used. Only accepts lengths greater than or equal to 256. | |
ffd89124 | 431 | |
96bb4ff9 | 432 | EVP_PKEY_CTX_set_dh_paramgen_subprime_len() sets the length of the DH |
e72467d3 | 433 | optional subprime parameter I<q> for DH parameter generation. The default is |
96bb4ff9 SL |
434 | 256 if the prime is at least 2048 bits long or 160 otherwise. The DH paramgen |
435 | type must have been set to "fips186_4". | |
90ccf05f | 436 | |
96bb4ff9 SL |
437 | EVP_PKEY_CTX_set_dh_paramgen_generator() sets DH generator to I<gen> for DH |
438 | parameter generation. If not specified 2 is used. | |
90ccf05f | 439 | |
96bb4ff9 SL |
440 | EVP_PKEY_CTX_set_dh_paramgen_type() sets the key type for DH parameter |
441 | generation. The supported parameters are: | |
f11f86f6 SL |
442 | |
443 | =over 4 | |
444 | ||
7165593c SL |
445 | =item B<DH_PARAMGEN_TYPE_GROUP> |
446 | ||
447 | Use a named group. If only the safe prime parameter I<p> is set this can be | |
448 | used to select a ffdhe safe prime group of the correct size. | |
449 | ||
450 | =item B<DH_PARAMGEN_TYPE_FIPS_186_4> | |
f11f86f6 | 451 | |
7165593c | 452 | FIPS186-4 FFC parameter generator. |
f11f86f6 SL |
453 | |
454 | =item B<DH_PARAMGEN_TYPE_FIPS_186_2> | |
455 | ||
456 | FIPS186-2 FFC parameter generator (X9.42 DH). | |
457 | ||
7165593c | 458 | =item B<DH_PARAMGEN_TYPE_GENERATOR> |
f11f86f6 | 459 | |
7165593c | 460 | Uses a safe prime generator g (PKCS#3 format). |
f11f86f6 SL |
461 | |
462 | =back | |
463 | ||
f1d66708 MC |
464 | The default in the default provider is B<DH_PARAMGEN_TYPE_GENERATOR> for the |
465 | "DH" keytype, and B<DH_PARAMGEN_TYPE_FIPS_186_2> for the "DHX" keytype. In the | |
466 | FIPS provider the default value is B<DH_PARAMGEN_TYPE_GROUP> for the "DH" | |
467 | keytype and <B<DH_PARAMGEN_TYPE_FIPS_186_4> for the "DHX" keytype. | |
ffd89124 | 468 | |
31d2daec SL |
469 | EVP_PKEY_CTX_set_dh_paramgen_gindex() sets the I<gindex> used by the generator G. |
470 | The default value is -1 which uses unverifiable g, otherwise a positive value | |
471 | uses verifiable g. This value must be saved if key validation of g is required, | |
472 | since it is not part of a persisted key. | |
7165593c | 473 | |
31d2daec SL |
474 | EVP_PKEY_CTX_set_dh_paramgen_seed() sets the I<seed> to use for generation |
475 | rather than using a randomly generated value for the seed. This is useful for | |
476 | testing purposes only and can fail if the seed does not produce primes for both | |
477 | p & q on its first iteration. This value must be saved if key validation of p, q, | |
478 | and verifiable g are required, since it is not part of a persisted key. | |
7165593c | 479 | |
96bb4ff9 | 480 | EVP_PKEY_CTX_set_dh_pad() sets the DH padding mode. |
e72467d3 RL |
481 | If I<pad> is 1 the shared secret is padded with zeros up to the size of the DH |
482 | prime I<p>. | |
483 | If I<pad> is zero (the default) then no padding is performed. | |
5368bf05 DSH |
484 | |
485 | EVP_PKEY_CTX_set_dh_nid() sets the DH parameters to values corresponding to | |
e72467d3 | 486 | I<nid> as defined in RFC7919 or RFC3526. The I<nid> parameter must be |
ca2bf555 SL |
487 | B<NID_ffdhe2048>, B<NID_ffdhe3072>, B<NID_ffdhe4096>, B<NID_ffdhe6144>, |
488 | B<NID_ffdhe8192>, B<NID_modp_1536>, B<NID_modp_2048>, B<NID_modp_3072>, | |
489 | B<NID_modp_4096>, B<NID_modp_6144>, B<NID_modp_8192> or B<NID_undef> to clear | |
96bb4ff9 | 490 | the stored value. This function can be called during parameter or key generation. |
ffd89124 AS |
491 | The nid parameter and the rfc5114 parameter are mutually exclusive. |
492 | ||
96bb4ff9 SL |
493 | EVP_PKEY_CTX_set_dh_rfc5114() and EVP_PKEY_CTX_set_dhx_rfc5114() both set the |
494 | DH parameters to the values defined in RFC5114. The I<rfc5114> parameter must | |
495 | be 1, 2 or 3 corresponding to RFC5114 sections 2.1, 2.2 and 2.3. or 0 to clear | |
496 | the stored value. This macro can be called during parameter generation. The | |
497 | I<ctx> must have a key type of B<EVP_PKEY_DHX>. | |
ffd89124 AS |
498 | The rfc5114 parameter and the nid parameter are mutually exclusive. |
499 | ||
500 | =head2 DH key derivation function parameters | |
501 | ||
e72467d3 | 502 | Note that all of the following functions require that the I<ctx> parameter has |
ffd89124 AS |
503 | a private key type of B<EVP_PKEY_DHX>. When using key derivation, the output of |
504 | EVP_PKEY_derive() is the output of the KDF instead of the DH shared secret. | |
505 | The KDF output is typically used as a Key Encryption Key (KEK) that in turn | |
506 | encrypts a Content Encryption Key (CEK). | |
507 | ||
31d2daec SL |
508 | EVP_PKEY_CTX_set_dh_kdf_type() sets the key derivation function type to I<kdf> |
509 | for DH key derivation. Possible values are B<EVP_PKEY_DH_KDF_NONE> and | |
510 | B<EVP_PKEY_DH_KDF_X9_42> which uses the key derivation specified in RFC2631 | |
ffd89124 | 511 | (based on the keying algorithm described in X9.42). When using key derivation, |
e72467d3 | 512 | the I<kdf_oid>, I<kdf_md> and I<kdf_outlen> parameters must also be specified. |
ffd89124 | 513 | |
31d2daec SL |
514 | EVP_PKEY_CTX_get_dh_kdf_type() gets the key derivation function type for I<ctx> |
515 | used for DH key derivation. Possible values are B<EVP_PKEY_DH_KDF_NONE> and | |
516 | B<EVP_PKEY_DH_KDF_X9_42>. | |
ffd89124 | 517 | |
31d2daec SL |
518 | EVP_PKEY_CTX_set0_dh_kdf_oid() sets the key derivation function object |
519 | identifier to I<oid> for DH key derivation. This OID should identify the | |
520 | algorithm to be used with the Content Encryption Key. | |
ffd89124 | 521 | The library takes ownership of the object identifier so the caller should not |
e72467d3 | 522 | free the original memory pointed to by I<oid>. |
ffd89124 | 523 | |
31d2daec SL |
524 | EVP_PKEY_CTX_get0_dh_kdf_oid() gets the key derivation function oid for I<ctx> |
525 | used for DH key derivation. The resulting pointer is owned by the library and | |
526 | should not be freed by the caller. | |
ffd89124 | 527 | |
31d2daec SL |
528 | EVP_PKEY_CTX_set_dh_kdf_md() sets the key derivation function message digest to |
529 | I<md> for DH key derivation. Note that RFC2631 specifies that this digest should | |
530 | be SHA1 but OpenSSL tolerates other digests. | |
ffd89124 | 531 | |
31d2daec SL |
532 | EVP_PKEY_CTX_get_dh_kdf_md() gets the key derivation function message digest for |
533 | I<ctx> used for DH key derivation. | |
ffd89124 | 534 | |
31d2daec SL |
535 | EVP_PKEY_CTX_set_dh_kdf_outlen() sets the key derivation function output length |
536 | to I<len> for DH key derivation. | |
ffd89124 | 537 | |
31d2daec SL |
538 | EVP_PKEY_CTX_get_dh_kdf_outlen() gets the key derivation function output length |
539 | for I<ctx> used for DH key derivation. | |
ffd89124 | 540 | |
31d2daec SL |
541 | EVP_PKEY_CTX_set0_dh_kdf_ukm() sets the user key material to I<ukm> and its |
542 | length to I<len> for DH key derivation. This parameter is optional and | |
543 | corresponds to the partyAInfo field in RFC2631 terms. The specification | |
ffd89124 AS |
544 | requires that it is 512 bits long but this is not enforced by OpenSSL. |
545 | The library takes ownership of the user key material so the caller should not | |
e72467d3 | 546 | free the original memory pointed to by I<ukm>. |
ffd89124 | 547 | |
31d2daec | 548 | EVP_PKEY_CTX_get0_dh_kdf_ukm() gets the user key material for I<ctx>. |
ffd89124 AS |
549 | The return value is the user key material length. The resulting pointer is owned |
550 | by the library and should not be freed by the caller. | |
551 | ||
552 | =head2 EC parameters | |
5368bf05 | 553 | |
11a1b341 MC |
554 | Use EVP_PKEY_CTX_set_group_name() (described above) to set the curve name to |
555 | I<name> for parameter and key generation. | |
10d756a7 RL |
556 | |
557 | EVP_PKEY_CTX_set_ec_paramgen_curve_nid() does the same as | |
11a1b341 MC |
558 | EVP_PKEY_CTX_set_group_name(), but is specific to EC and uses a I<nid> rather |
559 | than a name string. | |
10d756a7 | 560 | |
11a1b341 | 561 | For EC parameter generation, one of EVP_PKEY_CTX_set_group_name() |
10d756a7 RL |
562 | or EVP_PKEY_CTX_set_ec_paramgen_curve_nid() must be called or an error occurs |
563 | because there is no default curve. | |
564 | These function can also be called to set the curve explicitly when | |
146ca72c DSH |
565 | generating an EC key. |
566 | ||
11a1b341 MC |
567 | EVP_PKEY_CTX_get_group_name() (described above) can be used to obtain the curve |
568 | name that's currently set with I<ctx>. | |
10d756a7 | 569 | |
33dd828d SL |
570 | EVP_PKEY_CTX_set_ec_param_enc() sets the EC parameter encoding to I<param_enc> |
571 | when generating EC parameters or an EC key. The encoding can be | |
146ca72c DSH |
572 | B<OPENSSL_EC_EXPLICIT_CURVE> for explicit parameters (the default in versions |
573 | of OpenSSL before 1.1.0) or B<OPENSSL_EC_NAMED_CURVE> to use named curve form. | |
574 | For maximum compatibility the named curve form should be used. Note: the | |
fc5ecadd | 575 | B<OPENSSL_EC_NAMED_CURVE> value was added in OpenSSL 1.1.0; previous |
146ca72c | 576 | versions should use 0 instead. |
90ccf05f | 577 | |
ffd89124 AS |
578 | =head2 ECDH parameters |
579 | ||
96bb4ff9 SL |
580 | EVP_PKEY_CTX_set_ecdh_cofactor_mode() sets the cofactor mode to I<cofactor_mode> |
581 | for ECDH key derivation. Possible values are 1 to enable cofactor | |
582 | key derivation, 0 to disable it and -1 to clear the stored cofactor mode and | |
583 | fallback to the private key cofactor mode. | |
ffd89124 | 584 | |
96bb4ff9 SL |
585 | EVP_PKEY_CTX_get_ecdh_cofactor_mode() returns the cofactor mode for I<ctx> used |
586 | for ECDH key derivation. Possible values are 1 when cofactor key derivation is | |
587 | enabled and 0 otherwise. | |
ffd89124 AS |
588 | |
589 | =head2 ECDH key derivation function parameters | |
590 | ||
96bb4ff9 SL |
591 | EVP_PKEY_CTX_set_ecdh_kdf_type() sets the key derivation function type to |
592 | I<kdf> for ECDH key derivation. Possible values are B<EVP_PKEY_ECDH_KDF_NONE> | |
ffd89124 | 593 | and B<EVP_PKEY_ECDH_KDF_X9_63> which uses the key derivation specified in X9.63. |
e72467d3 | 594 | When using key derivation, the I<kdf_md> and I<kdf_outlen> parameters must |
ffd89124 AS |
595 | also be specified. |
596 | ||
96bb4ff9 SL |
597 | EVP_PKEY_CTX_get_ecdh_kdf_type() returns the key derivation function type for |
598 | I<ctx> used for ECDH key derivation. Possible values are | |
ffd89124 AS |
599 | B<EVP_PKEY_ECDH_KDF_NONE> and B<EVP_PKEY_ECDH_KDF_X9_63>. |
600 | ||
96bb4ff9 SL |
601 | EVP_PKEY_CTX_set_ecdh_kdf_md() sets the key derivation function message digest |
602 | to I<md> for ECDH key derivation. Note that X9.63 specifies that this digest | |
603 | should be SHA1 but OpenSSL tolerates other digests. | |
ffd89124 | 604 | |
96bb4ff9 SL |
605 | EVP_PKEY_CTX_get_ecdh_kdf_md() gets the key derivation function message digest |
606 | for I<ctx> used for ECDH key derivation. | |
ffd89124 | 607 | |
96bb4ff9 SL |
608 | EVP_PKEY_CTX_set_ecdh_kdf_outlen() sets the key derivation function output |
609 | length to I<len> for ECDH key derivation. | |
ffd89124 | 610 | |
96bb4ff9 SL |
611 | EVP_PKEY_CTX_get_ecdh_kdf_outlen() gets the key derivation function output |
612 | length for I<ctx> used for ECDH key derivation. | |
ffd89124 | 613 | |
96bb4ff9 SL |
614 | EVP_PKEY_CTX_set0_ecdh_kdf_ukm() sets the user key material to I<ukm> for ECDH |
615 | key derivation. This parameter is optional and corresponds to the shared info in | |
616 | X9.63 terms. The library takes ownership of the user key material so the caller | |
617 | should not free the original memory pointed to by I<ukm>. | |
ffd89124 | 618 | |
96bb4ff9 | 619 | EVP_PKEY_CTX_get0_ecdh_kdf_ukm() gets the user key material for I<ctx>. |
ffd89124 AS |
620 | The return value is the user key material length. The resulting pointer is owned |
621 | by the library and should not be freed by the caller. | |
622 | ||
623 | =head2 Other parameters | |
624 | ||
96bb4ff9 SL |
625 | EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len() |
626 | are used to manipulate the special identifier field for specific signature | |
e72467d3 RL |
627 | algorithms such as SM2. The EVP_PKEY_CTX_set1_id() sets an ID pointed by I<id> with |
628 | the length I<id_len> to the library. The library takes a copy of the id so that | |
96bb4ff9 SL |
629 | the caller can safely free the original memory pointed to by I<id>. |
630 | EVP_PKEY_CTX_get1_id_len() returns the length of the ID set via a previous call | |
631 | to EVP_PKEY_CTX_set1_id(). The length is usually used to allocate adequate | |
632 | memory for further calls to EVP_PKEY_CTX_get1_id(). EVP_PKEY_CTX_get1_id() | |
633 | returns the previously set ID value to caller in I<id>. The caller should | |
e72467d3 | 634 | allocate adequate memory space for the I<id> before calling EVP_PKEY_CTX_get1_id(). |
675f4cee | 635 | |
80f4fd18 SL |
636 | EVP_PKEY_CTX_set_kem_op() sets the KEM operation to run. This can be set after |
637 | EVP_PKEY_encapsulate_init() or EVP_PKEY_decapsulate_init() to select the | |
638 | kem operation. RSA is the only key type that supports encapsulation currently, | |
639 | and as there is no default operation for the RSA type, this function must be | |
640 | called before EVP_PKEY_encapsulate() or EVP_PKEY_decapsulate(). | |
641 | ||
90ccf05f DSH |
642 | =head1 RETURN VALUES |
643 | ||
96bb4ff9 SL |
644 | All other functions described on this page return a positive value for success |
645 | and 0 or a negative value for failure. In particular a return value of -2 | |
646 | indicates the operation is not supported by the public key algorithm. | |
90ccf05f DSH |
647 | |
648 | =head1 SEE ALSO | |
649 | ||
b8086652 | 650 | L<EVP_PKEY_CTX_set_params(3)>, |
9b86974e RS |
651 | L<EVP_PKEY_CTX_new(3)>, |
652 | L<EVP_PKEY_encrypt(3)>, | |
653 | L<EVP_PKEY_decrypt(3)>, | |
654 | L<EVP_PKEY_sign(3)>, | |
655 | L<EVP_PKEY_verify(3)>, | |
656 | L<EVP_PKEY_verify_recover(3)>, | |
ffd89124 | 657 | L<EVP_PKEY_derive(3)>, |
9b86974e | 658 | L<EVP_PKEY_keygen(3)> |
80f4fd18 SL |
659 | L<EVP_PKEY_encapsulate(3)> |
660 | L<EVP_PKEY_decapsulate(3)> | |
90ccf05f DSH |
661 | |
662 | =head1 HISTORY | |
663 | ||
d8fef6da | 664 | EVP_PKEY_CTX_get_rsa_oaep_md_name(), EVP_PKEY_CTX_get_rsa_mgf1_md_name(), |
b03ec3b5 SL |
665 | EVP_PKEY_CTX_set_rsa_mgf1_md_name(), EVP_PKEY_CTX_set_rsa_oaep_md_name(), |
666 | EVP_PKEY_CTX_set_dsa_paramgen_md_props(), EVP_PKEY_CTX_set_dsa_paramgen_gindex(), | |
11a1b341 MC |
667 | EVP_PKEY_CTX_set_dsa_paramgen_type(), EVP_PKEY_CTX_set_dsa_paramgen_seed(), |
668 | EVP_PKEY_CTX_set_group_name() and EVP_PKEY_CTX_get_group_name() | |
b03ec3b5 | 669 | were added in OpenSSL 3.0. |
d8fef6da MC |
670 | |
671 | The EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and | |
672 | EVP_PKEY_CTX_get1_id_len() macros were added in 1.1.1, other functions were | |
673 | added in OpenSSL 1.0.0. | |
12df11bd | 674 | |
96bb4ff9 SL |
675 | In OpenSSL 1.1.1 and below the functions were mostly macros. |
676 | From OpenSSL 3.0 they are all functions. | |
677 | ||
76e48c9d TM |
678 | EVP_PKEY_CTX_set_rsa_keygen_pubexp(), EVP_PKEY_CTX_get0_dh_kdf_ukm(), |
679 | and EVP_PKEY_CTX_get0_ecdh_kdf_ukm() were deprecated in OpenSSL 3.0. | |
680 | ||
e2f92610 RS |
681 | =head1 COPYRIGHT |
682 | ||
8020d79b | 683 | Copyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 684 | |
4746f25a | 685 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
686 | this file except in compliance with the License. You can obtain a copy |
687 | in the file LICENSE in the source distribution or at | |
688 | L<https://www.openssl.org/source/license.html>. | |
689 | ||
690 | =cut |