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