1EVP_EncryptInit(3)                  OpenSSL                 EVP_EncryptInit(3)
2
3
4

NAME

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

SYNOPSIS

36        #include <openssl/evp.h>
37
38        void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a);
39
40        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
47        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
54        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
61        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
66        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
71        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
76        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
81        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
85        #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
93        #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
104        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
107        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

DESCRIPTION

134       The EVP cipher routines are a high level interface to certain symmetric
135       ciphers.
136
137       EVP_CIPHER_CTX_init() initializes cipher contex ctx.
138
139       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
150       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
158       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
166       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
171       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
180       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
187       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
192       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
197       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
203       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
207       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
212       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
219       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
226       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
230       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
235       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
240       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
247       EVP_CIPHER_CTX_cipher() returns the EVP_CIPHER structure when passed an
248       EVP_CIPHER_CTX structure.
249
250       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
255       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
262       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
274       EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be
275       determined and set.
276

RETURN VALUES

278       EVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex()
279       return 1 for success and 0 for failure.
280
281       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
285       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
289       EVP_CIPHER_CTX_cleanup() returns 1 for success and 0 for failure.
290
291       EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
292       return an EVP_CIPHER structure or NULL on error.
293
294       EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID.
295
296       EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the
297       block size.
298
299       EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
300       length.
301
302       EVP_CIPHER_CTX_set_padding() always returns 1.
303
304       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
307       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
311       EVP_CIPHER_CTX_cipher() returns an EVP_CIPHER structure.
312
313       EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for
314       success or zero for failure.
315

CIPHER LISTING

317       All algorithms have a fixed key length unless otherwise stated.
318
319       EVP_enc_null()
320           Null cipher: does nothing.
321
322       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
326       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
330       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
334       EVP_desx_cbc(void)
335           DESX algorithm in CBC mode.
336
337       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
343       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
349       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
355       EVP_rc4(void)
356           RC4 stream cipher. This is a variable key length cipher with
357           default key length 128 bits.
358
359       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
364       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
369       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
376       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
383       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
387       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
392       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
399       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
404       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

GCM Mode

410       For GCM mode ciphers the behaviour of the EVP interface is subtly
411       altered and several GCM specific ctrl operations are supported.
412
413       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
417       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
422       The following ctrls are supported in GCM mode:
423
424        EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, ivlen, NULL);
425
426       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
429        EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, taglen, tag);
430
431       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
435        EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, taglen, tag);
436
437       Sets the expected tag to taglen bytes from tag. This call is only legal
438       when decrypting data.
439

CCM Mode

441       The behaviour of CCM mode ciphers is similar to CCM mode but with a few
442       additional requirements and different ctrl values.
443
444       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
452       The following ctrls are supported in CCM mode:
453
454        EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, taglen, tag);
455
456       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
461        EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL);
462
463       Sets the CCM L value. If not set a default is used (8 for AES).
464
465        EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, ivlen, NULL);
466
467       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

NOTES

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
479       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
486       When decrypting the final block is checked to see if it has the correct
487       form.
488
489       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
495       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
499       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

BUGS

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
512       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
518       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

EXAMPLES

523       Encrypt a string using IDEA:
524
525        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
538               EVP_CIPHER_CTX_init(&ctx);
539               EVP_EncryptInit_ex(&ctx, EVP_idea_cbc(), NULL, key, iv);
540
541               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
567       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
570        openssl idea -d <filename
571                 -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708
572
573       General encryption and decryption function example using FILE I/O and
574       AES128 with a 128-bit key:
575
576        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
588               /* 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
595               /* Now we can set key and IV */
596               EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);
597
598               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
618               EVP_CIPHER_CTX_cleanup(&ctx);
619               return 1;
620               }
621

SEE ALSO

623       evp(3)
624

HISTORY

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
631       IDEA appeared in OpenSSL 0.9.7 but was often disabled due to patent
632       concerns; the last patents expired in 2012.
633
634
635
6361.0.2o                            2020-08-01                EVP_EncryptInit(3)
Impressum