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