]>
Commit | Line | Data |
---|---|---|
72b60351 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
2cafb1df | 5 | EVP_CIPHER_fetch, |
550f974a RL |
6 | EVP_CIPHER_up_ref, |
7 | EVP_CIPHER_free, | |
8fa4d95e RT |
8 | EVP_CIPHER_CTX_new, |
9 | EVP_CIPHER_CTX_reset, | |
10 | EVP_CIPHER_CTX_free, | |
0324ae3e P |
11 | EVP_CIPHER_CTX_dup, |
12 | EVP_CIPHER_CTX_copy, | |
8fa4d95e | 13 | EVP_EncryptInit_ex, |
1036bb64 | 14 | EVP_EncryptInit_ex2, |
8fa4d95e RT |
15 | EVP_EncryptUpdate, |
16 | EVP_EncryptFinal_ex, | |
17 | EVP_DecryptInit_ex, | |
1036bb64 | 18 | EVP_DecryptInit_ex2, |
8fa4d95e RT |
19 | EVP_DecryptUpdate, |
20 | EVP_DecryptFinal_ex, | |
21 | EVP_CipherInit_ex, | |
1036bb64 | 22 | EVP_CipherInit_ex2, |
8fa4d95e RT |
23 | EVP_CipherUpdate, |
24 | EVP_CipherFinal_ex, | |
25 | EVP_CIPHER_CTX_set_key_length, | |
26 | EVP_CIPHER_CTX_ctrl, | |
27 | EVP_EncryptInit, | |
28 | EVP_EncryptFinal, | |
29 | EVP_DecryptInit, | |
30 | EVP_DecryptFinal, | |
31 | EVP_CipherInit, | |
32 | EVP_CipherFinal, | |
f7397f0d | 33 | EVP_Cipher, |
8fa4d95e RT |
34 | EVP_get_cipherbyname, |
35 | EVP_get_cipherbynid, | |
36 | EVP_get_cipherbyobj, | |
7cfa1717 | 37 | EVP_CIPHER_is_a, |
ed576acd TM |
38 | EVP_CIPHER_get0_name, |
39 | EVP_CIPHER_get0_description, | |
f651c727 | 40 | EVP_CIPHER_names_do_all, |
ed576acd TM |
41 | EVP_CIPHER_get0_provider, |
42 | EVP_CIPHER_get_nid, | |
ae3ff60e RL |
43 | EVP_CIPHER_get_params, |
44 | EVP_CIPHER_gettable_params, | |
ed576acd TM |
45 | EVP_CIPHER_get_block_size, |
46 | EVP_CIPHER_get_key_length, | |
47 | EVP_CIPHER_get_iv_length, | |
48 | EVP_CIPHER_get_flags, | |
49 | EVP_CIPHER_get_mode, | |
50 | EVP_CIPHER_get_type, | |
8fa4d95e | 51 | EVP_CIPHER_CTX_cipher, |
f6c95e46 RS |
52 | EVP_CIPHER_CTX_get0_cipher, |
53 | EVP_CIPHER_CTX_get1_cipher, | |
ed576acd TM |
54 | EVP_CIPHER_CTX_get0_name, |
55 | EVP_CIPHER_CTX_get_nid, | |
ae3ff60e | 56 | EVP_CIPHER_CTX_get_params, |
41f7ecf3 | 57 | EVP_CIPHER_gettable_ctx_params, |
fe20a66e | 58 | EVP_CIPHER_CTX_gettable_params, |
ae3ff60e | 59 | EVP_CIPHER_CTX_set_params, |
41f7ecf3 | 60 | EVP_CIPHER_settable_ctx_params, |
fe20a66e | 61 | EVP_CIPHER_CTX_settable_params, |
ed576acd TM |
62 | EVP_CIPHER_CTX_get_block_size, |
63 | EVP_CIPHER_CTX_get_key_length, | |
64 | EVP_CIPHER_CTX_get_iv_length, | |
65 | EVP_CIPHER_CTX_get_tag_length, | |
8fa4d95e RT |
66 | EVP_CIPHER_CTX_get_app_data, |
67 | EVP_CIPHER_CTX_set_app_data, | |
8fa4d95e | 68 | EVP_CIPHER_CTX_flags, |
7f9537d5 SL |
69 | EVP_CIPHER_CTX_set_flags, |
70 | EVP_CIPHER_CTX_clear_flags, | |
71 | EVP_CIPHER_CTX_test_flags, | |
ed576acd TM |
72 | EVP_CIPHER_CTX_get_type, |
73 | EVP_CIPHER_CTX_get_mode, | |
74 | EVP_CIPHER_CTX_get_num, | |
75 | EVP_CIPHER_CTX_set_num, | |
76 | EVP_CIPHER_CTX_is_encrypting, | |
8fa4d95e RT |
77 | EVP_CIPHER_param_to_asn1, |
78 | EVP_CIPHER_asn1_to_param, | |
79 | EVP_CIPHER_CTX_set_padding, | |
c540f00f | 80 | EVP_enc_null, |
31b7f23d TM |
81 | EVP_CIPHER_do_all_provided, |
82 | EVP_CIPHER_nid, | |
83 | EVP_CIPHER_name, | |
84 | EVP_CIPHER_block_size, | |
85 | EVP_CIPHER_key_length, | |
86 | EVP_CIPHER_iv_length, | |
87 | EVP_CIPHER_flags, | |
88 | EVP_CIPHER_mode, | |
89 | EVP_CIPHER_type, | |
90 | EVP_CIPHER_CTX_encrypting, | |
91 | EVP_CIPHER_CTX_nid, | |
92 | EVP_CIPHER_CTX_block_size, | |
93 | EVP_CIPHER_CTX_key_length, | |
94 | EVP_CIPHER_CTX_iv_length, | |
95 | EVP_CIPHER_CTX_tag_length, | |
96 | EVP_CIPHER_CTX_num, | |
97 | EVP_CIPHER_CTX_type, | |
98 | EVP_CIPHER_CTX_mode | |
8fa4d95e | 99 | - EVP cipher routines |
72b60351 DSH |
100 | |
101 | =head1 SYNOPSIS | |
102 | ||
bb82531f | 103 | =for openssl generic |
b97fdb57 | 104 | |
72b60351 DSH |
105 | #include <openssl/evp.h> |
106 | ||
b4250010 | 107 | EVP_CIPHER *EVP_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, |
2cafb1df | 108 | const char *properties); |
550f974a RL |
109 | int EVP_CIPHER_up_ref(EVP_CIPHER *cipher); |
110 | void EVP_CIPHER_free(EVP_CIPHER *cipher); | |
05fdb8d3 RL |
111 | EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void); |
112 | int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx); | |
113 | void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx); | |
0324ae3e P |
114 | EVP_CIPHER_CTX *EVP_CIPHER_CTX_dup(const EVP_CIPHER_CTX *in); |
115 | int EVP_CIPHER_CTX_copy(EVP_CIPHER_CTX *out, const EVP_CIPHER_CTX *in); | |
3811eed8 DSH |
116 | |
117 | int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | |
b38fa985 | 118 | ENGINE *impl, const unsigned char *key, const unsigned char *iv); |
1036bb64 P |
119 | int EVP_EncryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
120 | const unsigned char *key, const unsigned char *iv, | |
121 | const OSSL_PARAM params[]); | |
a91dedca | 122 | int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, |
7bbb0050 | 123 | int *outl, const unsigned char *in, int inl); |
e9b77246 | 124 | int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); |
3811eed8 DSH |
125 | |
126 | int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | |
b38fa985 | 127 | ENGINE *impl, const unsigned char *key, const unsigned char *iv); |
1036bb64 P |
128 | int EVP_DecryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
129 | const unsigned char *key, const unsigned char *iv, | |
130 | const OSSL_PARAM params[]); | |
3811eed8 | 131 | int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, |
7bbb0050 | 132 | int *outl, const unsigned char *in, int inl); |
e9b77246 | 133 | int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); |
3811eed8 DSH |
134 | |
135 | int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | |
b38fa985 | 136 | ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc); |
1036bb64 P |
137 | int EVP_CipherInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
138 | const unsigned char *key, const unsigned char *iv, | |
139 | int enc, const OSSL_PARAM params[]); | |
3811eed8 | 140 | int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, |
b38fa985 | 141 | int *outl, const unsigned char *in, int inl); |
e9b77246 | 142 | int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); |
3811eed8 DSH |
143 | |
144 | int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | |
b38fa985 | 145 | const unsigned char *key, const unsigned char *iv); |
e9b77246 | 146 | int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); |
4d524e10 | 147 | |
a91dedca | 148 | int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
b38fa985 | 149 | const unsigned char *key, const unsigned char *iv); |
e9b77246 | 150 | int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); |
4d524e10 | 151 | |
a91dedca | 152 | int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
b38fa985 | 153 | const unsigned char *key, const unsigned char *iv, int enc); |
e9b77246 | 154 | int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); |
72b60351 | 155 | |
f7397f0d RL |
156 | int EVP_Cipher(EVP_CIPHER_CTX *ctx, unsigned char *out, |
157 | const unsigned char *in, unsigned int inl); | |
158 | ||
f2e5ca84 | 159 | int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding); |
a91dedca | 160 | int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen); |
97aede68 | 161 | int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int cmd, int p1, void *p2); |
5c5eb286 | 162 | int EVP_CIPHER_CTX_rand_key(EVP_CIPHER_CTX *ctx, unsigned char *key); |
7f9537d5 SL |
163 | void EVP_CIPHER_CTX_set_flags(EVP_CIPHER_CTX *ctx, int flags); |
164 | void EVP_CIPHER_CTX_clear_flags(EVP_CIPHER_CTX *ctx, int flags); | |
165 | int EVP_CIPHER_CTX_test_flags(const EVP_CIPHER_CTX *ctx, int flags); | |
72b60351 DSH |
166 | |
167 | const EVP_CIPHER *EVP_get_cipherbyname(const char *name); | |
91da5e77 RS |
168 | const EVP_CIPHER *EVP_get_cipherbynid(int nid); |
169 | const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a); | |
170 | ||
ed576acd | 171 | int EVP_CIPHER_get_nid(const EVP_CIPHER *e); |
7cfa1717 | 172 | int EVP_CIPHER_is_a(const EVP_CIPHER *cipher, const char *name); |
d84f5515 MC |
173 | int EVP_CIPHER_names_do_all(const EVP_CIPHER *cipher, |
174 | void (*fn)(const char *name, void *data), | |
175 | void *data); | |
ed576acd TM |
176 | const char *EVP_CIPHER_get0_name(const EVP_CIPHER *cipher); |
177 | const char *EVP_CIPHER_get0_description(const EVP_CIPHER *cipher); | |
178 | const OSSL_PROVIDER *EVP_CIPHER_get0_provider(const EVP_CIPHER *cipher); | |
179 | int EVP_CIPHER_get_block_size(const EVP_CIPHER *e); | |
180 | int EVP_CIPHER_get_key_length(const EVP_CIPHER *e); | |
181 | int EVP_CIPHER_get_iv_length(const EVP_CIPHER *e); | |
182 | unsigned long EVP_CIPHER_get_flags(const EVP_CIPHER *e); | |
183 | unsigned long EVP_CIPHER_get_mode(const EVP_CIPHER *e); | |
184 | int EVP_CIPHER_get_type(const EVP_CIPHER *cipher); | |
a91dedca | 185 | |
f6c95e46 RS |
186 | const EVP_CIPHER *EVP_CIPHER_CTX_get0_cipher(const EVP_CIPHER_CTX *ctx); |
187 | EVP_CIPHER *EVP_CIPHER_CTX_get1_cipher(const EVP_CIPHER_CTX *ctx); | |
ed576acd TM |
188 | int EVP_CIPHER_CTX_get_nid(const EVP_CIPHER_CTX *ctx); |
189 | const char *EVP_CIPHER_CTX_get0_name(const EVP_CIPHER_CTX *ctx); | |
ae3ff60e RL |
190 | |
191 | int EVP_CIPHER_get_params(EVP_CIPHER *cipher, OSSL_PARAM params[]); | |
192 | int EVP_CIPHER_CTX_set_params(EVP_CIPHER_CTX *ctx, const OSSL_PARAM params[]); | |
193 | int EVP_CIPHER_CTX_get_params(EVP_CIPHER_CTX *ctx, OSSL_PARAM params[]); | |
194 | const OSSL_PARAM *EVP_CIPHER_gettable_params(const EVP_CIPHER *cipher); | |
41f7ecf3 P |
195 | const OSSL_PARAM *EVP_CIPHER_settable_ctx_params(const EVP_CIPHER *cipher); |
196 | const OSSL_PARAM *EVP_CIPHER_gettable_ctx_params(const EVP_CIPHER *cipher); | |
fe20a66e P |
197 | const OSSL_PARAM *EVP_CIPHER_CTX_settable_params(EVP_CIPHER_CTX *ctx); |
198 | const OSSL_PARAM *EVP_CIPHER_CTX_gettable_params(EVP_CIPHER_CTX *ctx); | |
ed576acd TM |
199 | int EVP_CIPHER_CTX_get_block_size(const EVP_CIPHER_CTX *ctx); |
200 | int EVP_CIPHER_CTX_get_key_length(const EVP_CIPHER_CTX *ctx); | |
201 | int EVP_CIPHER_CTX_get_iv_length(const EVP_CIPHER_CTX *ctx); | |
202 | int EVP_CIPHER_CTX_get_tag_length(const EVP_CIPHER_CTX *ctx); | |
05fdb8d3 RL |
203 | void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx); |
204 | void EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data); | |
ed576acd TM |
205 | int EVP_CIPHER_CTX_get_type(const EVP_CIPHER_CTX *ctx); |
206 | int EVP_CIPHER_CTX_get_mode(const EVP_CIPHER_CTX *ctx); | |
207 | int EVP_CIPHER_CTX_get_num(const EVP_CIPHER_CTX *ctx); | |
208 | int EVP_CIPHER_CTX_set_num(EVP_CIPHER_CTX *ctx, int num); | |
209 | int EVP_CIPHER_CTX_is_encrypting(const EVP_CIPHER_CTX *ctx); | |
72b60351 | 210 | |
3f2b5a88 DSH |
211 | int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); |
212 | int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); | |
213 | ||
b4250010 | 214 | void EVP_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx, |
251e610c RL |
215 | void (*fn)(EVP_CIPHER *cipher, void *arg), |
216 | void *arg); | |
c540f00f | 217 | |
31b7f23d TM |
218 | #define EVP_CIPHER_nid EVP_CIPHER_get_nid |
219 | #define EVP_CIPHER_name EVP_CIPHER_get0_name | |
220 | #define EVP_CIPHER_block_size EVP_CIPHER_get_block_size | |
221 | #define EVP_CIPHER_key_length EVP_CIPHER_get_key_length | |
222 | #define EVP_CIPHER_iv_length EVP_CIPHER_get_iv_length | |
223 | #define EVP_CIPHER_flags EVP_CIPHER_get_flags | |
224 | #define EVP_CIPHER_mode EVP_CIPHER_get_mode | |
225 | #define EVP_CIPHER_type EVP_CIPHER_get_type | |
226 | #define EVP_CIPHER_CTX_encrypting EVP_CIPHER_CTX_is_encrypting | |
227 | #define EVP_CIPHER_CTX_nid EVP_CIPHER_CTX_get_nid | |
228 | #define EVP_CIPHER_CTX_block_size EVP_CIPHER_CTX_get_block_size | |
229 | #define EVP_CIPHER_CTX_key_length EVP_CIPHER_CTX_get_key_length | |
230 | #define EVP_CIPHER_CTX_iv_length EVP_CIPHER_CTX_get_iv_length | |
231 | #define EVP_CIPHER_CTX_tag_length EVP_CIPHER_CTX_get_tag_length | |
232 | #define EVP_CIPHER_CTX_num EVP_CIPHER_CTX_get_num | |
233 | #define EVP_CIPHER_CTX_type EVP_CIPHER_CTX_get_type | |
234 | #define EVP_CIPHER_CTX_mode EVP_CIPHER_CTX_get_mode | |
235 | ||
3dbf8243 MC |
236 | The following function has been deprecated since OpenSSL 3.0, and can be |
237 | hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, | |
238 | see L<openssl_user_macros(7)>: | |
f6c95e46 RS |
239 | |
240 | const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx); | |
241 | ||
3dbf8243 MC |
242 | The following function has been deprecated since OpenSSL 1.1.0, and can be |
243 | hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, | |
244 | see L<openssl_user_macros(7)>: | |
ed576acd TM |
245 | |
246 | int EVP_CIPHER_CTX_flags(const EVP_CIPHER_CTX *ctx); | |
247 | ||
72b60351 DSH |
248 | =head1 DESCRIPTION |
249 | ||
8c1cbc72 | 250 | The EVP cipher routines are a high-level interface to certain |
72b60351 DSH |
251 | symmetric ciphers. |
252 | ||
550f974a RL |
253 | The B<EVP_CIPHER> type is a structure for cipher method implementation. |
254 | ||
97aede68 SL |
255 | =over 4 |
256 | ||
257 | =item EVP_CIPHER_fetch() | |
258 | ||
b9098d4e SL |
259 | Fetches the cipher implementation for the given I<algorithm> from any provider |
260 | offering it, within the criteria given by the I<properties>. | |
906bced1 | 261 | See L<crypto(7)/ALGORITHM FETCHING> for further information. |
2cafb1df | 262 | |
550f974a RL |
263 | The returned value must eventually be freed with EVP_CIPHER_free(). |
264 | ||
97aede68 SL |
265 | Fetched B<EVP_CIPHER> structures are reference counted. |
266 | ||
267 | =item EVP_CIPHER_up_ref() | |
550f974a | 268 | |
97aede68 SL |
269 | Increments the reference count for an B<EVP_CIPHER> structure. |
270 | ||
271 | =item EVP_CIPHER_free() | |
272 | ||
273 | Decrements the reference count for the fetched B<EVP_CIPHER> structure. | |
550f974a | 274 | If the reference count drops to 0 then the structure is freed. |
2cafb1df | 275 | |
97aede68 SL |
276 | =item EVP_CIPHER_CTX_new() |
277 | ||
278 | Allocates and returns a cipher context. | |
279 | ||
280 | =item EVP_CIPHER_CTX_free() | |
281 | ||
b9098d4e SL |
282 | Clears all information from a cipher context and frees any allocated memory |
283 | associated with it, including I<ctx> itself. This function should be called after | |
97aede68 SL |
284 | all operations using a cipher are complete so sensitive information does not |
285 | remain in memory. | |
286 | ||
0324ae3e P |
287 | =item EVP_CIPHER_CTX_dup() |
288 | ||
289 | Can be used to duplicate the cipher state from I<in>. This is useful | |
290 | to avoid multiple EVP_MD_fetch() calls or if large amounts of data are to be | |
291 | hashed which only differ in the last few bytes. | |
292 | ||
293 | =item EVP_CIPHER_CTX_copy() | |
294 | ||
295 | Can be used to copy the cipher state from I<in> to I<out>. | |
296 | ||
97aede68 SL |
297 | =item EVP_CIPHER_CTX_ctrl() |
298 | ||
b9098d4e | 299 | I<This is a legacy method.> EVP_CIPHER_CTX_set_params() and |
97aede68 | 300 | EVP_CIPHER_CTX_get_params() is the mechanism that should be used to set and get |
b9098d4e | 301 | parameters that are used by providers. |
97aede68 SL |
302 | |
303 | Performs cipher-specific control actions on context I<ctx>. The control command | |
304 | is indicated in I<cmd> and any additional arguments in I<p1> and I<p2>. | |
305 | EVP_CIPHER_CTX_ctrl() must be called after EVP_CipherInit_ex2(). Other restrictions | |
306 | may apply depending on the control type and cipher implementation. | |
307 | ||
308 | If this function happens to be used with a fetched B<EVP_CIPHER>, it will | |
309 | translate the controls that are known to OpenSSL into L<OSSL_PARAM(3)> | |
310 | parameters with keys defined by OpenSSL and call EVP_CIPHER_CTX_get_params() or | |
311 | EVP_CIPHER_CTX_set_params() as is appropriate for each control command. | |
312 | ||
313 | See L</CONTROLS> below for more information, including what translations are | |
314 | being done. | |
315 | ||
316 | =item EVP_CIPHER_get_params() | |
05fdb8d3 | 317 | |
97aede68 SL |
318 | Retrieves the requested list of algorithm I<params> from a CIPHER I<cipher>. |
319 | See L</PARAMETERS> below for more information. | |
3811eed8 | 320 | |
97aede68 SL |
321 | =item EVP_CIPHER_CTX_get_params() |
322 | ||
323 | Retrieves the requested list of I<params> from CIPHER context I<ctx>. | |
324 | See L</PARAMETERS> below for more information. | |
325 | ||
326 | =item EVP_CIPHER_CTX_set_params() | |
327 | ||
328 | Sets the list of I<params> into a CIPHER context I<ctx>. | |
329 | See L</PARAMETERS> below for more information. | |
330 | ||
331 | =item EVP_CIPHER_gettable_params() | |
332 | ||
318a9dfa RL |
333 | Get a constant L<OSSL_PARAM(3)> array that describes the retrievable parameters |
334 | that can be used with EVP_CIPHER_get_params(). | |
97aede68 SL |
335 | |
336 | =item EVP_CIPHER_gettable_ctx_params() and EVP_CIPHER_CTX_gettable_params() | |
337 | ||
318a9dfa | 338 | Get a constant L<OSSL_PARAM(3)> array that describes the retrievable parameters |
97aede68 SL |
339 | that can be used with EVP_CIPHER_CTX_get_params(). |
340 | EVP_CIPHER_gettable_ctx_params() returns the parameters that can be retrieved | |
341 | from the algorithm, whereas EVP_CIPHER_CTX_gettable_params() returns the | |
342 | parameters that can be retrieved in the context's current state. | |
97aede68 SL |
343 | |
344 | =item EVP_CIPHER_settable_ctx_params() and EVP_CIPHER_CTX_settable_params() | |
345 | ||
318a9dfa | 346 | Get a constant L<OSSL_PARAM(3)> array that describes the settable parameters |
97aede68 SL |
347 | that can be used with EVP_CIPHER_CTX_set_params(). |
348 | EVP_CIPHER_settable_ctx_params() returns the parameters that can be set from the | |
349 | algorithm, whereas EVP_CIPHER_CTX_settable_params() returns the parameters that | |
350 | can be set in the context's current state. | |
97aede68 SL |
351 | |
352 | =item EVP_EncryptInit_ex2() | |
353 | ||
354 | Sets up cipher context I<ctx> for encryption with cipher I<type>. I<type> is | |
b9098d4e SL |
355 | typically supplied by calling EVP_CIPHER_fetch(). I<type> may also be set |
356 | using legacy functions such as EVP_aes_256_cbc(), but this is not recommended | |
357 | for new applications. I<key> is the symmetric key to use and I<iv> is the IV to | |
358 | use (if necessary), the actual number of bytes used for the key and IV depends | |
359 | on the cipher. The parameters I<params> will be set on the context after | |
360 | initialisation. It is possible to set all parameters to NULL except I<type> in | |
361 | an initial call and supply the remaining parameters in subsequent calls, all of | |
362 | which have I<type> set to NULL. This is done when the default cipher parameters | |
363 | are not appropriate. | |
97aede68 | 364 | For B<EVP_CIPH_GCM_MODE> the IV will be generated internally if it is not |
1036bb64 P |
365 | specified. |
366 | ||
97aede68 | 367 | =item EVP_EncryptInit_ex() |
72b60351 | 368 | |
b9098d4e SL |
369 | This legacy function is similar to EVP_EncryptInit_ex2() when I<impl> is NULL. |
370 | The implementation of the I<type> from the I<impl> engine will be used if it | |
371 | exists. | |
97aede68 SL |
372 | |
373 | =item EVP_EncryptUpdate() | |
374 | ||
375 | Encrypts I<inl> bytes from the buffer I<in> and writes the encrypted version to | |
376 | I<out>. This function can be called multiple times to encrypt successive blocks | |
377 | of data. The amount of data written depends on the block alignment of the | |
378 | encrypted data. | |
3fc164e8 P |
379 | For most ciphers and modes, the amount of data written can be anything |
380 | from zero bytes to (inl + cipher_block_size - 1) bytes. | |
381 | For wrap cipher modes, the amount of data written can be anything | |
382 | from zero bytes to (inl + cipher_block_size) bytes. | |
383 | For stream ciphers, the amount of data written can be anything from zero | |
384 | bytes to inl bytes. | |
97aede68 SL |
385 | Thus, I<out> should contain sufficient room for the operation being performed. |
386 | The actual number of bytes written is placed in I<outl>. It also | |
387 | checks if I<in> and I<out> are partially overlapping, and if they are | |
c3a73daf | 388 | 0 is returned to indicate failure. |
72b60351 | 389 | |
3811eed8 | 390 | If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts |
f2e5ca84 | 391 | the "final" data, that is any data that remains in a partial block. |
a09474dd RS |
392 | It uses standard block padding (aka PKCS padding) as described in |
393 | the NOTES section, below. The encrypted | |
b9098d4e SL |
394 | final data is written to I<out> which should have sufficient space for |
395 | one cipher block. The number of bytes written is placed in I<outl>. After | |
f2e5ca84 DSH |
396 | this function is called the encryption operation is finished and no further |
397 | calls to EVP_EncryptUpdate() should be made. | |
398 | ||
3811eed8 | 399 | If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more |
f2e5ca84 | 400 | data and it will return an error if any data remains in a partial block: |
c7497f34 | 401 | that is if the total data length is not a multiple of the block size. |
72b60351 | 402 | |
97aede68 SL |
403 | =item EVP_DecryptInit_ex2(), EVP_DecryptInit_ex(), EVP_DecryptUpdate() |
404 | and EVP_DecryptFinal_ex() | |
405 | ||
406 | These functions are the corresponding decryption operations. | |
407 | EVP_DecryptFinal() will return an error code if padding is enabled and the | |
408 | final block is not correctly formatted. The parameters and restrictions are | |
409 | identical to the encryption operations except that if padding is enabled the | |
410 | decrypted data buffer I<out> passed to EVP_DecryptUpdate() should have | |
411 | sufficient room for (I<inl> + cipher_block_size) bytes unless the cipher block | |
412 | size is 1 in which case I<inl> bytes is sufficient. | |
413 | ||
414 | =item EVP_CipherInit_ex2(), EVP_CipherInit_ex(), EVP_CipherUpdate() and | |
415 | EVP_CipherFinal_ex() | |
416 | ||
b9098d4e | 417 | These functions can be used for decryption or encryption. The operation |
97aede68 SL |
418 | performed depends on the value of the I<enc> parameter. It should be set to 1 |
419 | for encryption, 0 for decryption and -1 to leave the value unchanged | |
420 | (the actual value of 'enc' being supplied in a previous call). | |
421 | ||
422 | =item EVP_CIPHER_CTX_reset() | |
423 | ||
424 | Clears all information from a cipher context and free up any allocated memory | |
425 | associated with it, except the I<ctx> itself. This function should be called | |
b9098d4e | 426 | anytime I<ctx> is reused by another |
97aede68 SL |
427 | EVP_CipherInit() / EVP_CipherUpdate() / EVP_CipherFinal() series of calls. |
428 | ||
429 | =item EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() | |
430 | ||
431 | Behave in a similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex() and | |
b9098d4e SL |
432 | EVP_CipherInit_ex() except if the I<type> is not a fetched cipher they use the |
433 | default implementation of the I<type>. | |
72b60351 | 434 | |
97aede68 SL |
435 | =item EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() |
436 | ||
437 | Identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and | |
538860a3 | 438 | EVP_CipherFinal_ex(). In previous releases they also cleaned up |
97aede68 | 439 | the I<ctx>, but this is no longer done and EVP_CIPHER_CTX_cleanup() |
538860a3 | 440 | must be called to free any context resources. |
72b60351 | 441 | |
97aede68 SL |
442 | =item EVP_Cipher() |
443 | ||
444 | Encrypts or decrypts a maximum I<inl> amount of bytes from I<in> and leaves the | |
445 | result in I<out>. | |
7f9537d5 SL |
446 | |
447 | For legacy ciphers - If the cipher doesn't have the flag | |
448 | B<EVP_CIPH_FLAG_CUSTOM_CIPHER> set, then I<inl> must be a multiple of | |
ed576acd | 449 | EVP_CIPHER_get_block_size(). If it isn't, the result is undefined. If the cipher |
7f9537d5 SL |
450 | has that flag set, then I<inl> can be any size. |
451 | ||
b9098d4e SL |
452 | Due to the constraints of the API contract of this function it shouldn't be used |
453 | in applications, please consider using EVP_CipherUpdate() and | |
454 | EVP_CipherFinal_ex() instead. | |
f7397f0d | 455 | |
97aede68 SL |
456 | =item EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() |
457 | ||
971dbab4 MC |
458 | Returns an B<EVP_CIPHER> structure when passed a cipher name, a cipher B<NID> or |
459 | an B<ASN1_OBJECT> structure respectively. | |
3f2b5a88 | 460 | |
69222552 | 461 | EVP_get_cipherbyname() will return NULL for algorithms such as "AES-128-SIV", |
462 | "AES-128-CBC-CTS" and "CAMELLIA-128-CBC-CTS" which were previously only | |
971dbab4 MC |
463 | accessible via low level interfaces. |
464 | ||
465 | The EVP_get_cipherbyname() function is present for backwards compatibility with | |
466 | OpenSSL prior to version 3 and is different to the EVP_CIPHER_fetch() function | |
467 | since it does not attempt to "fetch" an implementation of the cipher. | |
468 | Additionally, it only knows about ciphers that are built-in to OpenSSL and have | |
469 | an associated NID. Similarly EVP_get_cipherbynid() and EVP_get_cipherbyobj() | |
470 | also return objects without an associated implementation. | |
471 | ||
472 | When the cipher objects returned by these functions are used (such as in a call | |
473 | to EVP_EncryptInit_ex()) an implementation of the cipher will be implicitly | |
474 | fetched from the loaded providers. This fetch could fail if no suitable | |
475 | implementation is available. Use EVP_CIPHER_fetch() instead to explicitly fetch | |
476 | the algorithm and an associated implementation from a provider. | |
477 | ||
478 | See L<crypto(7)/ALGORITHM FETCHING> for more information about fetching. | |
479 | ||
480 | The cipher objects returned from these functions do not need to be freed with | |
481 | EVP_CIPHER_free(). | |
69222552 | 482 | |
ed576acd | 483 | =item EVP_CIPHER_get_nid() and EVP_CIPHER_CTX_get_nid() |
97aede68 SL |
484 | |
485 | Return the NID of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> | |
486 | structure. The actual NID value is an internal value which may not have a | |
487 | corresponding OBJECT IDENTIFIER. | |
488 | ||
7f9537d5 SL |
489 | =item EVP_CIPHER_CTX_set_flags(), EVP_CIPHER_CTX_clear_flags() and EVP_CIPHER_CTX_test_flags() |
490 | ||
491 | Sets, clears and tests I<ctx> flags. See L</FLAGS> below for more information. | |
492 | ||
493 | For provided ciphers EVP_CIPHER_CTX_set_flags() should be called only after the | |
494 | fetched cipher has been assigned to the I<ctx>. It is recommended to use | |
495 | L</PARAMETERS> instead. | |
496 | ||
97aede68 SL |
497 | =item EVP_CIPHER_CTX_set_padding() |
498 | ||
499 | Enables or disables padding. This function should be called after the context | |
500 | is set up for encryption or decryption with EVP_EncryptInit_ex2(), | |
501 | EVP_DecryptInit_ex2() or EVP_CipherInit_ex2(). By default encryption operations | |
502 | are padded using standard block padding and the padding is checked and removed | |
b9098d4e | 503 | when decrypting. If the I<pad> parameter is zero then no padding is |
83f68df3 CPLG |
504 | performed, the total amount of data encrypted or decrypted must then |
505 | be a multiple of the block size or an error will occur. | |
f2e5ca84 | 506 | |
ed576acd | 507 | =item EVP_CIPHER_get_key_length() and EVP_CIPHER_CTX_get_key_length() |
ae3ff60e | 508 | |
97aede68 SL |
509 | Return the key length of a cipher when passed an B<EVP_CIPHER> or |
510 | B<EVP_CIPHER_CTX> structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum | |
ed576acd TM |
511 | key length for all ciphers. Note: although EVP_CIPHER_get_key_length() is fixed for |
512 | a given cipher, the value of EVP_CIPHER_CTX_get_key_length() may be different for | |
97aede68 | 513 | variable key length ciphers. |
a91dedca | 514 | |
97aede68 SL |
515 | =item EVP_CIPHER_CTX_set_key_length() |
516 | ||
b9098d4e | 517 | Sets the key length of the cipher context. |
a91dedca DSH |
518 | If the cipher is a fixed length cipher then attempting to set the key |
519 | length to any value other than the fixed value is an error. | |
3f2b5a88 | 520 | |
ed576acd | 521 | =item EVP_CIPHER_get_iv_length() and EVP_CIPHER_CTX_get_iv_length() |
3f2b5a88 | 522 | |
97aede68 SL |
523 | Return the IV length of a cipher when passed an B<EVP_CIPHER> or |
524 | B<EVP_CIPHER_CTX>. It will return zero if the cipher does not use an IV. | |
525 | The constant B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers. | |
dc64dc2e | 526 | |
ed576acd | 527 | =item EVP_CIPHER_CTX_get_tag_length() |
97aede68 | 528 | |
b9098d4e | 529 | Returns the tag length of an AEAD cipher when passed a B<EVP_CIPHER_CTX>. It will |
97aede68 SL |
530 | return zero if the cipher does not support a tag. It returns a default value if |
531 | the tag length has not been set. | |
532 | ||
ed576acd | 533 | =item EVP_CIPHER_get_block_size() and EVP_CIPHER_CTX_get_block_size() |
97aede68 SL |
534 | |
535 | Return the block size of a cipher when passed an B<EVP_CIPHER> or | |
536 | B<EVP_CIPHER_CTX> structure. The constant B<EVP_MAX_BLOCK_LENGTH> is also the | |
537 | maximum block length for all ciphers. | |
538 | ||
ed576acd | 539 | =item EVP_CIPHER_get_type() and EVP_CIPHER_CTX_get_type() |
97aede68 SL |
540 | |
541 | Return the type of the passed cipher or context. This "type" is the actual NID | |
b9098d4e SL |
542 | of the cipher OBJECT IDENTIFIER and as such it ignores the cipher parameters |
543 | (40 bit RC2 and 128 bit RC2 have the same NID). If the cipher does not have an | |
97aede68 | 544 | object identifier or does not have ASN1 support this function will return |
41e68ef2 | 545 | B<NID_undef>. |
3f2b5a88 | 546 | |
97aede68 SL |
547 | =item EVP_CIPHER_is_a() |
548 | ||
549 | Returns 1 if I<cipher> is an implementation of an algorithm that's identifiable | |
550 | with I<name>, otherwise 0. If I<cipher> is a legacy cipher (it's the return | |
551 | value from the likes of EVP_aes128() rather than the result of an | |
552 | EVP_CIPHER_fetch()), only cipher names registered with the default library | |
553 | context (see L<OSSL_LIB_CTX(3)>) will be considered. | |
554 | ||
ed576acd | 555 | =item EVP_CIPHER_get0_name() and EVP_CIPHER_CTX_get0_name() |
7cfa1717 | 556 | |
97aede68 | 557 | Return the name of the passed cipher or context. For fetched ciphers with |
b9098d4e | 558 | multiple names, only one of them is returned. See also EVP_CIPHER_names_do_all(). |
506cb0f6 | 559 | |
97aede68 | 560 | =item EVP_CIPHER_names_do_all() |
f651c727 | 561 | |
97aede68 SL |
562 | Traverses all names for the I<cipher>, and calls I<fn> with each name and |
563 | I<data>. This is only useful with fetched B<EVP_CIPHER>s. | |
c750bc08 | 564 | |
ed576acd | 565 | =item EVP_CIPHER_get0_description() |
03888233 | 566 | |
97aede68 SL |
567 | Returns a description of the cipher, meant for display and human consumption. |
568 | The description is at the discretion of the cipher implementation. | |
1d2622d4 | 569 | |
ed576acd | 570 | =item EVP_CIPHER_get0_provider() |
97aede68 SL |
571 | |
572 | Returns an B<OSSL_PROVIDER> pointer to the provider that implements the given | |
573 | B<EVP_CIPHER>. | |
574 | ||
575 | =item EVP_CIPHER_CTX_get0_cipher() | |
576 | ||
577 | Returns the B<EVP_CIPHER> structure when passed an B<EVP_CIPHER_CTX> structure. | |
f6c95e46 RS |
578 | EVP_CIPHER_CTX_get1_cipher() is the same except the ownership is passed to |
579 | the caller. | |
3f2b5a88 | 580 | |
ed576acd | 581 | =item EVP_CIPHER_get_mode() and EVP_CIPHER_CTX_get_mode() |
97aede68 SL |
582 | |
583 | Return the block cipher mode: | |
338ead0f PS |
584 | EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, |
585 | EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE, | |
97aede68 SL |
586 | EVP_CIPH_WRAP_MODE, EVP_CIPH_OCB_MODE or EVP_CIPH_SIV_MODE. |
587 | If the cipher is a stream cipher then EVP_CIPH_STREAM_CIPHER is returned. | |
588 | ||
ed576acd | 589 | =item EVP_CIPHER_get_flags() |
97aede68 | 590 | |
7f9537d5 | 591 | Returns any flags associated with the cipher. See L</FLAGS> |
97aede68 SL |
592 | for a list of currently defined flags. |
593 | ||
ed576acd TM |
594 | =item EVP_CIPHER_CTX_get_num() and EVP_CIPHER_CTX_set_num() |
595 | ||
596 | Gets or sets the cipher specific "num" parameter for the associated I<ctx>. | |
597 | Built-in ciphers typically use this to track how much of the current underlying block | |
598 | has been "used" already. | |
599 | ||
600 | =item EVP_CIPHER_CTX_is_encrypting() | |
601 | ||
602 | Reports whether the I<ctx> is being used for encryption or decryption. | |
603 | ||
604 | =item EVP_CIPHER_CTX_flags() | |
605 | ||
606 | A deprecated macro calling C<EVP_CIPHER_get_flags(EVP_CIPHER_CTX_get0_cipher(ctx))>. | |
607 | Do not use. | |
608 | ||
97aede68 SL |
609 | =item EVP_CIPHER_param_to_asn1() |
610 | ||
611 | Sets the AlgorithmIdentifier "parameter" based on the passed cipher. This will | |
612 | typically include any parameters and an IV. The cipher IV (if any) must be set | |
613 | when this call is made. This call should be made before the cipher is actually | |
614 | "used" (before any EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). | |
615 | This function may fail if the cipher does not have any ASN1 support. | |
616 | ||
617 | =item EVP_CIPHER_asn1_to_param() | |
618 | ||
619 | Sets the cipher parameters based on an ASN1 AlgorithmIdentifier "parameter". | |
620 | The precise effect depends on the cipher. In the case of B<RC2>, for example, | |
621 | it will set the IV and effective key length. | |
3f2b5a88 DSH |
622 | This function should be called after the base cipher type is set but before |
623 | the key is set. For example EVP_CipherInit() will be called with the IV and | |
624 | key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally | |
625 | EVP_CipherInit() again with all parameters except the key set to NULL. It is | |
626 | possible for this function to fail if the cipher does not have any ASN1 support | |
627 | or the parameters cannot be set (for example the RC2 effective key length | |
a91dedca DSH |
628 | is not supported. |
629 | ||
97aede68 SL |
630 | =item EVP_CIPHER_CTX_rand_key() |
631 | ||
632 | Generates a random key of the appropriate length based on the cipher context. | |
633 | The B<EVP_CIPHER> can provide its own random key generation routine to support | |
b9098d4e | 634 | keys of a specific form. I<key> must point to a buffer at least as big as the |
ed576acd | 635 | value returned by EVP_CIPHER_CTX_get_key_length(). |
97aede68 SL |
636 | |
637 | =item EVP_CIPHER_do_all_provided() | |
638 | ||
639 | Traverses all ciphers implemented by all activated providers in the given | |
640 | library context I<libctx>, and for each of the implementations, calls the given | |
641 | function I<fn> with the implementation method and the given I<arg> as argument. | |
642 | ||
643 | =back | |
644 | ||
645 | =head1 PARAMETERS | |
646 | ||
647 | See L<OSSL_PARAM(3)> for information about passing parameters. | |
648 | ||
649 | =head2 Gettable EVP_CIPHER parameters | |
650 | ||
651 | When EVP_CIPHER_fetch() is called it internally calls EVP_CIPHER_get_params() | |
652 | and caches the results. | |
653 | ||
318a9dfa | 654 | EVP_CIPHER_get_params() can be used with the following L<OSSL_PARAM(3)> keys: |
97aede68 SL |
655 | |
656 | =over 4 | |
657 | ||
658 | =item "mode" (B<OSSL_CIPHER_PARAM_MODE>) <unsigned integer> | |
659 | ||
660 | Gets the mode for the associated cipher algorithm I<cipher>. | |
ed576acd TM |
661 | See L</EVP_CIPHER_get_mode() and EVP_CIPHER_CTX_get_mode()> for a list of valid modes. |
662 | Use EVP_CIPHER_get_mode() to retrieve the cached value. | |
97aede68 SL |
663 | |
664 | =item "keylen" (B<OSSL_CIPHER_PARAM_KEYLEN>) <unsigned integer> | |
665 | ||
666 | Gets the key length for the associated cipher algorithm I<cipher>. | |
ed576acd | 667 | Use EVP_CIPHER_get_key_length() to retrieve the cached value. |
97aede68 SL |
668 | |
669 | =item "ivlen" (B<OSSL_CIPHER_PARAM_IVLEN>) <unsigned integer> | |
670 | ||
671 | Gets the IV length for the associated cipher algorithm I<cipher>. | |
ed576acd | 672 | Use EVP_CIPHER_get_iv_length() to retrieve the cached value. |
97aede68 SL |
673 | |
674 | =item "blocksize" (B<OSSL_CIPHER_PARAM_BLOCK_SIZE>) <unsigned integer> | |
675 | ||
676 | Gets the block size for the associated cipher algorithm I<cipher>. | |
677 | The block size should be 1 for stream ciphers. | |
678 | Note that the block size for a cipher may be different to the block size for | |
679 | the underlying encryption/decryption primitive. | |
680 | For example AES in CTR mode has a block size of 1 (because it operates like a | |
681 | stream cipher), even though AES has a block size of 16. | |
e304aa87 | 682 | Use EVP_CIPHER_get_block_size() to retrieve the cached value. |
97aede68 SL |
683 | |
684 | =item "aead" (B<OSSL_CIPHER_PARAM_AEAD>) <integer> | |
685 | ||
686 | Gets 1 if this is an AEAD cipher algorithm, otherwise it gets 0. | |
ed576acd | 687 | Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_AEAD_CIPHER) to retrieve the |
97aede68 SL |
688 | cached value. |
689 | ||
690 | =item "custom-iv" (B<OSSL_CIPHER_PARAM_CUSTOM_IV>) <integer> | |
691 | ||
692 | Gets 1 if the cipher algorithm I<cipher> has a custom IV, otherwise it gets 0. | |
693 | Storing and initializing the IV is left entirely to the implementation, if a | |
694 | custom IV is used. | |
ed576acd | 695 | Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_CUSTOM_IV) to retrieve the |
97aede68 SL |
696 | cached value. |
697 | ||
698 | =item "cts" (B<OSSL_CIPHER_PARAM_CTS>) <integer> | |
699 | ||
700 | Gets 1 if the cipher algorithm I<cipher> uses ciphertext stealing, | |
701 | otherwise it gets 0. | |
702 | This is currently used to indicate that the cipher is a one shot that only | |
703 | allows a single call to EVP_CipherUpdate(). | |
ed576acd | 704 | Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_CTS) to retrieve the |
97aede68 SL |
705 | cached value. |
706 | ||
707 | =item "tls-multi" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK>) <integer> | |
708 | ||
709 | Gets 1 if the cipher algorithm I<cipher> supports interleaving of crypto blocks, | |
710 | otherwise it gets 0. The interleaving is an optimization only applicable to certain | |
711 | TLS ciphers. | |
ed576acd | 712 | Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK) to retrieve the |
97aede68 SL |
713 | cached value. |
714 | ||
f41fd10d SL |
715 | =item "has-randkey" (B<OSSL_CIPHER_PARAM_HAS_RANDKEY>) <integer> |
716 | ||
717 | Gets 1 if the cipher algorithm I<cipher> supports the gettable EVP_CIPHER_CTX | |
718 | parameter B<OSSL_CIPHER_PARAM_RANDOM_KEY>. Only DES and 3DES set this to 1, | |
719 | all other OpenSSL ciphers return 0. | |
720 | ||
97aede68 SL |
721 | =back |
722 | ||
723 | =head2 Gettable and Settable EVP_CIPHER_CTX parameters | |
724 | ||
318a9dfa | 725 | The following L<OSSL_PARAM(3)> keys can be used with both EVP_CIPHER_CTX_get_params() |
97aede68 SL |
726 | and EVP_CIPHER_CTX_set_params(). |
727 | ||
728 | =over 4 | |
729 | ||
730 | =item "padding" (B<OSSL_CIPHER_PARAM_PADDING>) <unsigned integer> | |
731 | ||
732 | Gets or sets the padding mode for the cipher context I<ctx>. | |
733 | Padding is enabled if the value is 1, and disabled if the value is 0. | |
734 | See also EVP_CIPHER_CTX_set_padding(). | |
735 | ||
736 | =item "num" (B<OSSL_CIPHER_PARAM_NUM>) <unsigned integer> | |
737 | ||
738 | Gets or sets the cipher specific "num" parameter for the cipher context I<ctx>. | |
739 | Built-in ciphers typically use this to track how much of the current underlying | |
740 | block has been "used" already. | |
ed576acd | 741 | See also EVP_CIPHER_CTX_get_num() and EVP_CIPHER_CTX_set_num(). |
97aede68 SL |
742 | |
743 | =item "keylen" (B<OSSL_CIPHER_PARAM_KEYLEN>) <unsigned integer> | |
744 | ||
745 | Gets or sets the key length for the cipher context I<ctx>. | |
746 | The length of the "keylen" parameter should not exceed that of a B<size_t>. | |
ed576acd | 747 | See also EVP_CIPHER_CTX_get_key_length() and EVP_CIPHER_CTX_set_key_length(). |
97aede68 SL |
748 | |
749 | =item "tag" (B<OSSL_CIPHER_PARAM_AEAD_TAG>) <octet string> | |
750 | ||
751 | Gets or sets the AEAD tag for the associated cipher context I<ctx>. | |
752 | See L<EVP_EncryptInit(3)/AEAD Interface>. | |
753 | ||
754 | =item "keybits" (B<OSSL_CIPHER_PARAM_RC2_KEYBITS>) <unsigned integer> | |
755 | ||
756 | Gets or sets the effective keybits used for a RC2 cipher. | |
757 | The length of the "keybits" parameter should not exceed that of a B<size_t>. | |
758 | ||
759 | =item "rounds" (B<OSSL_CIPHER_PARAM_ROUNDS>) <unsigned integer> | |
760 | ||
761 | Gets or sets the number of rounds to be used for a cipher. | |
762 | This is used by the RC5 cipher. | |
763 | ||
764 | =item "alg_id_param" (B<OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS>) <octet string> | |
765 | ||
766 | Used to pass the DER encoded AlgorithmIdentifier parameter to or from | |
767 | the cipher implementation. Functions like L<EVP_CIPHER_param_to_asn1(3)> | |
768 | and L<EVP_CIPHER_asn1_to_param(3)> use this parameter for any implementation | |
769 | that has the flag B<EVP_CIPH_FLAG_CUSTOM_ASN1> set. | |
3f2b5a88 | 770 | |
97aede68 | 771 | =item "cts_mode" (B<OSSL_CIPHER_PARAM_CTS_MODE>) <UTF8 string> |
5c5eb286 | 772 | |
97aede68 | 773 | Gets or sets the cipher text stealing mode. For all modes the output size is the |
7f5a9399 SL |
774 | same as the input size. The input length must be greater than or equal to the |
775 | block size. (The block size for AES and CAMELLIA is 16 bytes). | |
97aede68 SL |
776 | |
777 | Valid values for the mode are: | |
778 | ||
779 | =over 4 | |
780 | ||
781 | =item "CS1" | |
782 | ||
783 | The NIST variant of cipher text stealing. | |
7f5a9399 SL |
784 | For input lengths that are multiples of the block size it is equivalent to |
785 | using a "AES-XXX-CBC" or "CAMELLIA-XXX-CBC" cipher otherwise the second last | |
786 | cipher text block is a partial block. | |
97aede68 SL |
787 | |
788 | =item "CS2" | |
789 | ||
7f5a9399 SL |
790 | For input lengths that are multiples of the block size it is equivalent to |
791 | using a "AES-XXX-CBC" or "CAMELLIA-XXX-CBC" cipher, otherwise it is the same as | |
792 | "CS3" mode. | |
97aede68 SL |
793 | |
794 | =item "CS3" | |
795 | ||
796 | The Kerberos5 variant of cipher text stealing which always swaps the last | |
797 | cipher text block with the previous block (which may be a partial or full block | |
7f5a9399 SL |
798 | depending on the input length). If the input length is exactly one full block |
799 | then this is equivalent to using a "AES-XXX-CBC" or "CAMELLIA-XXX-CBC" cipher. | |
97aede68 SL |
800 | |
801 | =back | |
802 | ||
803 | The default is "CS1". | |
7f5a9399 SL |
804 | This is only supported for "AES-128-CBC-CTS", "AES-192-CBC-CTS", "AES-256-CBC-CTS", |
805 | "CAMELLIA-128-CBC-CTS", "CAMELLIA-192-CBC-CTS" and "CAMELLIA-256-CBC-CTS". | |
97aede68 SL |
806 | |
807 | =item "tls1multi_interleave" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE>) <unsigned integer> | |
808 | ||
809 | Sets or gets the number of records being sent in one go for a tls1 multiblock | |
810 | cipher operation (either 4 or 8 records). | |
811 | ||
812 | =back | |
813 | ||
814 | =head2 Gettable EVP_CIPHER_CTX parameters | |
815 | ||
318a9dfa | 816 | The following L<OSSL_PARAM(3)> keys can be used with EVP_CIPHER_CTX_get_params(): |
97aede68 SL |
817 | |
818 | =over 4 | |
819 | ||
820 | =item "ivlen" (B<OSSL_CIPHER_PARAM_IVLEN> and <B<OSSL_CIPHER_PARAM_AEAD_IVLEN>) <unsigned integer> | |
821 | ||
822 | Gets the IV length for the cipher context I<ctx>. | |
823 | The length of the "ivlen" parameter should not exceed that of a B<size_t>. | |
ed576acd | 824 | See also EVP_CIPHER_CTX_get_iv_length(). |
97aede68 SL |
825 | |
826 | =item "iv" (B<OSSL_CIPHER_PARAM_IV>) <octet string OR octet ptr> | |
827 | ||
828 | Gets the IV used to initialize the associated cipher context I<ctx>. | |
829 | See also EVP_CIPHER_CTX_get_original_iv(). | |
830 | ||
831 | =item "updated-iv" (B<OSSL_CIPHER_PARAM_UPDATED_IV>) <octet string OR octet ptr> | |
832 | ||
b9098d4e | 833 | Gets the updated pseudo-IV state for the associated cipher context, e.g., |
97aede68 SL |
834 | the previous ciphertext block for CBC mode or the iteratively encrypted IV |
835 | value for OFB mode. Note that octet pointer access is deprecated and is | |
836 | provided only for backwards compatibility with historical libcrypto APIs. | |
837 | See also EVP_CIPHER_CTX_get_updated_iv(). | |
838 | ||
839 | =item "randkey" (B<OSSL_CIPHER_PARAM_RANDOM_KEY>) <octet string> | |
840 | ||
b9098d4e SL |
841 | Gets an implementation specific randomly generated key for the associated |
842 | cipher context I<ctx>. This is currently only supported by DES and 3DES (which set | |
843 | the key to odd parity). | |
97aede68 SL |
844 | |
845 | =item "taglen" (B<OSSL_CIPHER_PARAM_AEAD_TAGLEN>) <unsigned integer> | |
846 | ||
b9098d4e SL |
847 | Gets the tag length to be used for an AEAD cipher for the associated cipher |
848 | context I<ctx>. It gets a default value if it has not been set. | |
97aede68 | 849 | The length of the "taglen" parameter should not exceed that of a B<size_t>. |
ed576acd | 850 | See also EVP_CIPHER_CTX_get_tag_length(). |
97aede68 SL |
851 | |
852 | =item "tlsaadpad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD>) <unsigned integer> | |
853 | ||
854 | Gets the length of the tag that will be added to a TLS record for the AEAD | |
b9098d4e | 855 | tag for the associated cipher context I<ctx>. |
97aede68 SL |
856 | The length of the "tlsaadpad" parameter should not exceed that of a B<size_t>. |
857 | ||
858 | =item "tlsivgen" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN>) <octet string> | |
859 | ||
860 | Gets the invocation field generated for encryption. | |
861 | Can only be called after "tlsivfixed" is set. | |
862 | This is only used for GCM mode. | |
863 | ||
864 | =item "tls1multi_enclen" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN>) <unsigned integer> | |
865 | ||
866 | Get the total length of the record returned from the "tls1multi_enc" operation. | |
867 | ||
868 | =item "tls1multi_maxbufsz" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE>) <unsigned integer> | |
869 | ||
b9098d4e | 870 | Gets the maximum record length for a TLS1 multiblock cipher operation. |
97aede68 SL |
871 | The length of the "tls1multi_maxbufsz" parameter should not exceed that of a B<size_t>. |
872 | ||
873 | =item "tls1multi_aadpacklen" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN>) <unsigned integer> | |
874 | ||
875 | Gets the result of running the "tls1multi_aad" operation. | |
876 | ||
877 | =item "tls-mac" (B<OSSL_CIPHER_PARAM_TLS_MAC>) <octet ptr> | |
878 | ||
b9098d4e | 879 | Used to pass the TLS MAC data. |
97aede68 SL |
880 | |
881 | =back | |
882 | ||
883 | =head2 Settable EVP_CIPHER_CTX parameters | |
884 | ||
318a9dfa | 885 | The following L<OSSL_PARAM(3)> keys can be used with EVP_CIPHER_CTX_set_params(): |
97aede68 SL |
886 | |
887 | =over 4 | |
888 | ||
889 | =item "mackey" (B<OSSL_CIPHER_PARAM_AEAD_MAC_KEY>) <octet string> | |
890 | ||
891 | Sets the MAC key used by composite AEAD ciphers such as AES-CBC-HMAC-SHA256. | |
892 | ||
893 | =item "speed" (B<OSSL_CIPHER_PARAM_SPEED>) <unsigned integer> | |
894 | ||
b9098d4e | 895 | Sets the speed option for the associated cipher context. This is only supported |
97aede68 SL |
896 | by AES SIV ciphers which disallow multiple operations by default. |
897 | Setting "speed" to 1 allows another encrypt or decrypt operation to be | |
898 | performed. This is used for performance testing. | |
899 | ||
7f9537d5 SL |
900 | =item "use-bits" (B<OSSL_CIPHER_PARAM_USE_BITS>) <unsigned integer> |
901 | ||
902 | Determines if the input length I<inl> passed to EVP_EncryptUpdate(), | |
903 | EVP_DecryptUpdate() and EVP_CipherUpdate() is the number of bits or number of bytes. | |
904 | Setting "use-bits" to 1 uses bits. The default is in bytes. | |
905 | This is only used for B<CFB1> ciphers. | |
906 | ||
907 | This can be set using EVP_CIPHER_CTX_set_flags(ctx, EVP_CIPH_FLAG_LENGTH_BITS). | |
908 | ||
97aede68 SL |
909 | =item "tls-version" (B<OSSL_CIPHER_PARAM_TLS_VERSION>) <integer> |
910 | ||
b9098d4e | 911 | Sets the TLS version. |
97aede68 SL |
912 | |
913 | =item "tls-mac-size" (B<OSSL_CIPHER_PARAM_TLS_MAC_SIZE>) <unsigned integer> | |
914 | ||
b9098d4e | 915 | Set the TLS MAC size. |
97aede68 SL |
916 | |
917 | =item "tlsaad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD>) <octet string> | |
918 | ||
b9098d4e | 919 | Sets TLSv1.2 AAD information for the associated cipher context I<ctx>. |
97aede68 SL |
920 | TLSv1.2 AAD information is always 13 bytes in length and is as defined for the |
921 | "additional_data" field described in section 6.2.3.3 of RFC5246. | |
922 | ||
923 | =item "tlsivfixed" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED>) <octet string> | |
924 | ||
925 | Sets the fixed portion of an IV for an AEAD cipher used in a TLS record | |
b9098d4e | 926 | encryption/ decryption for the associated cipher context. |
97aede68 SL |
927 | TLS record encryption/decryption always occurs "in place" so that the input and |
928 | output buffers are always the same memory location. | |
929 | AEAD IVs in TLSv1.2 consist of an implicit "fixed" part and an explicit part | |
930 | that varies with every record. | |
931 | Setting a TLS fixed IV changes a cipher to encrypt/decrypt TLS records. | |
932 | TLS records are encrypted/decrypted using a single OSSL_FUNC_cipher_cipher call per | |
933 | record. | |
934 | For a record decryption the first bytes of the input buffer will be the explicit | |
935 | part of the IV and the final bytes of the input buffer will be the AEAD tag. | |
936 | The length of the explicit part of the IV and the tag length will depend on the | |
937 | cipher in use and will be defined in the RFC for the relevant ciphersuite. | |
938 | In order to allow for "in place" decryption the plaintext output should be | |
939 | written to the same location in the output buffer that the ciphertext payload | |
940 | was read from, i.e. immediately after the explicit IV. | |
941 | ||
b9098d4e | 942 | When encrypting a record the first bytes of the input buffer should be empty to |
97aede68 SL |
943 | allow space for the explicit IV, as will the final bytes where the tag will |
944 | be written. | |
945 | The length of the input buffer will include the length of the explicit IV, the | |
946 | payload, and the tag bytes. | |
947 | The cipher implementation should generate the explicit IV and write it to the | |
948 | beginning of the output buffer, do "in place" encryption of the payload and | |
949 | write that to the output buffer, and finally add the tag onto the end of the | |
950 | output buffer. | |
951 | ||
952 | Whether encrypting or decrypting the value written to I<*outl> in the | |
953 | OSSL_FUNC_cipher_cipher call should be the length of the payload excluding the explicit | |
954 | IV length and the tag length. | |
955 | ||
956 | =item "tlsivinv" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV>) <octet string> | |
957 | ||
958 | Sets the invocation field used for decryption. | |
959 | Can only be called after "tlsivfixed" is set. | |
960 | This is only used for GCM mode. | |
961 | ||
962 | =item "tls1multi_enc" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC>) <octet string> | |
963 | ||
b9098d4e SL |
964 | Triggers a multiblock TLS1 encrypt operation for a TLS1 aware cipher that |
965 | supports sending 4 or 8 records in one go. | |
97aede68 SL |
966 | The cipher performs both the MAC and encrypt stages and constructs the record |
967 | headers itself. | |
968 | "tls1multi_enc" supplies the output buffer for the encrypt operation, | |
969 | "tls1multi_encin" & "tls1multi_interleave" must also be set in order to supply | |
970 | values to the encrypt operation. | |
971 | ||
972 | =item "tls1multi_encin" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN>) <octet string> | |
973 | ||
b9098d4e | 974 | Supplies the data to encrypt for a TLS1 multiblock cipher operation. |
97aede68 SL |
975 | |
976 | =item "tls1multi_maxsndfrag" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT>) <unsigned integer> | |
977 | ||
b9098d4e | 978 | Sets the maximum send fragment size for a TLS1 multiblock cipher operation. |
97aede68 SL |
979 | It must be set before using "tls1multi_maxbufsz". |
980 | The length of the "tls1multi_maxsndfrag" parameter should not exceed that of a B<size_t>. | |
981 | ||
982 | =item "tls1multi_aad" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD>) <octet string> | |
983 | ||
b9098d4e | 984 | Sets the authenticated additional data used by a TLS1 multiblock cipher operation. |
97aede68 SL |
985 | The supplied data consists of 13 bytes of record data containing: |
986 | Bytes 0-7: The sequence number of the first record | |
987 | Byte 8: The record type | |
988 | Byte 9-10: The protocol version | |
989 | Byte 11-12: Input length (Always 0) | |
990 | ||
991 | "tls1multi_interleave" must also be set for this operation. | |
992 | ||
e44b3418 XY |
993 | =item "xts_standard" (B<OSSL_CIPHER_PARAM_XTS_STANDARD>) <UTF8 string> |
994 | ||
995 | Sets the XTS standard to use with SM4-XTS algorithm. XTS mode has two | |
996 | implementations, one is standardized in IEEE Std. 1619-2007 and has | |
997 | been widely used (e.g., XTS AES), the other is proposed recently | |
998 | (GB/T 17964-2021 implemented in May 2022) and is currently only used | |
999 | in SM4. | |
1000 | ||
1001 | The main difference between them is the multiplication by the | |
1002 | primitive element E<alpha> to calculate the tweak values. The IEEE | |
1003 | Std 1619-2007 noted that the multiplication "is a left shift of each | |
1004 | byte by one bit with carry propagating from one byte to the next | |
1005 | one", which means that in each byte, the leftmost bit is the most | |
1006 | significant bit. But in GB/T 17964-2021, the rightmost bit is the | |
1007 | most significant bit, thus the multiplication becomes a right shift | |
1008 | of each byte by one bit with carry propagating from one byte to the | |
1009 | next one. | |
1010 | ||
1011 | Valid values for the mode are: | |
1012 | ||
1013 | =over 4 | |
1014 | ||
1015 | =item "GB" | |
1016 | ||
1017 | The GB/T 17964-2021 variant of SM4-XTS algorithm. | |
1018 | ||
1019 | =item "IEEE" | |
1020 | ||
1021 | The IEEE Std. 1619-2007 variant of SM4-XTS algorithm. | |
1022 | ||
1023 | =back | |
1024 | ||
1025 | The default value is "GB". | |
1026 | ||
97aede68 SL |
1027 | =back |
1028 | ||
1029 | =head1 CONTROLS | |
1030 | ||
1031 | The Mappings from EVP_CIPHER_CTX_ctrl() identifiers to PARAMETERS are listed | |
1032 | in the following section. See the L</PARAMETERS> section for more details. | |
1033 | ||
1034 | EVP_CIPHER_CTX_ctrl() can be used to send the following standard controls: | |
1035 | ||
1036 | =over 4 | |
1037 | ||
1038 | =item EVP_CTRL_AEAD_SET_IVLEN and EVP_CTRL_GET_IVLEN | |
1039 | ||
1040 | When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() and | |
1041 | EVP_CIPHER_CTX_get_params() get called with an L<OSSL_PARAM(3)> item with the | |
1042 | key "ivlen" (B<OSSL_CIPHER_PARAM_IVLEN>). | |
1043 | ||
1044 | =item EVP_CTRL_AEAD_SET_IV_FIXED | |
1045 | ||
1046 | When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called | |
1047 | with an L<OSSL_PARAM(3)> item with the key "tlsivfixed" | |
1048 | (B<OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED>). | |
1049 | ||
1050 | =item EVP_CTRL_AEAD_SET_MAC_KEY | |
1051 | ||
1052 | When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called | |
1053 | with an L<OSSL_PARAM(3)> item with the key "mackey" | |
1054 | (B<OSSL_CIPHER_PARAM_AEAD_MAC_KEY>). | |
1055 | ||
1056 | =item EVP_CTRL_AEAD_SET_TAG and EVP_CTRL_AEAD_GET_TAG | |
1057 | ||
1058 | When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() and | |
1059 | EVP_CIPHER_CTX_get_params() get called with an L<OSSL_PARAM(3)> item with the | |
1060 | key "tag" (B<OSSL_CIPHER_PARAM_AEAD_TAG>). | |
1061 | ||
1062 | =item EVP_CTRL_CCM_SET_L | |
1063 | ||
1064 | When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called | |
1065 | with an L<OSSL_PARAM(3)> item with the key "ivlen" (B<OSSL_CIPHER_PARAM_IVLEN>) | |
1066 | with a value of (15 - L) | |
1067 | ||
1068 | =item EVP_CTRL_COPY | |
1069 | ||
1070 | There is no OSSL_PARAM mapping for this. Use EVP_CIPHER_CTX_copy() instead. | |
1071 | ||
1072 | =item EVP_CTRL_GCM_SET_IV_INV | |
1073 | ||
1074 | When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called | |
1075 | with an L<OSSL_PARAM(3)> item with the key "tlsivinv" | |
1076 | (B<OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV>). | |
1077 | ||
1078 | =item EVP_CTRL_RAND_KEY | |
1079 | ||
1080 | When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called | |
1081 | with an L<OSSL_PARAM(3)> item with the key "randkey" | |
1082 | (B<OSSL_CIPHER_PARAM_RANDOM_KEY>). | |
1083 | ||
1084 | =item EVP_CTRL_SET_KEY_LENGTH | |
1085 | ||
1086 | When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called | |
1087 | with an L<OSSL_PARAM(3)> item with the key "keylen" (B<OSSL_CIPHER_PARAM_KEYLEN>). | |
1088 | ||
1089 | =item EVP_CTRL_SET_RC2_KEY_BITS and EVP_CTRL_GET_RC2_KEY_BITS | |
1090 | ||
1091 | When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() and | |
1092 | EVP_CIPHER_CTX_get_params() get called with an L<OSSL_PARAM(3)> item with the | |
1093 | key "keybits" (B<OSSL_CIPHER_PARAM_RC2_KEYBITS>). | |
1094 | ||
1095 | =item EVP_CTRL_SET_RC5_ROUNDS and EVP_CTRL_GET_RC5_ROUNDS | |
1096 | ||
1097 | When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() and | |
1098 | EVP_CIPHER_CTX_get_params() get called with an L<OSSL_PARAM(3)> item with the | |
1099 | key "rounds" (B<OSSL_CIPHER_PARAM_ROUNDS>). | |
1100 | ||
1101 | =item EVP_CTRL_SET_SPEED | |
1102 | ||
1103 | When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called | |
1104 | with an L<OSSL_PARAM(3)> item with the key "speed" (B<OSSL_CIPHER_PARAM_SPEED>). | |
1105 | ||
1106 | =item EVP_CTRL_GCM_IV_GEN | |
1107 | ||
1108 | When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_get_params() gets called | |
1109 | with an L<OSSL_PARAM(3)> item with the key | |
1110 | "tlsivgen" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN>). | |
1111 | ||
1112 | =item EVP_CTRL_AEAD_TLS1_AAD | |
1113 | ||
1114 | When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() get called | |
1115 | with an L<OSSL_PARAM(3)> item with the key | |
027226eb | 1116 | "tlsaad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD>) |
97aede68 SL |
1117 | followed by EVP_CIPHER_CTX_get_params() with a key of |
1118 | "tlsaadpad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD>). | |
1119 | ||
1120 | =item EVP_CTRL_TLS1_1_MULTIBLOCK_MAX_BUFSIZE | |
1121 | ||
1122 | When used with a fetched B<EVP_CIPHER>, | |
b9098d4e | 1123 | EVP_CIPHER_CTX_set_params() gets called with an L<OSSL_PARAM(3)> item with the |
97aede68 SL |
1124 | key OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT |
1125 | followed by EVP_CIPHER_CTX_get_params() with a key of | |
1126 | "tls1multi_maxbufsz" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE>). | |
1127 | ||
1128 | =item EVP_CTRL_TLS1_1_MULTIBLOCK_AAD | |
1129 | ||
b9098d4e | 1130 | When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called |
97aede68 SL |
1131 | with L<OSSL_PARAM(3)> items with the keys |
1132 | "tls1multi_aad" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD>) and | |
1133 | "tls1multi_interleave" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE>) | |
1134 | followed by EVP_CIPHER_CTX_get_params() with keys of | |
1135 | "tls1multi_aadpacklen" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN>) and | |
1136 | "tls1multi_interleave" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE>). | |
1137 | ||
1138 | =item EVP_CTRL_TLS1_1_MULTIBLOCK_ENCRYPT | |
1139 | ||
b9098d4e | 1140 | When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called |
97aede68 SL |
1141 | with L<OSSL_PARAM(3)> items with the keys |
1142 | "tls1multi_enc" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC>), | |
1143 | "tls1multi_encin" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN>) and | |
1144 | "tls1multi_interleave" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE>), | |
1145 | followed by EVP_CIPHER_CTX_get_params() with a key of | |
1146 | "tls1multi_enclen" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN>). | |
1147 | ||
1148 | =back | |
c540f00f | 1149 | |
7f9537d5 SL |
1150 | =head1 FLAGS |
1151 | ||
1152 | EVP_CIPHER_CTX_set_flags(), EVP_CIPHER_CTX_clear_flags() and EVP_CIPHER_CTX_test_flags(). | |
1153 | can be used to manipulate and test these B<EVP_CIPHER_CTX> flags: | |
1154 | ||
1155 | =over 4 | |
1156 | ||
1157 | =item EVP_CIPH_NO_PADDING | |
1158 | ||
1159 | Used by EVP_CIPHER_CTX_set_padding(). | |
1160 | ||
1161 | See also L</Gettable and Settable EVP_CIPHER_CTX parameters> "padding" | |
1162 | ||
1163 | =item EVP_CIPH_FLAG_LENGTH_BITS | |
1164 | ||
1165 | See L</Settable EVP_CIPHER_CTX parameters> "use-bits". | |
1166 | ||
1167 | =item EVP_CIPHER_CTX_FLAG_WRAP_ALLOW | |
1168 | ||
1169 | Used for Legacy purposes only. This flag needed to be set to indicate the | |
1170 | cipher handled wrapping. | |
1171 | ||
1172 | =back | |
1173 | ||
1174 | EVP_CIPHER_flags() uses the following flags that | |
1175 | have mappings to L</Gettable EVP_CIPHER parameters>: | |
1176 | ||
1177 | =over 4 | |
1178 | ||
1179 | =item EVP_CIPH_FLAG_AEAD_CIPHER | |
1180 | ||
1181 | See L</Gettable EVP_CIPHER parameters> "aead". | |
1182 | ||
1183 | =item EVP_CIPH_CUSTOM_IV | |
1184 | ||
1185 | See L</Gettable EVP_CIPHER parameters> "custom-iv". | |
1186 | ||
1187 | =item EVP_CIPH_FLAG_CTS | |
1188 | ||
1189 | See L</Gettable EVP_CIPHER parameters> "cts". | |
1190 | ||
1191 | =item EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK; | |
1192 | ||
1193 | See L</Gettable EVP_CIPHER parameters> "tls-multi". | |
1194 | ||
f41fd10d SL |
1195 | =item EVP_CIPH_RAND_KEY |
1196 | ||
1197 | See L</Gettable EVP_CIPHER parameters> "has-randkey". | |
1198 | ||
7f9537d5 SL |
1199 | =back |
1200 | ||
1201 | EVP_CIPHER_flags() uses the following flags for legacy purposes only: | |
1202 | ||
1203 | =over 4 | |
1204 | ||
1205 | =item EVP_CIPH_VARIABLE_LENGTH | |
1206 | ||
1207 | =item EVP_CIPH_FLAG_CUSTOM_CIPHER | |
1208 | ||
1209 | =item EVP_CIPH_ALWAYS_CALL_INIT | |
1210 | ||
1211 | =item EVP_CIPH_CTRL_INIT | |
1212 | ||
1213 | =item EVP_CIPH_CUSTOM_KEY_LENGTH | |
1214 | ||
7f9537d5 SL |
1215 | =item EVP_CIPH_CUSTOM_COPY |
1216 | ||
1217 | =item EVP_CIPH_FLAG_DEFAULT_ASN1 | |
1218 | ||
1219 | See L<EVP_CIPHER_meth_set_flags(3)> for further information related to the above | |
1220 | flags. | |
1221 | ||
1222 | =back | |
1223 | ||
72b60351 DSH |
1224 | =head1 RETURN VALUES |
1225 | ||
2cafb1df RL |
1226 | EVP_CIPHER_fetch() returns a pointer to a B<EVP_CIPHER> for success |
1227 | and B<NULL> for failure. | |
1228 | ||
550f974a RL |
1229 | EVP_CIPHER_up_ref() returns 1 for success or 0 otherwise. |
1230 | ||
05fdb8d3 RL |
1231 | EVP_CIPHER_CTX_new() returns a pointer to a newly created |
1232 | B<EVP_CIPHER_CTX> for success and B<NULL> for failure. | |
1233 | ||
0324ae3e P |
1234 | EVP_CIPHER_CTX_dup() returns a new EVP_MD_CTX if successful or NULL on failure. |
1235 | ||
1236 | EVP_CIPHER_CTX_copy() returns 1 if successful or 0 for failure. | |
1237 | ||
1036bb64 | 1238 | EVP_EncryptInit_ex2(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex() |
0e304b7f | 1239 | return 1 for success and 0 for failure. |
72b60351 | 1240 | |
1036bb64 | 1241 | EVP_DecryptInit_ex2() and EVP_DecryptUpdate() return 1 for success and 0 for failure. |
3811eed8 | 1242 | EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success. |
72b60351 | 1243 | |
1036bb64 | 1244 | EVP_CipherInit_ex2() and EVP_CipherUpdate() return 1 for success and 0 for failure. |
21d5ed98 | 1245 | EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success. |
72b60351 | 1246 | |
51a7066e | 1247 | EVP_Cipher() returns 1 on success or 0 on failure, if the flag |
f7397f0d | 1248 | B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is not set for the cipher. |
51a7066e SL |
1249 | EVP_Cipher() returns the number of bytes written to I<out> for encryption / decryption, or |
1250 | the number of bytes authenticated in a call specifying AAD for an AEAD cipher, if the flag | |
1251 | B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is set for the cipher. | |
f7397f0d | 1252 | |
05fdb8d3 | 1253 | EVP_CIPHER_CTX_reset() returns 1 for success and 0 for failure. |
3f2b5a88 DSH |
1254 | |
1255 | EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() | |
1256 | return an B<EVP_CIPHER> structure or NULL on error. | |
1257 | ||
ed576acd | 1258 | EVP_CIPHER_get_nid() and EVP_CIPHER_CTX_get_nid() return a NID. |
3f2b5a88 | 1259 | |
ed576acd TM |
1260 | EVP_CIPHER_get_block_size() and EVP_CIPHER_CTX_get_block_size() return the |
1261 | block size. | |
3f2b5a88 | 1262 | |
ed576acd | 1263 | EVP_CIPHER_get_key_length() and EVP_CIPHER_CTX_get_key_length() return the key |
3f2b5a88 DSH |
1264 | length. |
1265 | ||
f2e5ca84 DSH |
1266 | EVP_CIPHER_CTX_set_padding() always returns 1. |
1267 | ||
ed576acd | 1268 | EVP_CIPHER_get_iv_length() and EVP_CIPHER_CTX_get_iv_length() return the IV |
0a90577e | 1269 | length, zero if the cipher does not use an IV and a negative value on error. |
3f2b5a88 | 1270 | |
ed576acd TM |
1271 | EVP_CIPHER_CTX_get_tag_length() return the tag length or zero if the cipher |
1272 | does not use a tag. | |
dc64dc2e | 1273 | |
ed576acd TM |
1274 | EVP_CIPHER_get_type() and EVP_CIPHER_CTX_get_type() return the NID of the |
1275 | cipher's OBJECT IDENTIFIER or NID_undef if it has no defined | |
1276 | OBJECT IDENTIFIER. | |
41e68ef2 DSH |
1277 | |
1278 | EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure. | |
1279 | ||
ed576acd TM |
1280 | EVP_CIPHER_CTX_get_num() returns a nonnegative num value or |
1281 | B<EVP_CTRL_RET_UNSUPPORTED> if the implementation does not support the call | |
1282 | or on any other error. | |
1283 | ||
1284 | EVP_CIPHER_CTX_set_num() returns 1 on success and 0 if the implementation | |
1285 | does not support the call or on any other error. | |
1286 | ||
1287 | EVP_CIPHER_CTX_is_encrypting() returns 1 if the I<ctx> is set up for encryption | |
1288 | 0 otherwise. | |
1289 | ||
c03726ca | 1290 | EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return greater |
49c9c1b3 | 1291 | than zero for success and zero or a negative number on failure. |
41e68ef2 | 1292 | |
dd1f2842 PH |
1293 | EVP_CIPHER_CTX_rand_key() returns 1 for success and zero or a negative number |
1294 | for failure. | |
5c5eb286 | 1295 | |
d84f5515 MC |
1296 | EVP_CIPHER_names_do_all() returns 1 if the callback was called for all names. |
1297 | A return value of 0 means that the callback was not called for any names. | |
1298 | ||
a91dedca DSH |
1299 | =head1 CIPHER LISTING |
1300 | ||
1301 | All algorithms have a fixed key length unless otherwise stated. | |
1302 | ||
6e4618a0 | 1303 | Refer to L</SEE ALSO> for the full list of ciphers available through the EVP |
8fa4d95e RT |
1304 | interface. |
1305 | ||
a91dedca DSH |
1306 | =over 4 |
1307 | ||
1308 | =item EVP_enc_null() | |
1309 | ||
1310 | Null cipher: does nothing. | |
1311 | ||
8fa4d95e | 1312 | =back |
a91dedca | 1313 | |
485d3361 | 1314 | =head1 AEAD INTERFACE |
a91dedca | 1315 | |
8fa4d95e RT |
1316 | The EVP interface for Authenticated Encryption with Associated Data (AEAD) |
1317 | modes are subtly altered and several additional I<ctrl> operations are supported | |
1318 | depending on the mode specified. | |
a91dedca | 1319 | |
8fa4d95e RT |
1320 | To specify additional authenticated data (AAD), a call to EVP_CipherUpdate(), |
1321 | EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output | |
51a7066e SL |
1322 | parameter I<out> set to B<NULL>. In this case, on success, the parameter |
1323 | I<outl> is set to the number of bytes authenticated. | |
a91dedca | 1324 | |
8fa4d95e RT |
1325 | When decrypting, the return value of EVP_DecryptFinal() or EVP_CipherFinal() |
1326 | indicates whether the operation was successful. If it does not indicate success, | |
1327 | the authentication operation has failed and any output data B<MUST NOT> be used | |
1328 | as it is corrupted. | |
a91dedca | 1329 | |
8fa4d95e | 1330 | =head2 GCM and OCB Modes |
a91dedca | 1331 | |
8fa4d95e | 1332 | The following I<ctrl>s are supported in GCM and OCB modes. |
a91dedca | 1333 | |
8fa4d95e | 1334 | =over 4 |
a91dedca | 1335 | |
8fa4d95e | 1336 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL) |
a91dedca | 1337 | |
8fa4d95e RT |
1338 | Sets the IV length. This call can only be made before specifying an IV. If |
1339 | not called a default IV length is used. | |
a91dedca | 1340 | |
8fa4d95e RT |
1341 | For GCM AES and OCB AES the default is 12 (i.e. 96 bits). For OCB mode the |
1342 | maximum is 15. | |
a91dedca | 1343 | |
8fa4d95e | 1344 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag) |
a91dedca | 1345 | |
8fa4d95e RT |
1346 | Writes C<taglen> bytes of the tag value to the buffer indicated by C<tag>. |
1347 | This call can only be made when encrypting data and B<after> all data has been | |
1348 | processed (e.g. after an EVP_EncryptFinal() call). | |
a91dedca | 1349 | |
8fa4d95e RT |
1350 | For OCB, C<taglen> must either be 16 or the value previously set via |
1351 | B<EVP_CTRL_AEAD_SET_TAG>. | |
a91dedca | 1352 | |
8fa4d95e | 1353 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag) |
a91dedca | 1354 | |
3607b8ad | 1355 | When decrypting, this call sets the expected tag to C<taglen> bytes from C<tag>. |
8fa4d95e | 1356 | C<taglen> must be between 1 and 16 inclusive. |
3607b8ad MC |
1357 | The tag must be set prior to any call to EVP_DecryptFinal() or |
1358 | EVP_DecryptFinal_ex(). | |
a91dedca | 1359 | |
8fa4d95e | 1360 | For GCM, this call is only valid when decrypting data. |
a91dedca | 1361 | |
8fa4d95e | 1362 | For OCB, this call is valid when decrypting data to set the expected tag, |
3607b8ad | 1363 | and when encrypting to set the desired tag length. |
a91dedca | 1364 | |
3607b8ad MC |
1365 | In OCB mode, calling this when encrypting with C<tag> set to C<NULL> sets the |
1366 | tag length. The tag length can only be set before specifying an IV. If this is | |
1367 | not called prior to setting the IV during encryption, then a default tag length | |
1368 | is used. | |
a91dedca | 1369 | |
8fa4d95e RT |
1370 | For OCB AES, the default tag length is 16 (i.e. 128 bits). It is also the |
1371 | maximum tag length for OCB. | |
a91dedca | 1372 | |
8fa4d95e | 1373 | =back |
a91dedca | 1374 | |
8fa4d95e | 1375 | =head2 CCM Mode |
a91dedca | 1376 | |
8fa4d95e RT |
1377 | The EVP interface for CCM mode is similar to that of the GCM mode but with a |
1378 | few additional requirements and different I<ctrl> values. | |
aa714f3a | 1379 | |
8fa4d95e RT |
1380 | For CCM mode, the total plaintext or ciphertext length B<MUST> be passed to |
1381 | EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output | |
b9098d4e SL |
1382 | and input parameters (I<in> and I<out>) set to B<NULL> and the length passed in |
1383 | the I<inl> parameter. | |
e4bbee96 | 1384 | |
8fa4d95e | 1385 | The following I<ctrl>s are supported in CCM mode. |
e4bbee96 | 1386 | |
8fa4d95e | 1387 | =over 4 |
aa714f3a | 1388 | |
8fa4d95e | 1389 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag) |
aa714f3a | 1390 | |
8fa4d95e RT |
1391 | This call is made to set the expected B<CCM> tag value when decrypting or |
1392 | the length of the tag (with the C<tag> parameter set to NULL) when encrypting. | |
1393 | The tag length is often referred to as B<M>. If not set a default value is | |
67c81ec3 TN |
1394 | used (12 for AES). When decrypting, the tag needs to be set before passing |
1395 | in data to be decrypted, but as in GCM and OCB mode, it can be set after | |
485d3361 | 1396 | passing additional authenticated data (see L</AEAD INTERFACE>). |
aa714f3a | 1397 | |
8fa4d95e | 1398 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL) |
625b9d6b | 1399 | |
8fa4d95e | 1400 | Sets the CCM B<L> value. If not set a default is used (8 for AES). |
625b9d6b | 1401 | |
8fa4d95e | 1402 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL) |
625b9d6b | 1403 | |
57cd10dd | 1404 | Sets the CCM nonce (IV) length. This call can only be made before specifying a |
8fa4d95e RT |
1405 | nonce value. The nonce length is given by B<15 - L> so it is 7 by default for |
1406 | AES. | |
625b9d6b | 1407 | |
a91dedca DSH |
1408 | =back |
1409 | ||
b1ceb439 TS |
1410 | =head2 SIV Mode |
1411 | ||
0113ec84 TS |
1412 | Both the AES-SIV and AES-GCM-SIV ciphers fall under this mode. |
1413 | ||
b1ceb439 TS |
1414 | For SIV mode ciphers the behaviour of the EVP interface is subtly |
1415 | altered and several additional ctrl operations are supported. | |
1416 | ||
1417 | To specify any additional authenticated data (AAD) and/or a Nonce, a call to | |
1418 | EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made | |
b9098d4e | 1419 | with the output parameter I<out> set to B<NULL>. |
b1ceb439 TS |
1420 | |
1421 | RFC5297 states that the Nonce is the last piece of AAD before the actual | |
1422 | encrypt/decrypt takes place. The API does not differentiate the Nonce from | |
1423 | other AAD. | |
1424 | ||
1425 | When decrypting the return value of EVP_DecryptFinal() or EVP_CipherFinal() | |
1426 | indicates if the operation was successful. If it does not indicate success | |
1427 | the authentication operation has failed and any output data B<MUST NOT> | |
1428 | be used as it is corrupted. | |
1429 | ||
9cef2a70 TS |
1430 | The API does not store the the SIV (Synthetic Initialization Vector) in |
1431 | the cipher text. Instead, it is stored as the tag within the EVP_CIPHER_CTX. | |
1432 | The SIV must be retrieved from the context after encryption, and set into | |
1433 | the context before decryption. | |
1434 | ||
1435 | This differs from RFC5297 in that the cipher output from encryption, and | |
1436 | the cipher input to decryption, does not contain the SIV. This also means | |
1437 | that the plain text and cipher text lengths are identical. | |
1438 | ||
1439 | The following ctrls are supported in SIV mode, and are used to get and set | |
1440 | the Synthetic Initialization Vector: | |
b1ceb439 TS |
1441 | |
1442 | =over 4 | |
1443 | ||
1444 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag); | |
1445 | ||
9cef2a70 TS |
1446 | Writes I<taglen> bytes of the tag value (the Synthetic Initialization Vector) |
1447 | to the buffer indicated by I<tag>. This call can only be made when encrypting | |
1448 | data and B<after> all data has been processed (e.g. after an EVP_EncryptFinal() | |
1449 | call). For SIV mode the taglen must be 16. | |
b1ceb439 TS |
1450 | |
1451 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag); | |
1452 | ||
9cef2a70 TS |
1453 | Sets the expected tag (the Synthetic Initialization Vector) to I<taglen> |
1454 | bytes from I<tag>. This call is only legal when decrypting data and must be | |
1455 | made B<before> any data is processed (e.g. before any EVP_DecryptUpdate() | |
1456 | calls). For SIV mode the taglen must be 16. | |
b1ceb439 TS |
1457 | |
1458 | =back | |
1459 | ||
1460 | SIV mode makes two passes over the input data, thus, only one call to | |
1461 | EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made | |
9cef2a70 | 1462 | with I<out> set to a non-B<NULL> value. A call to EVP_DecryptFinal() or |
b1ceb439 TS |
1463 | EVP_CipherFinal() is not required, but will indicate if the update |
1464 | operation succeeded. | |
1465 | ||
8fa4d95e | 1466 | =head2 ChaCha20-Poly1305 |
aa714f3a | 1467 | |
8fa4d95e | 1468 | The following I<ctrl>s are supported for the ChaCha20-Poly1305 AEAD algorithm. |
aa714f3a | 1469 | |
8fa4d95e | 1470 | =over 4 |
aa714f3a | 1471 | |
8fa4d95e | 1472 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL) |
aa714f3a | 1473 | |
a0115237 | 1474 | Sets the nonce length. This call is now redundant since the only valid value |
1475 | is the default length of 12 (i.e. 96 bits). | |
1476 | Prior to OpenSSL 3.0 a nonce of less than 12 bytes could be used to automatically | |
1477 | pad the iv with leading 0 bytes to make it 12 bytes in length. | |
c7497f34 | 1478 | |
8fa4d95e | 1479 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag) |
aa714f3a | 1480 | |
8fa4d95e | 1481 | Writes C<taglen> bytes of the tag value to the buffer indicated by C<tag>. |
aa714f3a | 1482 | This call can only be made when encrypting data and B<after> all data has been |
8fa4d95e | 1483 | processed (e.g. after an EVP_EncryptFinal() call). |
c7497f34 | 1484 | |
8fa4d95e RT |
1485 | C<taglen> specified here must be 16 (B<POLY1305_BLOCK_SIZE>, i.e. 128-bits) or |
1486 | less. | |
aa714f3a | 1487 | |
8fa4d95e | 1488 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag) |
aa714f3a | 1489 | |
8fa4d95e RT |
1490 | Sets the expected tag to C<taglen> bytes from C<tag>. |
1491 | The tag length can only be set before specifying an IV. | |
1492 | C<taglen> must be between 1 and 16 (B<POLY1305_BLOCK_SIZE>) inclusive. | |
1493 | This call is only valid when decrypting data. | |
aa714f3a | 1494 | |
8fa4d95e | 1495 | =back |
aa714f3a | 1496 | |
72b60351 DSH |
1497 | =head1 NOTES |
1498 | ||
1499 | Where possible the B<EVP> interface to symmetric ciphers should be used in | |
8c1cbc72 | 1500 | preference to the low-level interfaces. This is because the code then becomes |
75b76068 JW |
1501 | transparent to the cipher used and much more flexible. Additionally, the |
1502 | B<EVP> interface will ensure the use of platform specific cryptographic | |
8c1cbc72 | 1503 | acceleration such as AES-NI (the low-level interfaces do not provide the |
75b76068 | 1504 | guarantee). |
72b60351 | 1505 | |
c7497f34 | 1506 | PKCS padding works by adding B<n> padding bytes of value B<n> to make the total |
72b60351 DSH |
1507 | length of the encrypted data a multiple of the block size. Padding is always |
1508 | added so if the data is already a multiple of the block size B<n> will equal | |
1509 | the block size. For example if the block size is 8 and 11 bytes are to be | |
1510 | encrypted then 5 padding bytes of value 5 will be added. | |
1511 | ||
1512 | When decrypting the final block is checked to see if it has the correct form. | |
1513 | ||
f2e5ca84 DSH |
1514 | Although the decryption operation can produce an error if padding is enabled, |
1515 | it is not a strong test that the input data or key is correct. A random block | |
1516 | has better than 1 in 256 chance of being of the correct format and problems with | |
1517 | the input data earlier on will not produce a final decrypt error. | |
1518 | ||
1519 | If padding is disabled then the decryption operation will always succeed if | |
1520 | the total amount of data decrypted is a multiple of the block size. | |
72b60351 | 1521 | |
97aede68 SL |
1522 | The functions EVP_EncryptInit(), EVP_EncryptInit_ex(), |
1523 | EVP_EncryptFinal(), EVP_DecryptInit(), EVP_DecryptInit_ex(), | |
1524 | EVP_CipherInit(), EVP_CipherInit_ex() and EVP_CipherFinal() are obsolete | |
1036bb64 P |
1525 | but are retained for compatibility with existing code. New code should |
1526 | use EVP_EncryptInit_ex2(), EVP_EncryptFinal_ex(), EVP_DecryptInit_ex2(), | |
1527 | EVP_DecryptFinal_ex(), EVP_CipherInit_ex2() and EVP_CipherFinal_ex() | |
1528 | because they can reuse an existing context without allocating and freeing | |
1529 | it up on each call. | |
a91dedca | 1530 | |
32745fcc DB |
1531 | There are some differences between functions EVP_CipherInit() and |
1532 | EVP_CipherInit_ex(), significant in some circumstances. EVP_CipherInit() fills | |
1533 | the passed context object with zeros. As a consequence, EVP_CipherInit() does | |
1534 | not allow step-by-step initialization of the ctx when the I<key> and I<iv> are | |
1535 | passed in separate calls. It also means that the flags set for the CTX are | |
1536 | removed, and it is especially important for the | |
1537 | B<EVP_CIPHER_CTX_FLAG_WRAP_ALLOW> flag treated specially in | |
1538 | EVP_CipherInit_ex(). | |
1539 | ||
d4c5d8ff TM |
1540 | Ignoring failure returns of the B<EVP_CIPHER_CTX> initialization functions can |
1541 | lead to subsequent undefined behavior when calling the functions that update or | |
1542 | finalize the context. The only valid calls on the B<EVP_CIPHER_CTX> when | |
1543 | initialization fails are calls that attempt another initialization of the | |
1544 | context or release the context. | |
1545 | ||
91da5e77 RS |
1546 | EVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as macros. |
1547 | ||
72b60351 DSH |
1548 | =head1 BUGS |
1549 | ||
8fa4d95e RT |
1550 | B<EVP_MAX_KEY_LENGTH> and B<EVP_MAX_IV_LENGTH> only refer to the internal |
1551 | ciphers with default key lengths. If custom ciphers exceed these values the | |
1552 | results are unpredictable. This is because it has become standard practice to | |
1553 | define a generic key as a fixed unsigned char array containing | |
1554 | B<EVP_MAX_KEY_LENGTH> bytes. | |
a91dedca | 1555 | |
c8973693 | 1556 | The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested |
a91dedca DSH |
1557 | for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode. |
1558 | ||
1559 | =head1 EXAMPLES | |
1560 | ||
fd4592be | 1561 | Encrypt a string using IDEA: |
18135561 DSH |
1562 | |
1563 | int do_crypt(char *outfile) | |
2947af32 BB |
1564 | { |
1565 | unsigned char outbuf[1024]; | |
1566 | int outlen, tmplen; | |
1567 | /* | |
1568 | * Bogus key and IV: we'd normally set these from | |
1569 | * another source. | |
1570 | */ | |
1571 | unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; | |
1572 | unsigned char iv[] = {1,2,3,4,5,6,7,8}; | |
1573 | char intext[] = "Some Crypto Text"; | |
1574 | EVP_CIPHER_CTX *ctx; | |
1575 | FILE *out; | |
1576 | ||
1577 | ctx = EVP_CIPHER_CTX_new(); | |
d4c5d8ff TM |
1578 | if (!EVP_EncryptInit_ex2(ctx, EVP_idea_cbc(), key, iv, NULL)) { |
1579 | /* Error */ | |
1580 | EVP_CIPHER_CTX_free(ctx); | |
1581 | return 0; | |
1582 | } | |
2947af32 BB |
1583 | |
1584 | if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) { | |
1585 | /* Error */ | |
519a5d1e | 1586 | EVP_CIPHER_CTX_free(ctx); |
2947af32 BB |
1587 | return 0; |
1588 | } | |
1589 | /* | |
1590 | * Buffer passed to EVP_EncryptFinal() must be after data just | |
1591 | * encrypted to avoid overwriting it. | |
1592 | */ | |
1593 | if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) { | |
1594 | /* Error */ | |
519a5d1e | 1595 | EVP_CIPHER_CTX_free(ctx); |
2947af32 BB |
1596 | return 0; |
1597 | } | |
1598 | outlen += tmplen; | |
1599 | EVP_CIPHER_CTX_free(ctx); | |
1600 | /* | |
1601 | * Need binary mode for fopen because encrypted data is | |
1602 | * binary data. Also cannot use strlen() on it because | |
1603 | * it won't be NUL terminated and may contain embedded | |
1604 | * NULs. | |
1605 | */ | |
1606 | out = fopen(outfile, "wb"); | |
519a5d1e GZ |
1607 | if (out == NULL) { |
1608 | /* Error */ | |
1609 | return 0; | |
1610 | } | |
2947af32 BB |
1611 | fwrite(outbuf, 1, outlen, out); |
1612 | fclose(out); | |
1613 | return 1; | |
1614 | } | |
18135561 DSH |
1615 | |
1616 | The ciphertext from the above example can be decrypted using the B<openssl> | |
fd4592be | 1617 | utility with the command line (shown on two lines for clarity): |
c7497f34 | 1618 | |
2947af32 BB |
1619 | openssl idea -d \ |
1620 | -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 <filename | |
18135561 | 1621 | |
fd4592be JS |
1622 | General encryption and decryption function example using FILE I/O and AES128 |
1623 | with a 128-bit key: | |
18135561 DSH |
1624 | |
1625 | int do_crypt(FILE *in, FILE *out, int do_encrypt) | |
2947af32 BB |
1626 | { |
1627 | /* Allow enough space in output buffer for additional block */ | |
1628 | unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; | |
1629 | int inlen, outlen; | |
1630 | EVP_CIPHER_CTX *ctx; | |
1631 | /* | |
1632 | * Bogus key and IV: we'd normally set these from | |
1633 | * another source. | |
1634 | */ | |
1635 | unsigned char key[] = "0123456789abcdeF"; | |
1636 | unsigned char iv[] = "1234567887654321"; | |
1637 | ||
1638 | /* Don't set key or IV right away; we want to check lengths */ | |
1639 | ctx = EVP_CIPHER_CTX_new(); | |
d4c5d8ff TM |
1640 | if (!EVP_CipherInit_ex2(ctx, EVP_aes_128_cbc(), NULL, NULL, |
1641 | do_encrypt, NULL)) { | |
1642 | /* Error */ | |
1643 | EVP_CIPHER_CTX_free(ctx); | |
1644 | return 0; | |
1645 | } | |
ed576acd TM |
1646 | OPENSSL_assert(EVP_CIPHER_CTX_get_key_length(ctx) == 16); |
1647 | OPENSSL_assert(EVP_CIPHER_CTX_get_iv_length(ctx) == 16); | |
2947af32 BB |
1648 | |
1649 | /* Now we can set key and IV */ | |
d4c5d8ff TM |
1650 | if (!EVP_CipherInit_ex2(ctx, NULL, key, iv, do_encrypt, NULL)) { |
1651 | /* Error */ | |
1652 | EVP_CIPHER_CTX_free(ctx); | |
1653 | return 0; | |
1654 | } | |
2947af32 BB |
1655 | |
1656 | for (;;) { | |
1657 | inlen = fread(inbuf, 1, 1024, in); | |
1658 | if (inlen <= 0) | |
1659 | break; | |
1660 | if (!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, inlen)) { | |
1661 | /* Error */ | |
1662 | EVP_CIPHER_CTX_free(ctx); | |
1663 | return 0; | |
1664 | } | |
1665 | fwrite(outbuf, 1, outlen, out); | |
1666 | } | |
1667 | if (!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) { | |
1668 | /* Error */ | |
1669 | EVP_CIPHER_CTX_free(ctx); | |
1670 | return 0; | |
1671 | } | |
1672 | fwrite(outbuf, 1, outlen, out); | |
1673 | ||
1674 | EVP_CIPHER_CTX_free(ctx); | |
1675 | return 1; | |
1676 | } | |
18135561 | 1677 | |
7cc355c2 SL |
1678 | Encryption using AES-CBC with a 256-bit key with "CS1" ciphertext stealing. |
1679 | ||
1680 | int encrypt(const unsigned char *key, const unsigned char *iv, | |
1681 | const unsigned char *msg, size_t msg_len, unsigned char *out) | |
1682 | { | |
1683 | /* | |
1684 | * This assumes that key size is 32 bytes and the iv is 16 bytes. | |
1685 | * For ciphertext stealing mode the length of the ciphertext "out" will be | |
1686 | * the same size as the plaintext size "msg_len". | |
1687 | * The "msg_len" can be any size >= 16. | |
1688 | */ | |
1689 | int ret = 0, encrypt = 1, outlen, len; | |
1690 | EVP_CIPHER_CTX *ctx = NULL; | |
1691 | EVP_CIPHER *cipher = NULL; | |
1692 | OSSL_PARAM params[2]; | |
1693 | ||
1694 | ctx = EVP_CIPHER_CTX_new(); | |
1695 | cipher = EVP_CIPHER_fetch(NULL, "AES-256-CBC-CTS", NULL); | |
1696 | if (ctx == NULL || cipher == NULL) | |
1697 | goto err; | |
1698 | ||
7cc355c2 SL |
1699 | /* |
1700 | * The default is "CS1" so this is not really needed, | |
1701 | * but would be needed to set either "CS2" or "CS3". | |
1702 | */ | |
1703 | params[0] = OSSL_PARAM_construct_utf8_string(OSSL_CIPHER_PARAM_CTS_MODE, | |
1704 | "CS1", 0); | |
1705 | params[1] = OSSL_PARAM_construct_end(); | |
1036bb64 P |
1706 | |
1707 | if (!EVP_CipherInit_ex2(ctx, cipher, key, iv, encrypt, params)) | |
7cc355c2 SL |
1708 | goto err; |
1709 | ||
1710 | /* NOTE: CTS mode does not support multiple calls to EVP_CipherUpdate() */ | |
0dbd3a81 | 1711 | if (!EVP_CipherUpdate(ctx, out, &outlen, msg, msg_len)) |
7cc355c2 | 1712 | goto err; |
0dbd3a81 | 1713 | if (!EVP_CipherFinal_ex(ctx, out + outlen, &len)) |
7cc355c2 SL |
1714 | goto err; |
1715 | ret = 1; | |
1716 | err: | |
1717 | EVP_CIPHER_free(cipher); | |
1718 | EVP_CIPHER_CTX_free(ctx); | |
1719 | return ret; | |
1720 | } | |
18135561 | 1721 | |
72b60351 DSH |
1722 | =head1 SEE ALSO |
1723 | ||
b1307e94 P |
1724 | L<evp(7)>, |
1725 | L<property(7)>, | |
1726 | L<crypto(7)/ALGORITHM FETCHING>, | |
1727 | L<provider-cipher(7)>, | |
1728 | L<life_cycle-cipher(7)> | |
72b60351 | 1729 | |
8fa4d95e RT |
1730 | Supported ciphers are listed in: |
1731 | ||
d7cea0b8 RS |
1732 | L<EVP_aes_128_gcm(3)>, |
1733 | L<EVP_aria_128_gcm(3)>, | |
1734 | L<EVP_bf_cbc(3)>, | |
1735 | L<EVP_camellia_128_ecb(3)>, | |
1736 | L<EVP_cast5_cbc(3)>, | |
8fa4d95e | 1737 | L<EVP_chacha20(3)>, |
d7cea0b8 RS |
1738 | L<EVP_des_cbc(3)>, |
1739 | L<EVP_desx_cbc(3)>, | |
1740 | L<EVP_idea_cbc(3)>, | |
1741 | L<EVP_rc2_cbc(3)>, | |
8fa4d95e | 1742 | L<EVP_rc4(3)>, |
d7cea0b8 RS |
1743 | L<EVP_rc5_32_12_16_cbc(3)>, |
1744 | L<EVP_seed_cbc(3)>, | |
b1307e94 | 1745 | L<EVP_sm4_cbc(3)>, |
8fa4d95e | 1746 | |
72b60351 DSH |
1747 | =head1 HISTORY |
1748 | ||
fc5ecadd | 1749 | Support for OCB mode was added in OpenSSL 1.1.0. |
a528d4f0 | 1750 | |
05fdb8d3 RL |
1751 | B<EVP_CIPHER_CTX> was made opaque in OpenSSL 1.1.0. As a result, |
1752 | EVP_CIPHER_CTX_reset() appeared and EVP_CIPHER_CTX_cleanup() | |
1753 | disappeared. EVP_CIPHER_CTX_init() remains as an alias for | |
1754 | EVP_CIPHER_CTX_reset(). | |
1755 | ||
f6c95e46 RS |
1756 | The EVP_CIPHER_CTX_cipher() function was deprecated in OpenSSL 3.0; use |
1757 | EVP_CIPHER_CTX_get0_cipher() instead. | |
1758 | ||
1036bb64 P |
1759 | The EVP_EncryptInit_ex2(), EVP_DecryptInit_ex2(), EVP_CipherInit_ex2(), |
1760 | EVP_CIPHER_fetch(), EVP_CIPHER_free(), EVP_CIPHER_up_ref(), | |
f6c95e46 | 1761 | EVP_CIPHER_CTX_get0_cipher(), EVP_CIPHER_CTX_get1_cipher(), |
fe20a66e P |
1762 | EVP_CIPHER_get_params(), EVP_CIPHER_CTX_set_params(), |
1763 | EVP_CIPHER_CTX_get_params(), EVP_CIPHER_gettable_params(), | |
1764 | EVP_CIPHER_settable_ctx_params(), EVP_CIPHER_gettable_ctx_params(), | |
1765 | EVP_CIPHER_CTX_settable_params() and EVP_CIPHER_CTX_gettable_params() | |
1766 | functions were added in 3.0. | |
550f974a | 1767 | |
31b7f23d TM |
1768 | The EVP_CIPHER_nid(), EVP_CIPHER_name(), EVP_CIPHER_block_size(), |
1769 | EVP_CIPHER_key_length(), EVP_CIPHER_iv_length(), EVP_CIPHER_flags(), | |
1770 | EVP_CIPHER_mode(), EVP_CIPHER_type(), EVP_CIPHER_CTX_nid(), | |
1771 | EVP_CIPHER_CTX_block_size(), EVP_CIPHER_CTX_key_length(), | |
1772 | EVP_CIPHER_CTX_iv_length(), EVP_CIPHER_CTX_tag_length(), | |
1773 | EVP_CIPHER_CTX_num(), EVP_CIPHER_CTX_type(), and EVP_CIPHER_CTX_mode() | |
1774 | functions were renamed to include C<get> or C<get0> in their names in | |
1775 | OpenSSL 3.0, respectively. The old names are kept as non-deprecated | |
1776 | alias macros. | |
1777 | ||
1778 | The EVP_CIPHER_CTX_encrypting() function was renamed to | |
1779 | EVP_CIPHER_CTX_is_encrypting() in OpenSSL 3.0. The old name is kept as | |
1780 | non-deprecated alias macro. | |
1781 | ||
ed576acd TM |
1782 | The EVP_CIPHER_CTX_flags() macro was deprecated in OpenSSL 1.1.0. |
1783 | ||
45ada6b9 | 1784 | EVP_CIPHER_CTX_dup() was added in OpenSSL 3.2. |
0324ae3e | 1785 | |
e2f92610 RS |
1786 | =head1 COPYRIGHT |
1787 | ||
da1c088f | 1788 | Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 1789 | |
4746f25a | 1790 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
1791 | this file except in compliance with the License. You can obtain a copy |
1792 | in the file LICENSE in the source distribution or at | |
1793 | L<https://www.openssl.org/source/license.html>. | |
1794 | ||
1795 | =cut |