1EVP_EncryptInit(3) OpenSSL EVP_EncryptInit(3)
2
6 EVP_CIPHER_CTX_init, EVP_EncryptInit_ex, EVP_EncryptUpdate,
7 EVP_EncryptFinal_ex, EVP_DecryptInit_ex, EVP_DecryptUpdate,
8 EVP_DecryptFinal_ex, EVP_CipherInit_ex, EVP_CipherUpdate,
9 EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl,
10 EVP_CIPHER_CTX_cleanup, EVP_EncryptInit, EVP_EncryptFinal,
11 EVP_DecryptInit, EVP_DecryptFinal, EVP_CipherInit, EVP_CipherFinal,
12 EVP_get_cipherbyname, EVP_get_cipherbynid, EVP_get_cipherbyobj,
13 EVP_CIPHER_nid, EVP_CIPHER_block_size, EVP_CIPHER_key_length,
14 EVP_CIPHER_iv_length, EVP_CIPHER_flags, EVP_CIPHER_mode,
15 EVP_CIPHER_type, EVP_CIPHER_CTX_cipher, EVP_CIPHER_CTX_nid,
16 EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length,
17 EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data,
18 EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags,
19 EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1,
20 EVP_CIPHER_asn1_to_param, EVP_CIPHER_CTX_set_padding, EVP_enc_null,
21 EVP_des_cbc, EVP_des_ecb, EVP_des_cfb, EVP_des_ofb, EVP_des_ede_cbc,
22 EVP_des_ede, EVP_des_ede_ofb, EVP_des_ede_cfb, EVP_des_ede3_cbc,
23 EVP_des_ede3, EVP_des_ede3_ofb, EVP_des_ede3_cfb, EVP_desx_cbc,
24 EVP_rc4, EVP_rc4_40, EVP_rc4_hmac_md5, EVP_idea_cbc, EVP_idea_ecb,
25 EVP_idea_cfb, EVP_idea_ofb, EVP_rc2_cbc, EVP_rc2_ecb, EVP_rc2_cfb,
26 EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc, EVP_bf_cbc, EVP_bf_ecb,
27 EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc, EVP_cast5_ecb, EVP_cast5_cfb,
28 EVP_cast5_ofb, EVP_rc5_32_12_16_cbc, EVP_rc5_32_12_16_ecb,
29 EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb, EVP_aes_128_gcm,
30 EVP_aes_192_gcm, EVP_aes_256_gcm, EVP_aes_128_ccm, EVP_aes_192_ccm,
31 EVP_aes_256_ccm, EVP_aes_128_cbc_hmac_sha1, EVP_aes_256_cbc_hmac_sha1,
32 EVP_aes_128_cbc_hmac_sha256, EVP_aes_256_cbc_hmac_sha256 - EVP cipher
33 routines
34
36 #include <openssl/evp.h>
37 void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a);
39 int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
41 ENGINE *impl, const unsigned char *key, const unsigned char *iv);
42 int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
43 int *outl, const unsigned char *in, int inl);
44 int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out,
45 int *outl);
46 int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
48 ENGINE *impl, const unsigned char *key, const unsigned char *iv);
49 int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
50 int *outl, const unsigned char *in, int inl);
51 int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
52 int *outl);
53 int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
55 ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc);
56 int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
57 int *outl, const unsigned char *in, int inl);
58 int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
59 int *outl);
60 int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
62 const unsigned char *key, const unsigned char *iv);
63 int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
64 int *outl);
65 int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
67 const unsigned char *key, const unsigned char *iv);
68 int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
69 int *outl);
70 int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
72 const unsigned char *key, const unsigned char *iv, int enc);
73 int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
74 int *outl);
75 int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);
77 int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);
78 int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);
79 int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a);
80 const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
82 #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a))
83 #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a))
84 #define EVP_CIPHER_nid(e) ((e)->nid)
86 #define EVP_CIPHER_block_size(e) ((e)->block_size)
87 #define EVP_CIPHER_key_length(e) ((e)->key_len)
88 #define EVP_CIPHER_iv_length(e) ((e)->iv_len)
89 #define EVP_CIPHER_flags(e) ((e)->flags)
90 #define EVP_CIPHER_mode(e) ((e)->flags) & EVP_CIPH_MODE)
91 int EVP_CIPHER_type(const EVP_CIPHER *ctx);
92 #define EVP_CIPHER_CTX_cipher(e) ((e)->cipher)
94 #define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid)
95 #define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size)
96 #define EVP_CIPHER_CTX_key_length(e) ((e)->key_len)
97 #define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len)
98 #define EVP_CIPHER_CTX_get_app_data(e) ((e)->app_data)
99 #define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d))
100 #define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c))
101 #define EVP_CIPHER_CTX_flags(e) ((e)->cipher->flags)
102 #define EVP_CIPHER_CTX_mode(e) ((e)->cipher->flags & EVP_CIPH_MODE)
103 int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
105 int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
106 const EVP_CIPHER *EVP_des_ede3(void);
108 const EVP_CIPHER *EVP_des_ede3_ecb(void);
109 const EVP_CIPHER *EVP_des_ede3_cfb64(void);
110 const EVP_CIPHER *EVP_des_ede3_cfb1(void);
111 const EVP_CIPHER *EVP_des_ede3_cfb8(void);
112 const EVP_CIPHER *EVP_des_ede3_ofb(void);
113 const EVP_CIPHER *EVP_des_ede3_cbc(void);
114 const EVP_CIPHER *EVP_aes_128_ecb(void);
115 const EVP_CIPHER *EVP_aes_128_cbc(void);
116 const EVP_CIPHER *EVP_aes_128_cfb1(void);
117 const EVP_CIPHER *EVP_aes_128_cfb8(void);
118 const EVP_CIPHER *EVP_aes_128_cfb128(void);
119 const EVP_CIPHER *EVP_aes_128_ofb(void);
120 const EVP_CIPHER *EVP_aes_192_ecb(void);
121 const EVP_CIPHER *EVP_aes_192_cbc(void);
122 const EVP_CIPHER *EVP_aes_192_cfb1(void);
123 const EVP_CIPHER *EVP_aes_192_cfb8(void);
124 const EVP_CIPHER *EVP_aes_192_cfb128(void);
125 const EVP_CIPHER *EVP_aes_192_ofb(void);
126 const EVP_CIPHER *EVP_aes_256_ecb(void);
127 const EVP_CIPHER *EVP_aes_256_cbc(void);
128 const EVP_CIPHER *EVP_aes_256_cfb1(void);
129 const EVP_CIPHER *EVP_aes_256_cfb8(void);
130 const EVP_CIPHER *EVP_aes_256_cfb128(void);
131 const EVP_CIPHER *EVP_aes_256_ofb(void);
132
134 The EVP cipher routines are a high level interface to certain symmetric
135 ciphers.
136 EVP_CIPHER_CTX_init() initializes cipher contex ctx.
138 EVP_EncryptInit_ex() sets up cipher context ctx for encryption with
140 cipher type from ENGINE impl. ctx must be initialized before calling
141 this function. type is normally supplied by a function such as
142 EVP_aes_256_cbc(). If impl is NULL then the default implementation is
143 used. key is the symmetric key to use and iv is the IV to use (if
144 necessary), the actual number of bytes used for the key and IV depends
145 on the cipher. It is possible to set all parameters to NULL except type
146 in an initial call and supply the remaining parameters in subsequent
147 calls, all of which have type set to NULL. This is done when the
148 default cipher parameters are not appropriate.
149 EVP_EncryptUpdate() encrypts inl bytes from the buffer in and writes
151 the encrypted version to out. This function can be called multiple
152 times to encrypt successive blocks of data. The amount of data written
153 depends on the block alignment of the encrypted data: as a result the
154 amount of data written may be anything from zero bytes to (inl +
155 cipher_block_size - 1) so out should contain sufficient room. The
156 actual number of bytes written is placed in outl.
157 If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts
159 the "final" data, that is any data that remains in a partial block. It
160 uses standard block padding (aka PKCS padding). The encrypted final
161 data is written to out which should have sufficient space for one
162 cipher block. The number of bytes written is placed in outl. After this
163 function is called the encryption operation is finished and no further
164 calls to EVP_EncryptUpdate() should be made.
165 If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any
167 more data and it will return an error if any data remains in a partial
168 block: that is if the total data length is not a multiple of the block
169 size.
170 EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are
172 the corresponding decryption operations. EVP_DecryptFinal() will return
173 an error code if padding is enabled and the final block is not
174 correctly formatted. The parameters and restrictions are identical to
175 the encryption operations except that if padding is enabled the
176 decrypted data buffer out passed to EVP_DecryptUpdate() should have
177 sufficient room for (inl + cipher_block_size) bytes unless the cipher
178 block size is 1 in which case inl bytes is sufficient.
179 EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex() are
181 functions that can be used for decryption or encryption. The operation
182 performed depends on the value of the enc parameter. It should be set
183 to 1 for encryption, 0 for decryption and -1 to leave the value
184 unchanged (the actual value of 'enc' being supplied in a previous
185 call).
186 EVP_CIPHER_CTX_cleanup() clears all information from a cipher context
188 and free up any allocated memory associate with it. It should be called
189 after all operations using a cipher are complete so sensitive
190 information does not remain in memory.
191 EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a
193 similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex and
194 EVP_CipherInit_ex() except the ctx parameter does not need to be
195 initialized and they always use the default cipher implementation.
196 EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() are
198 identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and
199 EVP_CipherFinal_ex(). In previous releases they also cleaned up the
200 ctx, but this is no longer done and EVP_CIPHER_CTX_clean() must be
201 called to free any context resources.
202 EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
204 return an EVP_CIPHER structure when passed a cipher name, a NID or an
205 ASN1_OBJECT structure.
206 EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher
208 when passed an EVP_CIPHER or EVP_CIPHER_CTX structure. The actual NID
209 value is an internal value which may not have a corresponding OBJECT
210 IDENTIFIER.
211 EVP_CIPHER_CTX_set_padding() enables or disables padding. By default
213 encryption operations are padded using standard block padding and the
214 padding is checked and removed when decrypting. If the pad parameter is
215 zero then no padding is performed, the total amount of data encrypted
216 or decrypted must then be a multiple of the block size or an error will
217 occur.
218 EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
220 length of a cipher when passed an EVP_CIPHER or EVP_CIPHER_CTX
221 structure. The constant EVP_MAX_KEY_LENGTH is the maximum key length
222 for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a
223 given cipher, the value of EVP_CIPHER_CTX_key_length() may be different
224 for variable key length ciphers.
225 EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx.
227 If the cipher is a fixed length cipher then attempting to set the key
228 length to any value other than the fixed value is an error.
229 EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
231 length of a cipher when passed an EVP_CIPHER or EVP_CIPHER_CTX. It
232 will return zero if the cipher does not use an IV. The constant
233 EVP_MAX_IV_LENGTH is the maximum IV length for all ciphers.
234 EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the
236 block size of a cipher when passed an EVP_CIPHER or EVP_CIPHER_CTX
237 structure. The constant EVP_MAX_IV_LENGTH is also the maximum block
238 length for all ciphers.
239 EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the
241 passed cipher or context. This "type" is the actual NID of the cipher
242 OBJECT IDENTIFIER as such it ignores the cipher parameters and 40 bit
243 RC2 and 128 bit RC2 have the same NID. If the cipher does not have an
244 object identifier or does not have ASN1 support this function will
245 return NID_undef.
246 EVP_CIPHER_CTX_cipher() returns the EVP_CIPHER structure when passed an
248 EVP_CIPHER_CTX structure.
249 EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher
251 mode: EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE or
252 EVP_CIPH_OFB_MODE. If the cipher is a stream cipher then
253 EVP_CIPH_STREAM_CIPHER is returned.
254 EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter"
256 based on the passed cipher. This will typically include any parameters
257 and an IV. The cipher IV (if any) must be set when this call is made.
258 This call should be made before the cipher is actually "used" (before
259 any EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This
260 function may fail if the cipher does not have any ASN1 support.
261 EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1
263 AlgorithmIdentifier "parameter". The precise effect depends on the
264 cipher In the case of RC2, for example, it will set the IV and
265 effective key length. This function should be called after the base
266 cipher type is set but before the key is set. For example
267 EVP_CipherInit() will be called with the IV and key set to NULL,
268 EVP_CIPHER_asn1_to_param() will be called and finally EVP_CipherInit()
269 again with all parameters except the key set to NULL. It is possible
270 for this function to fail if the cipher does not have any ASN1 support
271 or the parameters cannot be set (for example the RC2 effective key
272 length is not supported.
273 EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be
275 determined and set.
276
278 EVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex()
279 return 1 for success and 0 for failure.
280 EVP_DecryptInit_ex() and EVP_DecryptUpdate() return 1 for success and 0
282 for failure. EVP_DecryptFinal_ex() returns 0 if the decrypt failed or
283 1 for success.
284 EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0
286 for failure. EVP_CipherFinal_ex() returns 0 for a decryption failure
287 or 1 for success.
288 EVP_CIPHER_CTX_cleanup() returns 1 for success and 0 for failure.
290 EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
292 return an EVP_CIPHER structure or NULL on error.
293 EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID.
295 EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the
297 block size.
298 EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
300 length.
301 EVP_CIPHER_CTX_set_padding() always returns 1.
303 EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
305 length or zero if the cipher does not use an IV.
306 EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the
308 cipher's OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT
309 IDENTIFIER.
310 EVP_CIPHER_CTX_cipher() returns an EVP_CIPHER structure.
312 EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for
314 success or zero for failure.
315
317 All algorithms have a fixed key length unless otherwise stated.
318 EVP_enc_null()
320 Null cipher: does nothing.
321 EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void),
323 EVP_des_ofb(void)
324 DES in CBC, ECB, CFB and OFB modes respectively.
325 EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void),
327 EVP_des_ede_cfb(void)
328 Two key triple DES in CBC, ECB, CFB and OFB modes respectively.
329 EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void),
331 EVP_des_ede3_cfb(void)
332 Three key triple DES in CBC, ECB, CFB and OFB modes respectively.
333 EVP_desx_cbc(void)
335 DESX algorithm in CBC mode.
336 EVP_aes_128_cbc(void), EVP_aes_128_ecb(), EVP_aes_128_ofb(void),
338 EVP_aes_128_cfb1(void), EVP_aes_128_cfb8(void),
339 EVP_aes_128_cfb128(void)
340 AES with 128 bit key length in CBC, ECB, OFB and CFB modes
341 respectively.
342 EVP_aes_192_cbc(void), EVP_aes_192_ecb(), EVP_aes_192_ofb(void),
344 EVP_aes_192_cfb1(void), EVP_aes_192_cfb8(void),
345 EVP_aes_192_cfb128(void)
346 AES with 192 bit key length in CBC, ECB, OFB and CFB modes
347 respectively.
348 EVP_aes_256_cbc(void), EVP_aes_256_ecb(), EVP_aes_256_ofb(void),
350 EVP_aes_256_cfb1(void), EVP_aes_256_cfb8(void),
351 EVP_aes_256_cfb128(void)
352 AES with 256 bit key length in CBC, ECB, OFB and CFB modes
353 respectively.
354 EVP_rc4(void)
356 RC4 stream cipher. This is a variable key length cipher with
357 default key length 128 bits.
358 EVP_rc4_40(void)
360 RC4 stream cipher with 40 bit key length. This is obsolete and new
361 code should use EVP_rc4() and the EVP_CIPHER_CTX_set_key_length()
362 function.
363 EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void),
365 EVP_idea_ofb(void), EVP_idea_cbc(void)
366 IDEA encryption algorithm in CBC, ECB, CFB and OFB modes
367 respectively.
368 EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void),
370 EVP_rc2_ofb(void)
371 RC2 encryption algorithm in CBC, ECB, CFB and OFB modes
372 respectively. This is a variable key length cipher with an
373 additional parameter called "effective key bits" or "effective key
374 length". By default both are set to 128 bits.
375 EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void)
377 RC2 algorithm in CBC mode with a default key length and effective
378 key length of 40 and 64 bits. These are obsolete and new code
379 should use EVP_rc2_cbc(), EVP_CIPHER_CTX_set_key_length() and
380 EVP_CIPHER_CTX_ctrl() to set the key length and effective key
381 length.
382 EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void);
384 Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes
385 respectively. This is a variable key length cipher.
386 EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void),
388 EVP_cast5_ofb(void)
389 CAST encryption algorithm in CBC, ECB, CFB and OFB modes
390 respectively. This is a variable key length cipher.
391 EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void),
393 EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void)
394 RC5 encryption algorithm in CBC, ECB, CFB and OFB modes
395 respectively. This is a variable key length cipher with an
396 additional "number of rounds" parameter. By default the key length
397 is set to 128 bits and 12 rounds.
398 EVP_aes_128_gcm(void), EVP_aes_192_gcm(void), EVP_aes_256_gcm(void)
400 AES Galois Counter Mode (GCM) for 128, 192 and 256 bit keys
401 respectively. These ciphers require additional control operations
402 to function correctly: see "GCM mode" section below for details.
403 EVP_aes_128_ccm(void), EVP_aes_192_ccm(void), EVP_aes_256_ccm(void)
405 AES Counter with CBC-MAC Mode (CCM) for 128, 192 and 256 bit keys
406 respectively. These ciphers require additional control operations
407 to function correctly: see CCM mode section below for details.
408
410 For GCM mode ciphers the behaviour of the EVP interface is subtly
411 altered and several GCM specific ctrl operations are supported.
412 To specify any additional authenticated data (AAD) a call to
414 EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() should
415 be made with the output parameter out set to NULL.
416 When decrypting the return value of EVP_DecryptFinal() or
418 EVP_CipherFinal() indicates if the operation was successful. If it does
419 not indicate success the authentication operation has failed and any
420 output data MUST NOT be used as it is corrupted.
421 The following ctrls are supported in GCM mode:
423 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, ivlen, NULL);
425 Sets the GCM IV length: this call can only be made before specifying an
427 IV. If not called a default IV length is used (96 bits for AES).
428 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, taglen, tag);
430 Writes taglen bytes of the tag value to the buffer indicated by tag.
432 This call can only be made when encrypting data and after all data has
433 been processed (e.g. after an EVP_EncryptFinal() call).
434 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, taglen, tag);
436 Sets the expected tag to taglen bytes from tag. This call is only legal
438 when decrypting data.
439
441 The behaviour of CCM mode ciphers is similar to CCM mode but with a few
442 additional requirements and different ctrl values.
443 Like GCM mode any additional authenticated data (AAD) is passed by
445 calling EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate()
446 with the output parameter out set to NULL. Additionally the total
447 plaintext or ciphertext length MUST be passed to EVP_CipherUpdate(),
448 EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output and input
449 parameters (in and out) set to NULL and the length passed in the inl
450 parameter.
451 The following ctrls are supported in CCM mode:
453 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, taglen, tag);
455 This call is made to set the expected CCM tag value when decrypting or
457 the length of the tag (with the tag parameter set to NULL) when
458 encrypting. The tag length is often referred to as M. If not set a
459 default value is used (12 for AES).
460 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL);
462 Sets the CCM L value. If not set a default is used (8 for AES).
464 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, ivlen, NULL);
466 Sets the CCM nonce (IV) length: this call can only be made before
468 specifying an nonce value. The nonce length is given by 15 - L so it is
469 7 by default for AES.
470
472 Where possible the EVP interface to symmetric ciphers should be used in
473 preference to the low level interfaces. This is because the code then
474 becomes transparent to the cipher used and much more flexible.
475 Additionally, the EVP interface will ensure the use of platform
476 specific cryptographic acceleration such as AES-NI (the low level
477 interfaces do not provide the guarantee).
478 PKCS padding works by adding n padding bytes of value n to make the
480 total length of the encrypted data a multiple of the block size.
481 Padding is always added so if the data is already a multiple of the
482 block size n will equal the block size. For example if the block size
483 is 8 and 11 bytes are to be encrypted then 5 padding bytes of value 5
484 will be added.
485 When decrypting the final block is checked to see if it has the correct
487 form.
488 Although the decryption operation can produce an error if padding is
490 enabled, it is not a strong test that the input data or key is correct.
491 A random block has better than 1 in 256 chance of being of the correct
492 format and problems with the input data earlier on will not produce a
493 final decrypt error.
494 If padding is disabled then the decryption operation will always
496 succeed if the total amount of data decrypted is a multiple of the
497 block size.
498 The functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(),
500 EVP_CipherInit() and EVP_CipherFinal() are obsolete but are retained
501 for compatibility with existing code. New code should use
502 EVP_EncryptInit_ex(), EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(),
503 EVP_DecryptFinal_ex(), EVP_CipherInit_ex() and EVP_CipherFinal_ex()
504 because they can reuse an existing context without allocating and
505 freeing it up on each call.
506
508 For RC5 the number of rounds can currently only be set to 8, 12 or 16.
509 This is a limitation of the current RC5 code rather than the EVP
510 interface.
511 EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal
513 ciphers with default key lengths. If custom ciphers exceed these values
514 the results are unpredictable. This is because it has become standard
515 practice to define a generic key as a fixed unsigned char array
516 containing EVP_MAX_KEY_LENGTH bytes.
517 The ASN1 code is incomplete (and sometimes inaccurate) it has only been
519 tested for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC
520 mode.
521
523 Encrypt a string using IDEA:
524 int do_crypt(char *outfile)
526 {
527 unsigned char outbuf[1024];
528 int outlen, tmplen;
529 /* Bogus key and IV: we'd normally set these from
530 * another source.
531 */
532 unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
533 unsigned char iv[] = {1,2,3,4,5,6,7,8};
534 char intext[] = "Some Crypto Text";
535 EVP_CIPHER_CTX ctx;
536 FILE *out;
537 EVP_CIPHER_CTX_init(&ctx);
539 EVP_EncryptInit_ex(&ctx, EVP_idea_cbc(), NULL, key, iv);
540 if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext)))
542 {
543 /* Error */
544 return 0;
545 }
546 /* Buffer passed to EVP_EncryptFinal() must be after data just
547 * encrypted to avoid overwriting it.
548 */
549 if(!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen))
550 {
551 /* Error */
552 return 0;
553 }
554 outlen += tmplen;
555 EVP_CIPHER_CTX_cleanup(&ctx);
556 /* Need binary mode for fopen because encrypted data is
557 * binary data. Also cannot use strlen() on it because
558 * it wont be null terminated and may contain embedded
559 * nulls.
560 */
561 out = fopen(outfile, "wb");
562 fwrite(outbuf, 1, outlen, out);
563 fclose(out);
564 return 1;
565 }
566 The ciphertext from the above example can be decrypted using the
568 openssl utility with the command line (shown on two lines for clarity):
569 openssl idea -d <filename
571 -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708
572 General encryption and decryption function example using FILE I/O and
574 AES128 with a 128-bit key:
575 int do_crypt(FILE *in, FILE *out, int do_encrypt)
577 {
578 /* Allow enough space in output buffer for additional block */
579 unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
580 int inlen, outlen;
581 EVP_CIPHER_CTX ctx;
582 /* Bogus key and IV: we'd normally set these from
583 * another source.
584 */
585 unsigned char key[] = "0123456789abcdeF";
586 unsigned char iv[] = "1234567887654321";
587 /* Don't set key or IV right away; we want to check lengths */
589 EVP_CIPHER_CTX_init(&ctx);
590 EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL,
591 do_encrypt);
592 OPENSSL_assert(EVP_CIPHER_CTX_key_length(&ctx) == 16);
593 OPENSSL_assert(EVP_CIPHER_CTX_iv_length(&ctx) == 16);
594 /* Now we can set key and IV */
596 EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);
597 for(;;)
599 {
600 inlen = fread(inbuf, 1, 1024, in);
601 if(inlen <= 0) break;
602 if(!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf, inlen))
603 {
604 /* Error */
605 EVP_CIPHER_CTX_cleanup(&ctx);
606 return 0;
607 }
608 fwrite(outbuf, 1, outlen, out);
609 }
610 if(!EVP_CipherFinal_ex(&ctx, outbuf, &outlen))
611 {
612 /* Error */
613 EVP_CIPHER_CTX_cleanup(&ctx);
614 return 0;
615 }
616 fwrite(outbuf, 1, outlen, out);
617 EVP_CIPHER_CTX_cleanup(&ctx);
619 return 1;
620 }
621
623 evp(3)
624
626 EVP_CIPHER_CTX_init(), EVP_EncryptInit_ex(), EVP_EncryptFinal_ex(),
627 EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(),
628 EVP_CipherFinal_ex() and EVP_CIPHER_CTX_set_padding() appeared in
629 OpenSSL 0.9.7.
630 IDEA appeared in OpenSSL 0.9.7 but was often disabled due to patent
632 concerns; the last patents expired in 2012.
6331.0.2o 2019-02-08 EVP_EncryptInit(3)