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