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