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