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(3) array that describes the retrievable
252 parameters that can be used with EVP_CIPHER_get_params().
253 EVP_CIPHER_gettable_ctx_params() and EVP_CIPHER_CTX_gettable_params()
255 Get a constant OSSL_PARAM(3) array that describes the retrievable
256 parameters that can be used with EVP_CIPHER_CTX_get_params().
257 EVP_CIPHER_gettable_ctx_params() returns the parameters that can be
258 retrieved from the algorithm, whereas
259 EVP_CIPHER_CTX_gettable_params() returns the parameters that can be
260 retrieved in the context's current state.
261 EVP_CIPHER_settable_ctx_params() and EVP_CIPHER_CTX_settable_params()
263 Get a constant OSSL_PARAM(3) array that describes the settable
264 parameters that can be used with EVP_CIPHER_CTX_set_params().
265 EVP_CIPHER_settable_ctx_params() returns the parameters that can be
266 set from the algorithm, whereas EVP_CIPHER_CTX_settable_params()
267 returns the parameters that can be set in the context's current
268 state.
269 EVP_EncryptInit_ex2()
271 Sets up cipher context ctx for encryption with cipher type. type is
272 typically supplied by calling EVP_CIPHER_fetch(). type may also be
273 set using legacy functions such as EVP_aes_256_cbc(), but this is
274 not recommended for new applications. key is the symmetric key to
275 use and iv is the IV to use (if necessary), the actual number of
276 bytes used for the key and IV depends on the cipher. The parameters
277 params will be set on the context after initialisation. It is
278 possible to set all parameters to NULL except type in an initial
279 call and supply the remaining parameters in subsequent calls, all
280 of which have type set to NULL. This is done when the default
281 cipher parameters are not appropriate. For EVP_CIPH_GCM_MODE the
282 IV will be generated internally if it is not specified.
283 EVP_EncryptInit_ex()
285 This legacy function is similar to EVP_EncryptInit_ex2() when impl
286 is NULL. The implementation of the type from the impl engine will
287 be used if it exists.
288 EVP_EncryptUpdate()
290 Encrypts inl bytes from the buffer in and writes the encrypted
291 version to out. This function can be called multiple times to
292 encrypt successive blocks of data. The amount of data written
293 depends on the block alignment of the encrypted data. For most
294 ciphers and modes, the amount of data written can be anything from
295 zero bytes to (inl + cipher_block_size - 1) bytes. For wrap cipher
296 modes, the amount of data written can be anything from zero bytes
297 to (inl + cipher_block_size) bytes. For stream ciphers, the amount
298 of data written can be anything from zero bytes to inl bytes.
299 Thus, out should contain sufficient room for the operation being
300 performed. The actual number of bytes written is placed in outl.
301 It also checks if in and out are partially overlapping, and if they
302 are 0 is returned to indicate failure.
303 If padding is enabled (the default) then EVP_EncryptFinal_ex()
305 encrypts the "final" data, that is any data that remains in a
306 partial block. It uses standard block padding (aka PKCS padding)
307 as described in the NOTES section, below. The encrypted final data
308 is written to out which should have sufficient space for one cipher
309 block. The number of bytes written is placed in outl. After this
310 function is called the encryption operation is finished and no
311 further calls to EVP_EncryptUpdate() should be made.
312 If padding is disabled then EVP_EncryptFinal_ex() will not encrypt
314 any more data and it will return an error if any data remains in a
315 partial block: that is if the total data length is not a multiple
316 of the block size.
317 EVP_DecryptInit_ex2(), EVP_DecryptInit_ex(), EVP_DecryptUpdate() and
319 EVP_DecryptFinal_ex()
320 These functions are the corresponding decryption operations.
321 EVP_DecryptFinal() will return an error code if padding is enabled
322 and the final block is not correctly formatted. The parameters and
323 restrictions are identical to the encryption operations except that
324 if padding is enabled the decrypted data buffer out passed to
325 EVP_DecryptUpdate() should have sufficient room for (inl +
326 cipher_block_size) bytes unless the cipher block size is 1 in which
327 case inl bytes is sufficient.
328 EVP_CipherInit_ex2(), EVP_CipherInit_ex(), EVP_CipherUpdate() and
330 EVP_CipherFinal_ex()
331 These functions can be used for decryption or encryption. The
332 operation performed depends on the value of the enc parameter. It
333 should be set to 1 for encryption, 0 for decryption and -1 to leave
334 the value unchanged (the actual value of 'enc' being supplied in a
335 previous call).
336 EVP_CIPHER_CTX_reset()
338 Clears all information from a cipher context and free up any
339 allocated memory associated with it, except the ctx itself. This
340 function should be called anytime ctx is reused by another
341 EVP_CipherInit() / EVP_CipherUpdate() / EVP_CipherFinal() series of
342 calls.
343 EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit()
345 Behave in a similar way to EVP_EncryptInit_ex(),
346 EVP_DecryptInit_ex() and EVP_CipherInit_ex() except if the type is
347 not a fetched cipher they use the default implementation of the
348 type.
349 EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal()
351 Identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and
352 EVP_CipherFinal_ex(). In previous releases they also cleaned up the
353 ctx, but this is no longer done and EVP_CIPHER_CTX_cleanup() must
354 be called to free any context resources.
355 EVP_Cipher()
357 Encrypts or decrypts a maximum inl amount of bytes from in and
358 leaves the result in out.
359 For legacy ciphers - If the cipher doesn't have the flag
361 EVP_CIPH_FLAG_CUSTOM_CIPHER set, then inl must be a multiple of
362 EVP_CIPHER_get_block_size(). If it isn't, the result is undefined.
363 If the cipher has that flag set, then inl can be any size.
364 Due to the constraints of the API contract of this function it
366 shouldn't be used in applications, please consider using
367 EVP_CipherUpdate() and EVP_CipherFinal_ex() instead.
368 EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
370 Returns an EVP_CIPHER structure when passed a cipher name, a cipher
371 NID or an ASN1_OBJECT structure respectively.
372 EVP_get_cipherbyname() will return NULL for algorithms such as
374 "AES-128-SIV", "AES-128-CBC-CTS" and "CAMELLIA-128-CBC-CTS" which
375 were previously only accessible via low level interfaces.
376 The EVP_get_cipherbyname() function is present for backwards
378 compatibility with OpenSSL prior to version 3 and is different to
379 the EVP_CIPHER_fetch() function since it does not attempt to
380 "fetch" an implementation of the cipher. Additionally, it only
381 knows about ciphers that are built-in to OpenSSL and have an
382 associated NID. Similarly EVP_get_cipherbynid() and
383 EVP_get_cipherbyobj() also return objects without an associated
384 implementation.
385 When the cipher objects returned by these functions are used (such
387 as in a call to EVP_EncryptInit_ex()) an implementation of the
388 cipher will be implicitly fetched from the loaded providers. This
389 fetch could fail if no suitable implementation is available. Use
390 EVP_CIPHER_fetch() instead to explicitly fetch the algorithm and an
391 associated implementation from a provider.
392 See "ALGORITHM FETCHING" in crypto(7) for more information about
394 fetching.
395 The cipher objects returned from these functions do not need to be
397 freed with EVP_CIPHER_free().
398 EVP_CIPHER_get_nid() and EVP_CIPHER_CTX_get_nid()
400 Return the NID of a cipher when passed an EVP_CIPHER or
401 EVP_CIPHER_CTX structure. The actual NID value is an internal
402 value which may not have a corresponding OBJECT IDENTIFIER.
403 EVP_CIPHER_CTX_set_flags(), EVP_CIPHER_CTX_clear_flags() and
405 EVP_CIPHER_CTX_test_flags()
406 Sets, clears and tests ctx flags. See "FLAGS" below for more
407 information.
408 For provided ciphers EVP_CIPHER_CTX_set_flags() should be called
410 only after the fetched cipher has been assigned to the ctx. It is
411 recommended to use "PARAMETERS" instead.
412 EVP_CIPHER_CTX_set_padding()
414 Enables or disables padding. This function should be called after
415 the context is set up for encryption or decryption with
416 EVP_EncryptInit_ex2(), EVP_DecryptInit_ex2() or
417 EVP_CipherInit_ex2(). By default encryption operations are padded
418 using standard block padding and the padding is checked and removed
419 when decrypting. If the pad parameter is zero then no padding is
420 performed, the total amount of data encrypted or decrypted must
421 then be a multiple of the block size or an error will occur.
422 EVP_CIPHER_get_key_length() and EVP_CIPHER_CTX_get_key_length()
424 Return the key length of a cipher when passed an EVP_CIPHER or
425 EVP_CIPHER_CTX structure. The constant EVP_MAX_KEY_LENGTH is the
426 maximum key length for all ciphers. Note: although
427 EVP_CIPHER_get_key_length() is fixed for a given cipher, the value
428 of EVP_CIPHER_CTX_get_key_length() may be different for variable
429 key length ciphers.
430 EVP_CIPHER_CTX_set_key_length()
432 Sets the key length of the cipher context. If the cipher is a
433 fixed length cipher then attempting to set the key length to any
434 value other than the fixed value is an error.
435 EVP_CIPHER_get_iv_length() and EVP_CIPHER_CTX_get_iv_length()
437 Return the IV length of a cipher when passed an EVP_CIPHER or
438 EVP_CIPHER_CTX. It will return zero if the cipher does not use an
439 IV. The constant EVP_MAX_IV_LENGTH is the maximum IV length for
440 all ciphers.
441 EVP_CIPHER_CTX_get_tag_length()
443 Returns the tag length of an AEAD cipher when passed a
444 EVP_CIPHER_CTX. It will return zero if the cipher does not support
445 a tag. It returns a default value if the tag length has not been
446 set.
447 EVP_CIPHER_get_block_size() and EVP_CIPHER_CTX_get_block_size()
449 Return the block size of a cipher when passed an EVP_CIPHER or
450 EVP_CIPHER_CTX structure. The constant EVP_MAX_BLOCK_LENGTH is also
451 the maximum block length for all ciphers.
452 EVP_CIPHER_get_type() and EVP_CIPHER_CTX_get_type()
454 Return the type of the passed cipher or context. This "type" is the
455 actual NID of the cipher OBJECT IDENTIFIER and as such it ignores
456 the cipher parameters (40 bit RC2 and 128 bit RC2 have the same
457 NID). If the cipher does not have an object identifier or does not
458 have ASN1 support this function will return NID_undef.
459 EVP_CIPHER_is_a()
461 Returns 1 if cipher is an implementation of an algorithm that's
462 identifiable with name, otherwise 0. If cipher is a legacy cipher
463 (it's the return value from the likes of EVP_aes128() rather than
464 the result of an EVP_CIPHER_fetch()), only cipher names registered
465 with the default library context (see OSSL_LIB_CTX(3)) will be
466 considered.
467 EVP_CIPHER_get0_name() and EVP_CIPHER_CTX_get0_name()
469 Return the name of the passed cipher or context. For fetched
470 ciphers with multiple names, only one of them is returned. See also
471 EVP_CIPHER_names_do_all().
472 EVP_CIPHER_names_do_all()
474 Traverses all names for the cipher, and calls fn with each name and
475 data. This is only useful with fetched EVP_CIPHERs.
476 EVP_CIPHER_get0_description()
478 Returns a description of the cipher, meant for display and human
479 consumption. The description is at the discretion of the cipher
480 implementation.
481 EVP_CIPHER_get0_provider()
483 Returns an OSSL_PROVIDER pointer to the provider that implements
484 the given EVP_CIPHER.
485 EVP_CIPHER_CTX_get0_cipher()
487 Returns the EVP_CIPHER structure when passed an EVP_CIPHER_CTX
488 structure. EVP_CIPHER_CTX_get1_cipher() is the same except the
489 ownership is passed to the caller.
490 EVP_CIPHER_get_mode() and EVP_CIPHER_CTX_get_mode()
492 Return the block cipher mode: EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE,
493 EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, EVP_CIPH_CTR_MODE,
494 EVP_CIPH_GCM_MODE, EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE,
495 EVP_CIPH_WRAP_MODE, EVP_CIPH_OCB_MODE or EVP_CIPH_SIV_MODE. If the
496 cipher is a stream cipher then EVP_CIPH_STREAM_CIPHER is returned.
497 EVP_CIPHER_get_flags()
499 Returns any flags associated with the cipher. See "FLAGS" for a
500 list of currently defined flags.
501 EVP_CIPHER_CTX_get_num() and EVP_CIPHER_CTX_set_num()
503 Gets or sets the cipher specific "num" parameter for the associated
504 ctx. Built-in ciphers typically use this to track how much of the
505 current underlying block has been "used" already.
506 EVP_CIPHER_CTX_is_encrypting()
508 Reports whether the ctx is being used for encryption or decryption.
509 EVP_CIPHER_CTX_flags()
511 A deprecated macro calling
512 "EVP_CIPHER_get_flags(EVP_CIPHER_CTX_get0_cipher(ctx))". Do not
513 use.
514 EVP_CIPHER_param_to_asn1()
516 Sets the AlgorithmIdentifier "parameter" based on the passed
517 cipher. This will typically include any parameters and an IV. The
518 cipher IV (if any) must be set when this call is made. This call
519 should be made before the cipher is actually "used" (before any
520 EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This
521 function may fail if the cipher does not have any ASN1 support.
522 EVP_CIPHER_asn1_to_param()
524 Sets the cipher parameters based on an ASN1 AlgorithmIdentifier
525 "parameter". The precise effect depends on the cipher. In the case
526 of RC2, for example, it will set the IV and effective key length.
527 This function should be called after the base cipher type is set
528 but before the key is set. For example EVP_CipherInit() will be
529 called with the IV and key set to NULL, EVP_CIPHER_asn1_to_param()
530 will be called and finally EVP_CipherInit() again with all
531 parameters except the key set to NULL. It is possible for this
532 function to fail if the cipher does not have any ASN1 support or
533 the parameters cannot be set (for example the RC2 effective key
534 length is not supported.
535 EVP_CIPHER_CTX_rand_key()
537 Generates a random key of the appropriate length based on the
538 cipher context. The EVP_CIPHER can provide its own random key
539 generation routine to support keys of a specific form. key must
540 point to a buffer at least as big as the value returned by
541 EVP_CIPHER_CTX_get_key_length().
542 EVP_CIPHER_do_all_provided()
544 Traverses all ciphers implemented by all activated providers in the
545 given library context libctx, and for each of the implementations,
546 calls the given function fn with the implementation method and the
547 given arg as argument.
548
550 See OSSL_PARAM(3) for information about passing parameters.
551 Gettable EVP_CIPHER parameters
553 When EVP_CIPHER_fetch() is called it internally calls
554 EVP_CIPHER_get_params() and caches the results.
555 EVP_CIPHER_get_params() can be used with the following OSSL_PARAM(3)
557 keys:
558 "mode" (OSSL_CIPHER_PARAM_MODE) <unsigned integer>
560 Gets the mode for the associated cipher algorithm cipher. See
561 "EVP_CIPHER_get_mode() and EVP_CIPHER_CTX_get_mode()" for a list of
562 valid modes. Use EVP_CIPHER_get_mode() to retrieve the cached
563 value.
564 "keylen" (OSSL_CIPHER_PARAM_KEYLEN) <unsigned integer>
566 Gets the key length for the associated cipher algorithm cipher.
567 Use EVP_CIPHER_get_key_length() to retrieve the cached value.
568 "ivlen" (OSSL_CIPHER_PARAM_IVLEN) <unsigned integer>
570 Gets the IV length for the associated cipher algorithm cipher. Use
571 EVP_CIPHER_get_iv_length() to retrieve the cached value.
572 "blocksize" (OSSL_CIPHER_PARAM_BLOCK_SIZE) <unsigned integer>
574 Gets the block size for the associated cipher algorithm cipher.
575 The block size should be 1 for stream ciphers. Note that the block
576 size for a cipher may be different to the block size for the
577 underlying encryption/decryption primitive. For example AES in CTR
578 mode has a block size of 1 (because it operates like a stream
579 cipher), even though AES has a block size of 16. Use
580 EVP_CIPHER_get_block_size() to retreive the cached value.
581 "aead" (OSSL_CIPHER_PARAM_AEAD) <integer>
583 Gets 1 if this is an AEAD cipher algorithm, otherwise it gets 0.
584 Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_AEAD_CIPHER) to
585 retrieve the cached value.
586 "custom-iv" (OSSL_CIPHER_PARAM_CUSTOM_IV) <integer>
588 Gets 1 if the cipher algorithm cipher has a custom IV, otherwise it
589 gets 0. Storing and initializing the IV is left entirely to the
590 implementation, if a custom IV is used. Use
591 (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_CUSTOM_IV) to retrieve the
592 cached value.
593 "cts" (OSSL_CIPHER_PARAM_CTS) <integer>
595 Gets 1 if the cipher algorithm cipher uses ciphertext stealing,
596 otherwise it gets 0. This is currently used to indicate that the
597 cipher is a one shot that only allows a single call to
598 EVP_CipherUpdate(). Use (EVP_CIPHER_get_flags(cipher) &
599 EVP_CIPH_FLAG_CTS) to retrieve the cached value.
600 "tls-multi" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK) <integer>
602 Gets 1 if the cipher algorithm cipher supports interleaving of
603 crypto blocks, otherwise it gets 0. The interleaving is an
604 optimization only applicable to certain TLS ciphers. Use
605 (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK) to
606 retrieve the cached value.
607 "has-randkey" (OSSL_CIPHER_PARAM_HAS_RANDKEY) <integer>
609 Gets 1 if the cipher algorithm cipher supports the gettable
610 EVP_CIPHER_CTX parameter OSSL_CIPHER_PARAM_RANDOM_KEY. Only DES and
611 3DES set this to 1, all other OpenSSL ciphers return 0.
612 Gettable and Settable EVP_CIPHER_CTX parameters
614 The following OSSL_PARAM(3) keys can be used with both
615 EVP_CIPHER_CTX_get_params() and EVP_CIPHER_CTX_set_params().
616 "padding" (OSSL_CIPHER_PARAM_PADDING) <unsigned integer>
618 Gets or sets the padding mode for the cipher context ctx. Padding
619 is enabled if the value is 1, and disabled if the value is 0. See
620 also EVP_CIPHER_CTX_set_padding().
621 "num" (OSSL_CIPHER_PARAM_NUM) <unsigned integer>
623 Gets or sets the cipher specific "num" parameter for the cipher
624 context ctx. Built-in ciphers typically use this to track how much
625 of the current underlying block has been "used" already. See also
626 EVP_CIPHER_CTX_get_num() and EVP_CIPHER_CTX_set_num().
627 "keylen" (OSSL_CIPHER_PARAM_KEYLEN) <unsigned integer>
629 Gets or sets the key length for the cipher context ctx. The length
630 of the "keylen" parameter should not exceed that of a size_t. See
631 also EVP_CIPHER_CTX_get_key_length() and
632 EVP_CIPHER_CTX_set_key_length().
633 "tag" (OSSL_CIPHER_PARAM_AEAD_TAG) <octet string>
635 Gets or sets the AEAD tag for the associated cipher context ctx.
636 See "AEAD Interface" in EVP_EncryptInit(3).
637 "keybits" (OSSL_CIPHER_PARAM_RC2_KEYBITS) <unsigned integer>
639 Gets or sets the effective keybits used for a RC2 cipher. The
640 length of the "keybits" parameter should not exceed that of a
641 size_t.
642 "rounds" (OSSL_CIPHER_PARAM_ROUNDS) <unsigned integer>
644 Gets or sets the number of rounds to be used for a cipher. This is
645 used by the RC5 cipher.
646 "alg_id_param" (OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS) <octet string>
648 Used to pass the DER encoded AlgorithmIdentifier parameter to or
649 from the cipher implementation. Functions like
650 EVP_CIPHER_param_to_asn1(3) and EVP_CIPHER_asn1_to_param(3) use
651 this parameter for any implementation that has the flag
652 EVP_CIPH_FLAG_CUSTOM_ASN1 set.
653 "cts_mode" (OSSL_CIPHER_PARAM_CTS_MODE) <UTF8 string>
655 Gets or sets the cipher text stealing mode. For all modes the
656 output size is the same as the input size. The input length must be
657 greater than or equal to the block size. (The block size for AES
658 and CAMELLIA is 16 bytes).
659 Valid values for the mode are:
661 "CS1"
663 The NIST variant of cipher text stealing. For input lengths
664 that are multiples of the block size it is equivalent to using
665 a "AES-XXX-CBC" or "CAMELLIA-XXX-CBC" cipher otherwise the
666 second last cipher text block is a partial block.
667 "CS2"
669 For input lengths that are multiples of the block size it is
670 equivalent to using a "AES-XXX-CBC" or "CAMELLIA-XXX-CBC"
671 cipher, otherwise it is the same as "CS3" mode.
672 "CS3"
674 The Kerberos5 variant of cipher text stealing which always
675 swaps the last cipher text block with the previous block (which
676 may be a partial or full block depending on the input length).
677 If the input length is exactly one full block then this is
678 equivalent to using a "AES-XXX-CBC" or "CAMELLIA-XXX-CBC"
679 cipher.
680 The default is "CS1". This is only supported for
682 "AES-128-CBC-CTS", "AES-192-CBC-CTS", "AES-256-CBC-CTS",
683 "CAMELLIA-128-CBC-CTS", "CAMELLIA-192-CBC-CTS" and
684 "CAMELLIA-256-CBC-CTS".
685 "tls1multi_interleave" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE)
687 <unsigned integer>
688 Sets or gets the number of records being sent in one go for a tls1
689 multiblock cipher operation (either 4 or 8 records).
690 Gettable EVP_CIPHER_CTX parameters
692 The following OSSL_PARAM(3) keys can be used with
693 EVP_CIPHER_CTX_get_params():
694 "ivlen" (OSSL_CIPHER_PARAM_IVLEN and <OSSL_CIPHER_PARAM_AEAD_IVLEN)
696 <unsigned integer>
697 Gets the IV length for the cipher context ctx. The length of the
698 "ivlen" parameter should not exceed that of a size_t. See also
699 EVP_CIPHER_CTX_get_iv_length().
700 "iv" (OSSL_CIPHER_PARAM_IV) <octet string OR octet ptr>
702 Gets the IV used to initialize the associated cipher context ctx.
703 See also EVP_CIPHER_CTX_get_original_iv().
704 "updated-iv" (OSSL_CIPHER_PARAM_UPDATED_IV) <octet string OR octet ptr>
706 Gets the updated pseudo-IV state for the associated cipher context,
707 e.g., the previous ciphertext block for CBC mode or the iteratively
708 encrypted IV value for OFB mode. Note that octet pointer access is
709 deprecated and is provided only for backwards compatibility with
710 historical libcrypto APIs. See also
711 EVP_CIPHER_CTX_get_updated_iv().
712 "randkey" (OSSL_CIPHER_PARAM_RANDOM_KEY) <octet string>
714 Gets an implementation specific randomly generated key for the
715 associated cipher context ctx. This is currently only supported by
716 DES and 3DES (which set the key to odd parity).
717 "taglen" (OSSL_CIPHER_PARAM_AEAD_TAGLEN) <unsigned integer>
719 Gets the tag length to be used for an AEAD cipher for the
720 associated cipher context ctx. It gets a default value if it has
721 not been set. The length of the "taglen" parameter should not
722 exceed that of a size_t. See also EVP_CIPHER_CTX_get_tag_length().
723 "tlsaadpad" (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD) <unsigned integer>
725 Gets the length of the tag that will be added to a TLS record for
726 the AEAD tag for the associated cipher context ctx. The length of
727 the "tlsaadpad" parameter should not exceed that of a size_t.
728 "tlsivgen" (OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN) <octet string>
730 Gets the invocation field generated for encryption. Can only be
731 called after "tlsivfixed" is set. This is only used for GCM mode.
732 "tls1multi_enclen" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN)
734 <unsigned integer>
735 Get the total length of the record returned from the
736 "tls1multi_enc" operation.
737 "tls1multi_maxbufsz" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE)
739 <unsigned integer>
740 Gets the maximum record length for a TLS1 multiblock cipher
741 operation. The length of the "tls1multi_maxbufsz" parameter should
742 not exceed that of a size_t.
743 "tls1multi_aadpacklen" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN)
745 <unsigned integer>
746 Gets the result of running the "tls1multi_aad" operation.
747 "tls-mac" (OSSL_CIPHER_PARAM_TLS_MAC) <octet ptr>
749 Used to pass the TLS MAC data.
750 Settable EVP_CIPHER_CTX parameters
752 The following OSSL_PARAM(3) keys can be used with
753 EVP_CIPHER_CTX_set_params():
754 "mackey" (OSSL_CIPHER_PARAM_AEAD_MAC_KEY) <octet string>
756 Sets the MAC key used by composite AEAD ciphers such as
757 AES-CBC-HMAC-SHA256.
758 "speed" (OSSL_CIPHER_PARAM_SPEED) <unsigned integer>
760 Sets the speed option for the associated cipher context. This is
761 only supported by AES SIV ciphers which disallow multiple
762 operations by default. Setting "speed" to 1 allows another encrypt
763 or decrypt operation to be performed. This is used for performance
764 testing.
765 "use-bits" (OSSL_CIPHER_PARAM_USE_BITS) <unsigned integer>
767 Determines if the input length inl passed to EVP_EncryptUpdate(),
768 EVP_DecryptUpdate() and EVP_CipherUpdate() is the number of bits or
769 number of bytes. Setting "use-bits" to 1 uses bits. The default is
770 in bytes. This is only used for CFB1 ciphers.
771 This can be set using EVP_CIPHER_CTX_set_flags(ctx,
773 EVP_CIPH_FLAG_LENGTH_BITS).
774 "tls-version" (OSSL_CIPHER_PARAM_TLS_VERSION) <integer>
776 Sets the TLS version.
777 "tls-mac-size" (OSSL_CIPHER_PARAM_TLS_MAC_SIZE) <unsigned integer>
779 Set the TLS MAC size.
780 "tlsaad" (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD) <octet string>
782 Sets TLSv1.2 AAD information for the associated cipher context ctx.
783 TLSv1.2 AAD information is always 13 bytes in length and is as
784 defined for the "additional_data" field described in section
785 6.2.3.3 of RFC5246.
786 "tlsivfixed" (OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED) <octet string>
788 Sets the fixed portion of an IV for an AEAD cipher used in a TLS
789 record encryption/ decryption for the associated cipher context.
790 TLS record encryption/decryption always occurs "in place" so that
791 the input and output buffers are always the same memory location.
792 AEAD IVs in TLSv1.2 consist of an implicit "fixed" part and an
793 explicit part that varies with every record. Setting a TLS fixed
794 IV changes a cipher to encrypt/decrypt TLS records. TLS records
795 are encrypted/decrypted using a single OSSL_FUNC_cipher_cipher call
796 per record. For a record decryption the first bytes of the input
797 buffer will be the explicit part of the IV and the final bytes of
798 the input buffer will be the AEAD tag. The length of the explicit
799 part of the IV and the tag length will depend on the cipher in use
800 and will be defined in the RFC for the relevant ciphersuite. In
801 order to allow for "in place" decryption the plaintext output
802 should be written to the same location in the output buffer that
803 the ciphertext payload was read from, i.e. immediately after the
804 explicit IV.
805 When encrypting a record the first bytes of the input buffer should
807 be empty to allow space for the explicit IV, as will the final
808 bytes where the tag will be written. The length of the input
809 buffer will include the length of the explicit IV, the payload, and
810 the tag bytes. The cipher implementation should generate the
811 explicit IV and write it to the beginning of the output buffer, do
812 "in place" encryption of the payload and write that to the output
813 buffer, and finally add the tag onto the end of the output buffer.
814 Whether encrypting or decrypting the value written to *outl in the
816 OSSL_FUNC_cipher_cipher call should be the length of the payload
817 excluding the explicit IV length and the tag length.
818 "tlsivinv" (OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV) <octet string>
820 Sets the invocation field used for decryption. Can only be called
821 after "tlsivfixed" is set. This is only used for GCM mode.
822 "tls1multi_enc" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC) <octet string>
824 Triggers a multiblock TLS1 encrypt operation for a TLS1 aware
825 cipher that supports sending 4 or 8 records in one go. The cipher
826 performs both the MAC and encrypt stages and constructs the record
827 headers itself. "tls1multi_enc" supplies the output buffer for the
828 encrypt operation, "tls1multi_encin" & "tls1multi_interleave" must
829 also be set in order to supply values to the encrypt operation.
830 "tls1multi_encin" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN) <octet
832 string>
833 Supplies the data to encrypt for a TLS1 multiblock cipher
834 operation.
835 "tls1multi_maxsndfrag"
837 (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT) <unsigned
838 integer>
839 Sets the maximum send fragment size for a TLS1 multiblock cipher
840 operation. It must be set before using "tls1multi_maxbufsz". The
841 length of the "tls1multi_maxsndfrag" parameter should not exceed
842 that of a size_t.
843 "tls1multi_aad" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD) <octet string>
845 Sets the authenticated additional data used by a TLS1 multiblock
846 cipher operation. The supplied data consists of 13 bytes of record
847 data containing: Bytes 0-7: The sequence number of the first record
848 Byte 8: The record type Byte 9-10: The protocol version Byte 11-12:
849 Input length (Always 0)
850 "tls1multi_interleave" must also be set for this operation.
852
854 The Mappings from EVP_CIPHER_CTX_ctrl() identifiers to PARAMETERS are
855 listed in the following section. See the "PARAMETERS" section for more
856 details.
857 EVP_CIPHER_CTX_ctrl() can be used to send the following standard
859 controls:
860 EVP_CTRL_AEAD_SET_IVLEN and EVP_CTRL_GET_IVLEN
862 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_set_params()
863 and EVP_CIPHER_CTX_get_params() get called with an OSSL_PARAM(3)
864 item with the key "ivlen" (OSSL_CIPHER_PARAM_IVLEN).
865 EVP_CTRL_AEAD_SET_IV_FIXED
867 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_set_params()
868 gets called with an OSSL_PARAM(3) item with the key "tlsivfixed"
869 (OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED).
870 EVP_CTRL_AEAD_SET_MAC_KEY
872 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_set_params()
873 gets called with an OSSL_PARAM(3) item with the key "mackey"
874 (OSSL_CIPHER_PARAM_AEAD_MAC_KEY).
875 EVP_CTRL_AEAD_SET_TAG and EVP_CTRL_AEAD_GET_TAG
877 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_set_params()
878 and EVP_CIPHER_CTX_get_params() get called with an OSSL_PARAM(3)
879 item with the key "tag" (OSSL_CIPHER_PARAM_AEAD_TAG).
880 EVP_CTRL_CCM_SET_L
882 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_set_params()
883 gets called with an OSSL_PARAM(3) item with the key "ivlen"
884 (OSSL_CIPHER_PARAM_IVLEN) with a value of (15 - L)
885 EVP_CTRL_COPY
887 There is no OSSL_PARAM mapping for this. Use EVP_CIPHER_CTX_copy()
888 instead.
889 EVP_CTRL_GCM_SET_IV_INV
891 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_set_params()
892 gets called with an OSSL_PARAM(3) item with the key "tlsivinv"
893 (OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV).
894 EVP_CTRL_RAND_KEY
896 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_set_params()
897 gets called with an OSSL_PARAM(3) item with the key "randkey"
898 (OSSL_CIPHER_PARAM_RANDOM_KEY).
899 EVP_CTRL_SET_KEY_LENGTH
901 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_set_params()
902 gets called with an OSSL_PARAM(3) item with the key "keylen"
903 (OSSL_CIPHER_PARAM_KEYLEN).
904 EVP_CTRL_SET_RC2_KEY_BITS and EVP_CTRL_GET_RC2_KEY_BITS
906 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_set_params()
907 and EVP_CIPHER_CTX_get_params() get called with an OSSL_PARAM(3)
908 item with the key "keybits" (OSSL_CIPHER_PARAM_RC2_KEYBITS).
909 EVP_CTRL_SET_RC5_ROUNDS and EVP_CTRL_GET_RC5_ROUNDS
911 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_set_params()
912 and EVP_CIPHER_CTX_get_params() get called with an OSSL_PARAM(3)
913 item with the key "rounds" (OSSL_CIPHER_PARAM_ROUNDS).
914 EVP_CTRL_SET_SPEED
916 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_set_params()
917 gets called with an OSSL_PARAM(3) item with the key "speed"
918 (OSSL_CIPHER_PARAM_SPEED).
919 EVP_CTRL_GCM_IV_GEN
921 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_get_params()
922 gets called with an OSSL_PARAM(3) item with the key "tlsivgen"
923 (OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN).
924 EVP_CTRL_AEAD_TLS1_AAD
926 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_set_params()
927 get called with an OSSL_PARAM(3) item with the key "tlsaad"
928 (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD) followed by
929 EVP_CIPHER_CTX_get_params() with a key of "tlsaadpad"
930 (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD).
931 EVP_CTRL_TLS1_1_MULTIBLOCK_MAX_BUFSIZE
933 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_set_params()
934 gets called with an OSSL_PARAM(3) item with the key
935 OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT followed by
936 EVP_CIPHER_CTX_get_params() with a key of "tls1multi_maxbufsz"
937 (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE).
938 EVP_CTRL_TLS1_1_MULTIBLOCK_AAD
940 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_set_params()
941 gets called with OSSL_PARAM(3) items with the keys "tls1multi_aad"
942 (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD) and "tls1multi_interleave"
943 (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE) followed by
944 EVP_CIPHER_CTX_get_params() with keys of "tls1multi_aadpacklen"
945 (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN) and
946 "tls1multi_interleave"
947 (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE).
948 EVP_CTRL_TLS1_1_MULTIBLOCK_ENCRYPT
950 When used with a fetched EVP_CIPHER, EVP_CIPHER_CTX_set_params()
951 gets called with OSSL_PARAM(3) items with the keys "tls1multi_enc"
952 (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC), "tls1multi_encin"
953 (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN) and
954 "tls1multi_interleave"
955 (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE), followed by
956 EVP_CIPHER_CTX_get_params() with a key of "tls1multi_enclen"
957 (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN).
958
960 EVP_CIPHER_CTX_set_flags(), EVP_CIPHER_CTX_clear_flags() and
961 EVP_CIPHER_CTX_test_flags(). can be used to manipulate and test these
962 EVP_CIPHER_CTX flags:
963 EVP_CIPH_NO_PADDING
965 Used by EVP_CIPHER_CTX_set_padding().
966 See also "Gettable and Settable EVP_CIPHER_CTX parameters"
968 "padding"
969 EVP_CIPH_FLAG_LENGTH_BITS
971 See "Settable EVP_CIPHER_CTX parameters" "use-bits".
972 EVP_CIPHER_CTX_FLAG_WRAP_ALLOW
974 Used for Legacy purposes only. This flag needed to be set to
975 indicate the cipher handled wrapping.
976 EVP_CIPHER_flags() uses the following flags that have mappings to
978 "Gettable EVP_CIPHER parameters":
979 EVP_CIPH_FLAG_AEAD_CIPHER
981 See "Gettable EVP_CIPHER parameters" "aead".
982 EVP_CIPH_CUSTOM_IV
984 See "Gettable EVP_CIPHER parameters" "custom-iv".
985 EVP_CIPH_FLAG_CTS
987 See "Gettable EVP_CIPHER parameters" "cts".
988 EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK;
990 See "Gettable EVP_CIPHER parameters" "tls-multi".
991 EVP_CIPH_RAND_KEY
993 See "Gettable EVP_CIPHER parameters" "has-randkey".
994 EVP_CIPHER_flags() uses the following flags for legacy purposes only:
996 EVP_CIPH_VARIABLE_LENGTH
998 EVP_CIPH_FLAG_CUSTOM_CIPHER
999 EVP_CIPH_ALWAYS_CALL_INIT
1000 EVP_CIPH_CTRL_INIT
1001 EVP_CIPH_CUSTOM_KEY_LENGTH
1002 EVP_CIPH_CUSTOM_COPY
1003 EVP_CIPH_FLAG_DEFAULT_ASN1
1004 See EVP_CIPHER_meth_set_flags(3) for further information related to
1005 the above flags.
1006
1008 EVP_CIPHER_fetch() returns a pointer to a EVP_CIPHER for success and
1009 NULL for failure.
1010 EVP_CIPHER_up_ref() returns 1 for success or 0 otherwise.
1012 EVP_CIPHER_CTX_new() returns a pointer to a newly created
1014 EVP_CIPHER_CTX for success and NULL for failure.
1015 EVP_EncryptInit_ex2(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex()
1017 return 1 for success and 0 for failure.
1018 EVP_DecryptInit_ex2() and EVP_DecryptUpdate() return 1 for success and
1020 0 for failure. EVP_DecryptFinal_ex() returns 0 if the decrypt failed
1021 or 1 for success.
1022 EVP_CipherInit_ex2() and EVP_CipherUpdate() return 1 for success and 0
1024 for failure. EVP_CipherFinal_ex() returns 0 for a decryption failure
1025 or 1 for success.
1026 EVP_Cipher() returns the amount of encrypted / decrypted bytes, or -1
1028 on failure if the flag EVP_CIPH_FLAG_CUSTOM_CIPHER is set for the
1029 cipher. EVP_Cipher() returns 1 on success or 0 on failure, if the flag
1030 EVP_CIPH_FLAG_CUSTOM_CIPHER is not set for the cipher.
1031 EVP_CIPHER_CTX_reset() returns 1 for success and 0 for failure.
1033 EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
1035 return an EVP_CIPHER structure or NULL on error.
1036 EVP_CIPHER_get_nid() and EVP_CIPHER_CTX_get_nid() return a NID.
1038 EVP_CIPHER_get_block_size() and EVP_CIPHER_CTX_get_block_size() return
1040 the block size.
1041 EVP_CIPHER_get_key_length() and EVP_CIPHER_CTX_get_key_length() return
1043 the key length.
1044 EVP_CIPHER_CTX_set_padding() always returns 1.
1046 EVP_CIPHER_get_iv_length() and EVP_CIPHER_CTX_get_iv_length() return
1048 the IV length or zero if the cipher does not use an IV.
1049 EVP_CIPHER_CTX_get_tag_length() return the tag length or zero if the
1051 cipher does not use a tag.
1052 EVP_CIPHER_get_type() and EVP_CIPHER_CTX_get_type() return the NID of
1054 the cipher's OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT
1055 IDENTIFIER.
1056 EVP_CIPHER_CTX_cipher() returns an EVP_CIPHER structure.
1058 EVP_CIPHER_CTX_get_num() returns a nonnegative num value or
1060 EVP_CTRL_RET_UNSUPPORTED if the implementation does not support the
1061 call or on any other error.
1062 EVP_CIPHER_CTX_set_num() returns 1 on success and 0 if the
1064 implementation does not support the call or on any other error.
1065 EVP_CIPHER_CTX_is_encrypting() returns 1 if the ctx is set up for
1067 encryption 0 otherwise.
1068 EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return
1070 greater than zero for success and zero or a negative number on failure.
1071 EVP_CIPHER_CTX_rand_key() returns 1 for success and zero or a negative
1073 number for failure.
1074 EVP_CIPHER_names_do_all() returns 1 if the callback was called for all
1076 names. A return value of 0 means that the callback was not called for
1077 any names.
1078
1080 All algorithms have a fixed key length unless otherwise stated.
1081 Refer to "SEE ALSO" for the full list of ciphers available through the
1083 EVP interface.
1084 EVP_enc_null()
1086 Null cipher: does nothing.
1087
1089 The EVP interface for Authenticated Encryption with Associated Data
1090 (AEAD) modes are subtly altered and several additional ctrl operations
1091 are supported depending on the mode specified.
1092 To specify additional authenticated data (AAD), a call to
1094 EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() should
1095 be made with the output parameter out set to NULL.
1096 When decrypting, the return value of EVP_DecryptFinal() or
1098 EVP_CipherFinal() indicates whether the operation was successful. If it
1099 does not indicate success, the authentication operation has failed and
1100 any output data MUST NOT be used as it is corrupted.
1101 GCM and OCB Modes
1103 The following ctrls are supported in GCM and OCB modes.
1104 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)
1106 Sets the IV length. This call can only be made before specifying an
1107 IV. If not called a default IV length is used.
1108 For GCM AES and OCB AES the default is 12 (i.e. 96 bits). For OCB
1110 mode the maximum is 15.
1111 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)
1113 Writes "taglen" bytes of the tag value to the buffer indicated by
1114 "tag". This call can only be made when encrypting data and after
1115 all data has been processed (e.g. after an EVP_EncryptFinal()
1116 call).
1117 For OCB, "taglen" must either be 16 or the value previously set via
1119 EVP_CTRL_AEAD_SET_TAG.
1120 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)
1122 When decrypting, this call sets the expected tag to "taglen" bytes
1123 from "tag". "taglen" must be between 1 and 16 inclusive. The tag
1124 must be set prior to any call to EVP_DecryptFinal() or
1125 EVP_DecryptFinal_ex().
1126 For GCM, this call is only valid when decrypting data.
1128 For OCB, this call is valid when decrypting data to set the
1130 expected tag, and when encrypting to set the desired tag length.
1131 In OCB mode, calling this when encrypting with "tag" set to "NULL"
1133 sets the tag length. The tag length can only be set before
1134 specifying an IV. If this is not called prior to setting the IV
1135 during encryption, then a default tag length is used.
1136 For OCB AES, the default tag length is 16 (i.e. 128 bits). It is
1138 also the maximum tag length for OCB.
1139 CCM Mode
1141 The EVP interface for CCM mode is similar to that of the GCM mode but
1142 with a few additional requirements and different ctrl values.
1143 For CCM mode, the total plaintext or ciphertext length MUST be passed
1145 to EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with
1146 the output and input parameters (in and out) set to NULL and the length
1147 passed in the inl parameter.
1148 The following ctrls are supported in CCM mode.
1150 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)
1152 This call is made to set the expected CCM tag value when decrypting
1153 or the length of the tag (with the "tag" parameter set to NULL)
1154 when encrypting. The tag length is often referred to as M. If not
1155 set a default value is used (12 for AES). When decrypting, the tag
1156 needs to be set before passing in data to be decrypted, but as in
1157 GCM and OCB mode, it can be set after passing additional
1158 authenticated data (see "AEAD INTERFACE").
1159 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL)
1161 Sets the CCM L value. If not set a default is used (8 for AES).
1162 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)
1164 Sets the CCM nonce (IV) length. This call can only be made before
1165 specifying a nonce value. The nonce length is given by 15 - L so it
1166 is 7 by default for AES.
1167 SIV Mode
1169 For SIV mode ciphers the behaviour of the EVP interface is subtly
1170 altered and several additional ctrl operations are supported.
1171 To specify any additional authenticated data (AAD) and/or a Nonce, a
1173 call to EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate()
1174 should be made with the output parameter out set to NULL.
1175 RFC5297 states that the Nonce is the last piece of AAD before the
1177 actual encrypt/decrypt takes place. The API does not differentiate the
1178 Nonce from other AAD.
1179 When decrypting the return value of EVP_DecryptFinal() or
1181 EVP_CipherFinal() indicates if the operation was successful. If it does
1182 not indicate success the authentication operation has failed and any
1183 output data MUST NOT be used as it is corrupted.
1184 The API does not store the the SIV (Synthetic Initialization Vector) in
1186 the cipher text. Instead, it is stored as the tag within the
1187 EVP_CIPHER_CTX. The SIV must be retrieved from the context after
1188 encryption, and set into the context before decryption.
1189 This differs from RFC5297 in that the cipher output from encryption,
1191 and the cipher input to decryption, does not contain the SIV. This also
1192 means that the plain text and cipher text lengths are identical.
1193 The following ctrls are supported in SIV mode, and are used to get and
1195 set the Synthetic Initialization Vector:
1196 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);
1198 Writes taglen bytes of the tag value (the Synthetic Initialization
1199 Vector) to the buffer indicated by tag. This call can only be made
1200 when encrypting data and after all data has been processed (e.g.
1201 after an EVP_EncryptFinal() call). For SIV mode the taglen must be
1202 16.
1203 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);
1205 Sets the expected tag (the Synthetic Initialization Vector) to
1206 taglen bytes from tag. This call is only legal when decrypting data
1207 and must be made before any data is processed (e.g. before any
1208 EVP_DecryptUpdate() calls). For SIV mode the taglen must be 16.
1209 SIV mode makes two passes over the input data, thus, only one call to
1211 EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() should
1212 be made with out set to a non-NULL value. A call to EVP_DecryptFinal()
1213 or EVP_CipherFinal() is not required, but will indicate if the update
1214 operation succeeded.
1215 ChaCha20-Poly1305
1217 The following ctrls are supported for the ChaCha20-Poly1305 AEAD
1218 algorithm.
1219 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)
1221 Sets the nonce length. This call is now redundant since the only
1222 valid value is the default length of 12 (i.e. 96 bits). Prior to
1223 OpenSSL 3.0 a nonce of less than 12 bytes could be used to
1224 automatically pad the iv with leading 0 bytes to make it 12 bytes
1225 in length.
1226 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)
1228 Writes "taglen" bytes of the tag value to the buffer indicated by
1229 "tag". This call can only be made when encrypting data and after
1230 all data has been processed (e.g. after an EVP_EncryptFinal()
1231 call).
1232 "taglen" specified here must be 16 (POLY1305_BLOCK_SIZE, i.e.
1234 128-bits) or less.
1235 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)
1237 Sets the expected tag to "taglen" bytes from "tag". The tag length
1238 can only be set before specifying an IV. "taglen" must be between
1239 1 and 16 (POLY1305_BLOCK_SIZE) inclusive. This call is only valid
1240 when decrypting data.
1241
1243 Where possible the EVP interface to symmetric ciphers should be used in
1244 preference to the low-level interfaces. This is because the code then
1245 becomes transparent to the cipher used and much more flexible.
1246 Additionally, the EVP interface will ensure the use of platform
1247 specific cryptographic acceleration such as AES-NI (the low-level
1248 interfaces do not provide the guarantee).
1249 PKCS padding works by adding n padding bytes of value n to make the
1251 total length of the encrypted data a multiple of the block size.
1252 Padding is always added so if the data is already a multiple of the
1253 block size n will equal the block size. For example if the block size
1254 is 8 and 11 bytes are to be encrypted then 5 padding bytes of value 5
1255 will be added.
1256 When decrypting the final block is checked to see if it has the correct
1258 form.
1259 Although the decryption operation can produce an error if padding is
1261 enabled, it is not a strong test that the input data or key is correct.
1262 A random block has better than 1 in 256 chance of being of the correct
1263 format and problems with the input data earlier on will not produce a
1264 final decrypt error.
1265 If padding is disabled then the decryption operation will always
1267 succeed if the total amount of data decrypted is a multiple of the
1268 block size.
1269 The functions EVP_EncryptInit(), EVP_EncryptInit_ex(),
1271 EVP_EncryptFinal(), EVP_DecryptInit(), EVP_DecryptInit_ex(),
1272 EVP_CipherInit(), EVP_CipherInit_ex() and EVP_CipherFinal() are
1273 obsolete but are retained for compatibility with existing code. New
1274 code should use EVP_EncryptInit_ex2(), EVP_EncryptFinal_ex(),
1275 EVP_DecryptInit_ex2(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex2() and
1276 EVP_CipherFinal_ex() because they can reuse an existing context without
1277 allocating and freeing it up on each call.
1278 There are some differences between functions EVP_CipherInit() and
1280 EVP_CipherInit_ex(), significant in some circumstances.
1281 EVP_CipherInit() fills the passed context object with zeros. As a
1282 consequence, EVP_CipherInit() does not allow step-by-step
1283 initialization of the ctx when the key and iv are passed in separate
1284 calls. It also means that the flags set for the CTX are removed, and it
1285 is especially important for the EVP_CIPHER_CTX_FLAG_WRAP_ALLOW flag
1286 treated specially in EVP_CipherInit_ex().
1287 Ignoring failure returns of the EVP_CIPHER_CTX initialization functions
1289 can lead to subsequent undefined behavior when calling the functions
1290 that update or finalize the context. The only valid calls on the
1291 EVP_CIPHER_CTX when initialization fails are calls that attempt another
1292 initialization of the context or release the context.
1293 EVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as
1295 macros.
1296
1298 EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal
1299 ciphers with default key lengths. If custom ciphers exceed these values
1300 the results are unpredictable. This is because it has become standard
1301 practice to define a generic key as a fixed unsigned char array
1302 containing EVP_MAX_KEY_LENGTH bytes.
1303 The ASN1 code is incomplete (and sometimes inaccurate) it has only been
1305 tested for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC
1306 mode.
1307
1309 Encrypt a string using IDEA:
1310 int do_crypt(char *outfile)
1312 {
1313 unsigned char outbuf[1024];
1314 int outlen, tmplen;
1315 /*
1316 * Bogus key and IV: we'd normally set these from
1317 * another source.
1318 */
1319 unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
1320 unsigned char iv[] = {1,2,3,4,5,6,7,8};
1321 char intext[] = "Some Crypto Text";
1322 EVP_CIPHER_CTX *ctx;
1323 FILE *out;
1324 ctx = EVP_CIPHER_CTX_new();
1326 if (!EVP_EncryptInit_ex2(ctx, EVP_idea_cbc(), key, iv, NULL)) {
1327 /* Error */
1328 EVP_CIPHER_CTX_free(ctx);
1329 return 0;
1330 }
1331 if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) {
1333 /* Error */
1334 EVP_CIPHER_CTX_free(ctx);
1335 return 0;
1336 }
1337 /*
1338 * Buffer passed to EVP_EncryptFinal() must be after data just
1339 * encrypted to avoid overwriting it.
1340 */
1341 if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) {
1342 /* Error */
1343 EVP_CIPHER_CTX_free(ctx);
1344 return 0;
1345 }
1346 outlen += tmplen;
1347 EVP_CIPHER_CTX_free(ctx);
1348 /*
1349 * Need binary mode for fopen because encrypted data is
1350 * binary data. Also cannot use strlen() on it because
1351 * it won't be NUL terminated and may contain embedded
1352 * NULs.
1353 */
1354 out = fopen(outfile, "wb");
1355 if (out == NULL) {
1356 /* Error */
1357 return 0;
1358 }
1359 fwrite(outbuf, 1, outlen, out);
1360 fclose(out);
1361 return 1;
1362 }
1363 The ciphertext from the above example can be decrypted using the
1365 openssl utility with the command line (shown on two lines for clarity):
1366 openssl idea -d \
1368 -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 <filename
1369 General encryption and decryption function example using FILE I/O and
1371 AES128 with a 128-bit key:
1372 int do_crypt(FILE *in, FILE *out, int do_encrypt)
1374 {
1375 /* Allow enough space in output buffer for additional block */
1376 unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
1377 int inlen, outlen;
1378 EVP_CIPHER_CTX *ctx;
1379 /*
1380 * Bogus key and IV: we'd normally set these from
1381 * another source.
1382 */
1383 unsigned char key[] = "0123456789abcdeF";
1384 unsigned char iv[] = "1234567887654321";
1385 /* Don't set key or IV right away; we want to check lengths */
1387 ctx = EVP_CIPHER_CTX_new();
1388 if (!EVP_CipherInit_ex2(ctx, EVP_aes_128_cbc(), NULL, NULL,
1389 do_encrypt, NULL)) {
1390 /* Error */
1391 EVP_CIPHER_CTX_free(ctx);
1392 return 0;
1393 }
1394 OPENSSL_assert(EVP_CIPHER_CTX_get_key_length(ctx) == 16);
1395 OPENSSL_assert(EVP_CIPHER_CTX_get_iv_length(ctx) == 16);
1396 /* Now we can set key and IV */
1398 if (!EVP_CipherInit_ex2(ctx, NULL, key, iv, do_encrypt, NULL)) {
1399 /* Error */
1400 EVP_CIPHER_CTX_free(ctx);
1401 return 0;
1402 }
1403 for (;;) {
1405 inlen = fread(inbuf, 1, 1024, in);
1406 if (inlen <= 0)
1407 break;
1408 if (!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, inlen)) {
1409 /* Error */
1410 EVP_CIPHER_CTX_free(ctx);
1411 return 0;
1412 }
1413 fwrite(outbuf, 1, outlen, out);
1414 }
1415 if (!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) {
1416 /* Error */
1417 EVP_CIPHER_CTX_free(ctx);
1418 return 0;
1419 }
1420 fwrite(outbuf, 1, outlen, out);
1421 EVP_CIPHER_CTX_free(ctx);
1423 return 1;
1424 }
1425 Encryption using AES-CBC with a 256-bit key with "CS1" ciphertext
1427 stealing.
1428 int encrypt(const unsigned char *key, const unsigned char *iv,
1430 const unsigned char *msg, size_t msg_len, unsigned char *out)
1431 {
1432 /*
1433 * This assumes that key size is 32 bytes and the iv is 16 bytes.
1434 * For ciphertext stealing mode the length of the ciphertext "out" will be
1435 * the same size as the plaintext size "msg_len".
1436 * The "msg_len" can be any size >= 16.
1437 */
1438 int ret = 0, encrypt = 1, outlen, len;
1439 EVP_CIPHER_CTX *ctx = NULL;
1440 EVP_CIPHER *cipher = NULL;
1441 OSSL_PARAM params[2];
1442 ctx = EVP_CIPHER_CTX_new();
1444 cipher = EVP_CIPHER_fetch(NULL, "AES-256-CBC-CTS", NULL);
1445 if (ctx == NULL || cipher == NULL)
1446 goto err;
1447 /*
1449 * The default is "CS1" so this is not really needed,
1450 * but would be needed to set either "CS2" or "CS3".
1451 */
1452 params[0] = OSSL_PARAM_construct_utf8_string(OSSL_CIPHER_PARAM_CTS_MODE,
1453 "CS1", 0);
1454 params[1] = OSSL_PARAM_construct_end();
1455 if (!EVP_CipherInit_ex2(ctx, cipher, key, iv, encrypt, params))
1457 goto err;
1458 /* NOTE: CTS mode does not support multiple calls to EVP_CipherUpdate() */
1460 if (!EVP_CipherUpdate(ctx, out, &outlen, msg, msg_len))
1461 goto err;
1462 if (!EVP_CipherFinal_ex(ctx, out + outlen, &len))
1463 goto err;
1464 ret = 1;
1465 err:
1466 EVP_CIPHER_free(cipher);
1467 EVP_CIPHER_CTX_free(ctx);
1468 return ret;
1469 }
1470
1472 evp(7), property(7), "ALGORITHM FETCHING" in crypto(7),
1473 provider-cipher(7), life_cycle-cipher(7)
1474 Supported ciphers are listed in:
1476 EVP_aes_128_gcm(3), EVP_aria_128_gcm(3), EVP_bf_cbc(3),
1478 EVP_camellia_128_ecb(3), EVP_cast5_cbc(3), EVP_chacha20(3),
1479 EVP_des_cbc(3), EVP_desx_cbc(3), EVP_idea_cbc(3), EVP_rc2_cbc(3),
1480 EVP_rc4(3), EVP_rc5_32_12_16_cbc(3), EVP_seed_cbc(3), EVP_sm4_cbc(3),
1481
1483 Support for OCB mode was added in OpenSSL 1.1.0.
1484 EVP_CIPHER_CTX was made opaque in OpenSSL 1.1.0. As a result,
1486 EVP_CIPHER_CTX_reset() appeared and EVP_CIPHER_CTX_cleanup()
1487 disappeared. EVP_CIPHER_CTX_init() remains as an alias for
1488 EVP_CIPHER_CTX_reset().
1489 The EVP_CIPHER_CTX_cipher() function was deprecated in OpenSSL 3.0; use
1491 EVP_CIPHER_CTX_get0_cipher() instead.
1492 The EVP_EncryptInit_ex2(), EVP_DecryptInit_ex2(), EVP_CipherInit_ex2(),
1494 EVP_CIPHER_fetch(), EVP_CIPHER_free(), EVP_CIPHER_up_ref(),
1495 EVP_CIPHER_CTX_get0_cipher(), EVP_CIPHER_CTX_get1_cipher(),
1496 EVP_CIPHER_get_params(), EVP_CIPHER_CTX_set_params(),
1497 EVP_CIPHER_CTX_get_params(), EVP_CIPHER_gettable_params(),
1498 EVP_CIPHER_settable_ctx_params(), EVP_CIPHER_gettable_ctx_params(),
1499 EVP_CIPHER_CTX_settable_params() and EVP_CIPHER_CTX_gettable_params()
1500 functions were added in 3.0.
1501 The EVP_CIPHER_nid(), EVP_CIPHER_name(), EVP_CIPHER_block_size(),
1503 EVP_CIPHER_key_length(), EVP_CIPHER_iv_length(), EVP_CIPHER_flags(),
1504 EVP_CIPHER_mode(), EVP_CIPHER_type(), EVP_CIPHER_CTX_nid(),
1505 EVP_CIPHER_CTX_block_size(), EVP_CIPHER_CTX_key_length(),
1506 EVP_CIPHER_CTX_iv_length(), EVP_CIPHER_CTX_tag_length(),
1507 EVP_CIPHER_CTX_num(), EVP_CIPHER_CTX_type(), and EVP_CIPHER_CTX_mode()
1508 functions were renamed to include "get" or "get0" in their names in
1509 OpenSSL 3.0, respectively. The old names are kept as non-deprecated
1510 alias macros.
1511 The EVP_CIPHER_CTX_encrypting() function was renamed to
1513 EVP_CIPHER_CTX_is_encrypting() in OpenSSL 3.0. The old name is kept as
1514 non-deprecated alias macro.
1515 The EVP_CIPHER_CTX_flags() macro was deprecated in OpenSSL 1.1.0.
1517
1519 Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
1520 Licensed under the Apache License 2.0 (the "License"). You may not use
1522 this file except in compliance with the License. You can obtain a copy
1523 in the file LICENSE in the source distribution or at
1524 <https://www.openssl.org/source/license.html>.
15253.0.9 2023-07-27 EVP_ENCRYPTINIT(3ossl)