]>
Commit | Line | Data |
---|---|---|
72b60351 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
2cafb1df | 5 | EVP_CIPHER_fetch, |
550f974a RL |
6 | EVP_CIPHER_up_ref, |
7 | EVP_CIPHER_free, | |
8fa4d95e RT |
8 | EVP_CIPHER_CTX_new, |
9 | EVP_CIPHER_CTX_reset, | |
10 | EVP_CIPHER_CTX_free, | |
11 | EVP_EncryptInit_ex, | |
12 | EVP_EncryptUpdate, | |
13 | EVP_EncryptFinal_ex, | |
14 | EVP_DecryptInit_ex, | |
15 | EVP_DecryptUpdate, | |
16 | EVP_DecryptFinal_ex, | |
17 | EVP_CipherInit_ex, | |
18 | EVP_CipherUpdate, | |
19 | EVP_CipherFinal_ex, | |
20 | EVP_CIPHER_CTX_set_key_length, | |
21 | EVP_CIPHER_CTX_ctrl, | |
22 | EVP_EncryptInit, | |
23 | EVP_EncryptFinal, | |
24 | EVP_DecryptInit, | |
25 | EVP_DecryptFinal, | |
26 | EVP_CipherInit, | |
27 | EVP_CipherFinal, | |
f7397f0d | 28 | EVP_Cipher, |
8fa4d95e RT |
29 | EVP_get_cipherbyname, |
30 | EVP_get_cipherbynid, | |
31 | EVP_get_cipherbyobj, | |
7cfa1717 | 32 | EVP_CIPHER_is_a, |
c750bc08 | 33 | EVP_CIPHER_name, |
506cb0f6 | 34 | EVP_CIPHER_number, |
f651c727 | 35 | EVP_CIPHER_names_do_all, |
1d2622d4 | 36 | EVP_CIPHER_provider, |
8fa4d95e | 37 | EVP_CIPHER_nid, |
ae3ff60e RL |
38 | EVP_CIPHER_get_params, |
39 | EVP_CIPHER_gettable_params, | |
8fa4d95e RT |
40 | EVP_CIPHER_block_size, |
41 | EVP_CIPHER_key_length, | |
42 | EVP_CIPHER_iv_length, | |
43 | EVP_CIPHER_flags, | |
44 | EVP_CIPHER_mode, | |
45 | EVP_CIPHER_type, | |
46 | EVP_CIPHER_CTX_cipher, | |
c750bc08 | 47 | EVP_CIPHER_CTX_name, |
8fa4d95e | 48 | EVP_CIPHER_CTX_nid, |
ae3ff60e | 49 | EVP_CIPHER_CTX_get_params, |
41f7ecf3 | 50 | EVP_CIPHER_gettable_ctx_params, |
ae3ff60e | 51 | EVP_CIPHER_CTX_set_params, |
41f7ecf3 | 52 | EVP_CIPHER_settable_ctx_params, |
8fa4d95e RT |
53 | EVP_CIPHER_CTX_block_size, |
54 | EVP_CIPHER_CTX_key_length, | |
55 | EVP_CIPHER_CTX_iv_length, | |
dc64dc2e | 56 | EVP_CIPHER_CTX_tag_length, |
8fa4d95e RT |
57 | EVP_CIPHER_CTX_get_app_data, |
58 | EVP_CIPHER_CTX_set_app_data, | |
59 | EVP_CIPHER_CTX_type, | |
60 | EVP_CIPHER_CTX_flags, | |
61 | EVP_CIPHER_CTX_mode, | |
62 | EVP_CIPHER_param_to_asn1, | |
63 | EVP_CIPHER_asn1_to_param, | |
64 | EVP_CIPHER_CTX_set_padding, | |
c540f00f | 65 | EVP_enc_null, |
251e610c | 66 | EVP_CIPHER_do_all_provided |
8fa4d95e | 67 | - EVP cipher routines |
72b60351 DSH |
68 | |
69 | =head1 SYNOPSIS | |
70 | ||
bb82531f | 71 | =for openssl generic |
b97fdb57 | 72 | |
72b60351 DSH |
73 | #include <openssl/evp.h> |
74 | ||
b4250010 | 75 | EVP_CIPHER *EVP_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, |
2cafb1df | 76 | const char *properties); |
550f974a RL |
77 | int EVP_CIPHER_up_ref(EVP_CIPHER *cipher); |
78 | void EVP_CIPHER_free(EVP_CIPHER *cipher); | |
05fdb8d3 RL |
79 | EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void); |
80 | int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx); | |
81 | void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx); | |
3811eed8 DSH |
82 | |
83 | int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | |
b38fa985 | 84 | ENGINE *impl, const unsigned char *key, const unsigned char *iv); |
a91dedca | 85 | int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, |
7bbb0050 | 86 | int *outl, const unsigned char *in, int inl); |
e9b77246 | 87 | int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); |
3811eed8 DSH |
88 | |
89 | int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | |
b38fa985 | 90 | ENGINE *impl, const unsigned char *key, const unsigned char *iv); |
3811eed8 | 91 | int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, |
7bbb0050 | 92 | int *outl, const unsigned char *in, int inl); |
e9b77246 | 93 | int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); |
3811eed8 DSH |
94 | |
95 | int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | |
b38fa985 | 96 | ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc); |
3811eed8 | 97 | int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, |
b38fa985 | 98 | int *outl, const unsigned char *in, int inl); |
e9b77246 | 99 | int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); |
3811eed8 DSH |
100 | |
101 | int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | |
b38fa985 | 102 | const unsigned char *key, const unsigned char *iv); |
e9b77246 | 103 | int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); |
4d524e10 | 104 | |
a91dedca | 105 | int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
b38fa985 | 106 | const unsigned char *key, const unsigned char *iv); |
e9b77246 | 107 | int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); |
4d524e10 | 108 | |
a91dedca | 109 | int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
b38fa985 | 110 | const unsigned char *key, const unsigned char *iv, int enc); |
e9b77246 | 111 | int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); |
72b60351 | 112 | |
f7397f0d RL |
113 | int EVP_Cipher(EVP_CIPHER_CTX *ctx, unsigned char *out, |
114 | const unsigned char *in, unsigned int inl); | |
115 | ||
f2e5ca84 | 116 | int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding); |
a91dedca DSH |
117 | int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen); |
118 | int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr); | |
5c5eb286 | 119 | int EVP_CIPHER_CTX_rand_key(EVP_CIPHER_CTX *ctx, unsigned char *key); |
72b60351 DSH |
120 | |
121 | const EVP_CIPHER *EVP_get_cipherbyname(const char *name); | |
91da5e77 RS |
122 | const EVP_CIPHER *EVP_get_cipherbynid(int nid); |
123 | const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a); | |
124 | ||
125 | int EVP_CIPHER_nid(const EVP_CIPHER *e); | |
506cb0f6 | 126 | int EVP_CIPHER_number(const EVP_CIPHER *e); |
7cfa1717 | 127 | int EVP_CIPHER_is_a(const EVP_CIPHER *cipher, const char *name); |
d84f5515 MC |
128 | int EVP_CIPHER_names_do_all(const EVP_CIPHER *cipher, |
129 | void (*fn)(const char *name, void *data), | |
130 | void *data); | |
c750bc08 | 131 | const char *EVP_CIPHER_name(const EVP_CIPHER *cipher); |
1d2622d4 | 132 | const OSSL_PROVIDER *EVP_CIPHER_provider(const EVP_CIPHER *cipher); |
91da5e77 | 133 | int EVP_CIPHER_block_size(const EVP_CIPHER *e); |
91da5e77 RS |
134 | int EVP_CIPHER_key_length(const EVP_CIPHER *e); |
135 | int EVP_CIPHER_iv_length(const EVP_CIPHER *e); | |
136 | unsigned long EVP_CIPHER_flags(const EVP_CIPHER *e); | |
137 | unsigned long EVP_CIPHER_mode(const EVP_CIPHER *e); | |
72b60351 | 138 | int EVP_CIPHER_type(const EVP_CIPHER *ctx); |
a91dedca | 139 | |
05fdb8d3 RL |
140 | const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx); |
141 | int EVP_CIPHER_CTX_nid(const EVP_CIPHER_CTX *ctx); | |
c750bc08 | 142 | const char *EVP_CIPHER_CTX_name(const EVP_CIPHER_CTX *ctx); |
ae3ff60e RL |
143 | |
144 | int EVP_CIPHER_get_params(EVP_CIPHER *cipher, OSSL_PARAM params[]); | |
145 | int EVP_CIPHER_CTX_set_params(EVP_CIPHER_CTX *ctx, const OSSL_PARAM params[]); | |
146 | int EVP_CIPHER_CTX_get_params(EVP_CIPHER_CTX *ctx, OSSL_PARAM params[]); | |
147 | const OSSL_PARAM *EVP_CIPHER_gettable_params(const EVP_CIPHER *cipher); | |
41f7ecf3 P |
148 | const OSSL_PARAM *EVP_CIPHER_settable_ctx_params(const EVP_CIPHER *cipher); |
149 | const OSSL_PARAM *EVP_CIPHER_gettable_ctx_params(const EVP_CIPHER *cipher); | |
05fdb8d3 RL |
150 | int EVP_CIPHER_CTX_block_size(const EVP_CIPHER_CTX *ctx); |
151 | int EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx); | |
152 | int EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx); | |
dc64dc2e | 153 | int EVP_CIPHER_CTX_tag_length(const EVP_CIPHER_CTX *ctx); |
05fdb8d3 RL |
154 | void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx); |
155 | void EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data); | |
156 | int EVP_CIPHER_CTX_type(const EVP_CIPHER_CTX *ctx); | |
05fdb8d3 | 157 | int EVP_CIPHER_CTX_mode(const EVP_CIPHER_CTX *ctx); |
72b60351 | 158 | |
3f2b5a88 DSH |
159 | int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); |
160 | int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); | |
161 | ||
b4250010 | 162 | void EVP_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx, |
251e610c RL |
163 | void (*fn)(EVP_CIPHER *cipher, void *arg), |
164 | void *arg); | |
c540f00f | 165 | |
72b60351 DSH |
166 | =head1 DESCRIPTION |
167 | ||
8c1cbc72 | 168 | The EVP cipher routines are a high-level interface to certain |
72b60351 DSH |
169 | symmetric ciphers. |
170 | ||
550f974a RL |
171 | The B<EVP_CIPHER> type is a structure for cipher method implementation. |
172 | ||
2cafb1df RL |
173 | EVP_CIPHER_fetch() fetches the cipher implementation for the given |
174 | B<algorithm> from any provider offering it, within the criteria given | |
175 | by the B<properties>. | |
176 | See L<provider(7)/Fetching algorithms> for further information. | |
177 | ||
550f974a RL |
178 | The returned value must eventually be freed with EVP_CIPHER_free(). |
179 | ||
180 | EVP_CIPHER_up_ref() increments the reference count for an B<EVP_CIPHER> | |
181 | structure. | |
182 | ||
183 | EVP_CIPHER_free() decrements the reference count for the B<EVP_CIPHER> | |
184 | structure. | |
185 | If the reference count drops to 0 then the structure is freed. | |
2cafb1df | 186 | |
05fdb8d3 RL |
187 | EVP_CIPHER_CTX_new() creates a cipher context. |
188 | ||
189 | EVP_CIPHER_CTX_free() clears all information from a cipher context | |
190 | and free up any allocated memory associate with it, including B<ctx> | |
191 | itself. This function should be called after all operations using a | |
192 | cipher are complete so sensitive information does not remain in | |
193 | memory. | |
3811eed8 DSH |
194 | |
195 | EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption | |
2cafb1df RL |
196 | with cipher B<type>. B<type> is typically supplied by a function such |
197 | as EVP_aes_256_cbc(), or a value explicitly fetched with | |
198 | EVP_CIPHER_fetch(). If B<impl> is non-NULL, its implementation of the | |
199 | cipher B<type> is used if there is one, and if not, the default | |
200 | implementation is used. B<key> is the symmetric key to use | |
3811eed8 DSH |
201 | and B<iv> is the IV to use (if necessary), the actual number of bytes |
202 | used for the key and IV depends on the cipher. It is possible to set | |
203 | all parameters to NULL except B<type> in an initial call and supply | |
204 | the remaining parameters in subsequent calls, all of which have B<type> | |
205 | set to NULL. This is done when the default cipher parameters are not | |
206 | appropriate. | |
a672a02a SL |
207 | For EVP_CIPH_GCM_MODE the IV will be generated internally if it is not |
208 | specified. | |
72b60351 DSH |
209 | |
210 | EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and | |
211 | writes the encrypted version to B<out>. This function can be called | |
212 | multiple times to encrypt successive blocks of data. The amount | |
3fc164e8 P |
213 | of data written depends on the block alignment of the encrypted data. |
214 | For most ciphers and modes, the amount of data written can be anything | |
215 | from zero bytes to (inl + cipher_block_size - 1) bytes. | |
216 | For wrap cipher modes, the amount of data written can be anything | |
217 | from zero bytes to (inl + cipher_block_size) bytes. | |
218 | For stream ciphers, the amount of data written can be anything from zero | |
219 | bytes to inl bytes. | |
220 | Thus, B<out> should contain sufficient room for the operation being performed. | |
221 | The actual number of bytes written is placed in B<outl>. It also | |
c3a73daf AP |
222 | checks if B<in> and B<out> are partially overlapping, and if they are |
223 | 0 is returned to indicate failure. | |
72b60351 | 224 | |
3811eed8 | 225 | If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts |
f2e5ca84 | 226 | the "final" data, that is any data that remains in a partial block. |
a09474dd RS |
227 | It uses standard block padding (aka PKCS padding) as described in |
228 | the NOTES section, below. The encrypted | |
f2e5ca84 DSH |
229 | final data is written to B<out> which should have sufficient space for |
230 | one cipher block. The number of bytes written is placed in B<outl>. After | |
231 | this function is called the encryption operation is finished and no further | |
232 | calls to EVP_EncryptUpdate() should be made. | |
233 | ||
3811eed8 | 234 | If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more |
f2e5ca84 | 235 | data and it will return an error if any data remains in a partial block: |
c7497f34 | 236 | that is if the total data length is not a multiple of the block size. |
72b60351 | 237 | |
3811eed8 | 238 | EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the |
72b60351 | 239 | corresponding decryption operations. EVP_DecryptFinal() will return an |
f2e5ca84 DSH |
240 | error code if padding is enabled and the final block is not correctly |
241 | formatted. The parameters and restrictions are identical to the encryption | |
242 | operations except that if padding is enabled the decrypted data buffer B<out> | |
243 | passed to EVP_DecryptUpdate() should have sufficient room for | |
244 | (B<inl> + cipher_block_size) bytes unless the cipher block size is 1 in | |
245 | which case B<inl> bytes is sufficient. | |
72b60351 | 246 | |
3811eed8 DSH |
247 | EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex() are |
248 | functions that can be used for decryption or encryption. The operation | |
249 | performed depends on the value of the B<enc> parameter. It should be set | |
250 | to 1 for encryption, 0 for decryption and -1 to leave the value unchanged | |
251 | (the actual value of 'enc' being supplied in a previous call). | |
252 | ||
05fdb8d3 RL |
253 | EVP_CIPHER_CTX_reset() clears all information from a cipher context |
254 | and free up any allocated memory associate with it, except the B<ctx> | |
255 | itself. This function should be called anytime B<ctx> is to be reused | |
256 | for another EVP_CipherInit() / EVP_CipherUpdate() / EVP_CipherFinal() | |
257 | series of calls. | |
3811eed8 DSH |
258 | |
259 | EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a | |
d4a43700 | 260 | similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex() and |
b45497c3 | 261 | EVP_CipherInit_ex() except they always use the default cipher implementation. |
72b60351 | 262 | |
538860a3 RS |
263 | EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() are |
264 | identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and | |
265 | EVP_CipherFinal_ex(). In previous releases they also cleaned up | |
266 | the B<ctx>, but this is no longer done and EVP_CIPHER_CTX_clean() | |
267 | must be called to free any context resources. | |
72b60351 | 268 | |
f7397f0d RL |
269 | EVP_Cipher() encrypts or decrypts a maximum I<inl> amount of bytes from |
270 | I<in> and leaves the result in I<out>. | |
271 | If the cipher doesn't have the flag B<EVP_CIPH_FLAG_CUSTOM_CIPHER> set, | |
272 | then I<inl> must be a multiple of EVP_CIPHER_block_size(). If it isn't, | |
273 | the result is undefined. If the cipher has that flag set, then I<inl> | |
274 | can be any size. | |
275 | This function is historic and shouldn't be used in an application, please | |
276 | consider using EVP_CipherUpdate() and EVP_CipherFinal_ex instead. | |
277 | ||
3f2b5a88 DSH |
278 | EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() |
279 | return an EVP_CIPHER structure when passed a cipher name, a NID or an | |
280 | ASN1_OBJECT structure. | |
281 | ||
282 | EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when | |
283 | passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> structure. The actual NID | |
284 | value is an internal value which may not have a corresponding OBJECT | |
285 | IDENTIFIER. | |
286 | ||
83f68df3 CPLG |
287 | EVP_CIPHER_CTX_set_padding() enables or disables padding. This |
288 | function should be called after the context is set up for encryption | |
289 | or decryption with EVP_EncryptInit_ex(), EVP_DecryptInit_ex() or | |
290 | EVP_CipherInit_ex(). By default encryption operations are padded using | |
291 | standard block padding and the padding is checked and removed when | |
292 | decrypting. If the B<pad> parameter is zero then no padding is | |
293 | performed, the total amount of data encrypted or decrypted must then | |
294 | be a multiple of the block size or an error will occur. | |
f2e5ca84 | 295 | |
ae3ff60e RL |
296 | EVP_CIPHER_get_params() retrieves the requested list of algorithm |
297 | B<params> from a B<cipher>. | |
298 | ||
299 | EVP_CIPHER_CTX_set_params() Sets the list of operation B<params> into a CIPHER | |
300 | context B<ctx>. | |
301 | ||
302 | EVP_CIPHER_CTX_get_params() retrieves the requested list of operation | |
303 | B<params> from CIPHER context B<ctx>. | |
304 | ||
41f7ecf3 P |
305 | EVP_CIPHER_gettable_params(), EVP_CIPHER_gettable_ctx_params(), and |
306 | EVP_CIPHER_settable_ctx_params() get a constant B<OSSL_PARAM> array | |
79c44b4e | 307 | that describes the retrievable and settable parameters, i.e. parameters |
ae3ff60e RL |
308 | that can be used with EVP_CIPHER_get_params(), EVP_CIPHER_CTX_get_params() |
309 | and EVP_CIPHER_CTX_set_params(), respectively. | |
310 | See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. | |
311 | ||
3f2b5a88 DSH |
312 | EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key |
313 | length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> | |
314 | structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length | |
a91dedca DSH |
315 | for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a |
316 | given cipher, the value of EVP_CIPHER_CTX_key_length() may be different | |
317 | for variable key length ciphers. | |
318 | ||
319 | EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx. | |
320 | If the cipher is a fixed length cipher then attempting to set the key | |
321 | length to any value other than the fixed value is an error. | |
3f2b5a88 DSH |
322 | |
323 | EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV | |
324 | length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>. | |
325 | It will return zero if the cipher does not use an IV. The constant | |
326 | B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers. | |
327 | ||
dc64dc2e SL |
328 | EVP_CIPHER_CTX_tag_length() returns the tag length of a AEAD cipher when passed |
329 | a B<EVP_CIPHER_CTX>. It will return zero if the cipher does not support a tag. | |
330 | It returns a default value if the tag length has not been set. | |
331 | ||
3f2b5a88 DSH |
332 | EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block |
333 | size of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> | |
14f46560 | 334 | structure. The constant B<EVP_MAX_BLOCK_LENGTH> is also the maximum block |
3f2b5a88 DSH |
335 | length for all ciphers. |
336 | ||
337 | EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed | |
338 | cipher or context. This "type" is the actual NID of the cipher OBJECT | |
339 | IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and | |
41e68ef2 DSH |
340 | 128 bit RC2 have the same NID. If the cipher does not have an object |
341 | identifier or does not have ASN1 support this function will return | |
342 | B<NID_undef>. | |
3f2b5a88 | 343 | |
251e610c | 344 | EVP_CIPHER_is_a() returns 1 if I<cipher> is an implementation of an |
7cfa1717 | 345 | algorithm that's identifiable with I<name>, otherwise 0. |
e4a1d023 RL |
346 | If I<cipher> is a legacy cipher (it's the return value from the likes |
347 | of EVP_aes128() rather than the result of an EVP_CIPHER_fetch()), only | |
348 | cipher names registered with the default library context (see | |
b4250010 | 349 | L<OSSL_LIB_CTX(3)>) will be considered. |
7cfa1717 | 350 | |
506cb0f6 RL |
351 | EVP_CIPHER_number() returns the internal dynamic number assigned to |
352 | the I<cipher>. This is only useful with fetched B<EVP_CIPHER>s. | |
353 | ||
c750bc08 | 354 | EVP_CIPHER_name() and EVP_CIPHER_CTX_name() return the name of the passed |
251e610c | 355 | cipher or context. For fetched ciphers with multiple names, only one |
f651c727 RL |
356 | of them is returned; it's recommended to use EVP_CIPHER_names_do_all() |
357 | instead. | |
358 | ||
359 | EVP_CIPHER_names_do_all() traverses all names for the I<cipher>, and | |
360 | calls I<fn> with each name and I<data>. This is only useful with | |
361 | fetched B<EVP_CIPHER>s. | |
c750bc08 | 362 | |
1d2622d4 RL |
363 | EVP_CIPHER_provider() returns an B<OSSL_PROVIDER> pointer to the provider |
364 | that implements the given B<EVP_CIPHER>. | |
365 | ||
3f2b5a88 DSH |
366 | EVP_CIPHER_CTX_cipher() returns the B<EVP_CIPHER> structure when passed |
367 | an B<EVP_CIPHER_CTX> structure. | |
368 | ||
a91dedca | 369 | EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode: |
338ead0f PS |
370 | EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, |
371 | EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE, | |
11dbdc07 MC |
372 | EVP_CIPH_WRAP_MODE, EVP_CIPH_OCB_MODE or EVP_CIPH_SIV_MODE. If the cipher is a |
373 | stream cipher then EVP_CIPH_STREAM_CIPHER is returned. | |
374 | ||
375 | EVP_CIPHER_flags() returns any flags associated with the cipher. See | |
376 | EVP_CIPHER_meth_set_flags() for a list of currently defined flags. | |
a91dedca | 377 | |
3f2b5a88 DSH |
378 | EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based |
379 | on the passed cipher. This will typically include any parameters and an | |
380 | IV. The cipher IV (if any) must be set when this call is made. This call | |
381 | should be made before the cipher is actually "used" (before any | |
382 | EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function | |
383 | may fail if the cipher does not have any ASN1 support. | |
384 | ||
385 | EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1 | |
386 | AlgorithmIdentifier "parameter". The precise effect depends on the cipher | |
387 | In the case of RC2, for example, it will set the IV and effective key length. | |
388 | This function should be called after the base cipher type is set but before | |
389 | the key is set. For example EVP_CipherInit() will be called with the IV and | |
390 | key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally | |
391 | EVP_CipherInit() again with all parameters except the key set to NULL. It is | |
392 | possible for this function to fail if the cipher does not have any ASN1 support | |
393 | or the parameters cannot be set (for example the RC2 effective key length | |
a91dedca DSH |
394 | is not supported. |
395 | ||
396 | EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined | |
aa714f3a | 397 | and set. |
3f2b5a88 | 398 | |
5c5eb286 PS |
399 | EVP_CIPHER_CTX_rand_key() generates a random key of the appropriate length |
400 | based on the cipher context. The EVP_CIPHER can provide its own random key | |
401 | generation routine to support keys of a specific form. B<Key> must point to a | |
402 | buffer at least as big as the value returned by EVP_CIPHER_CTX_key_length(). | |
403 | ||
251e610c | 404 | EVP_CIPHER_do_all_provided() traverses all ciphers implemented by all activated |
c540f00f RL |
405 | providers in the given library context I<libctx>, and for each of the |
406 | implementations, calls the given function I<fn> with the implementation method | |
407 | and the given I<arg> as argument. | |
408 | ||
72b60351 DSH |
409 | =head1 RETURN VALUES |
410 | ||
2cafb1df RL |
411 | EVP_CIPHER_fetch() returns a pointer to a B<EVP_CIPHER> for success |
412 | and B<NULL> for failure. | |
413 | ||
550f974a RL |
414 | EVP_CIPHER_up_ref() returns 1 for success or 0 otherwise. |
415 | ||
05fdb8d3 RL |
416 | EVP_CIPHER_CTX_new() returns a pointer to a newly created |
417 | B<EVP_CIPHER_CTX> for success and B<NULL> for failure. | |
418 | ||
0e304b7f NL |
419 | EVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex() |
420 | return 1 for success and 0 for failure. | |
72b60351 | 421 | |
3811eed8 DSH |
422 | EVP_DecryptInit_ex() and EVP_DecryptUpdate() return 1 for success and 0 for failure. |
423 | EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success. | |
72b60351 | 424 | |
3811eed8 | 425 | EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for failure. |
21d5ed98 | 426 | EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success. |
72b60351 | 427 | |
f7397f0d RL |
428 | EVP_Cipher() returns the amount of encrypted / decrypted bytes, or -1 |
429 | on failure, if the flag B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is set for the | |
430 | cipher. EVP_Cipher() returns 1 on success or 0 on failure, if the flag | |
431 | B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is not set for the cipher. | |
432 | ||
05fdb8d3 | 433 | EVP_CIPHER_CTX_reset() returns 1 for success and 0 for failure. |
3f2b5a88 DSH |
434 | |
435 | EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() | |
436 | return an B<EVP_CIPHER> structure or NULL on error. | |
437 | ||
438 | EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID. | |
439 | ||
440 | EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block | |
441 | size. | |
442 | ||
443 | EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key | |
444 | length. | |
445 | ||
f2e5ca84 DSH |
446 | EVP_CIPHER_CTX_set_padding() always returns 1. |
447 | ||
3f2b5a88 DSH |
448 | EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV |
449 | length or zero if the cipher does not use an IV. | |
450 | ||
dc64dc2e SL |
451 | EVP_CIPHER_CTX_tag_length() return the tag length or zero if the cipher does not |
452 | use a tag. | |
453 | ||
41e68ef2 DSH |
454 | EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher's |
455 | OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER. | |
456 | ||
457 | EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure. | |
458 | ||
c03726ca | 459 | EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return greater |
49c9c1b3 | 460 | than zero for success and zero or a negative number on failure. |
41e68ef2 | 461 | |
5c5eb286 PS |
462 | EVP_CIPHER_CTX_rand_key() returns 1 for success. |
463 | ||
d84f5515 MC |
464 | EVP_CIPHER_names_do_all() returns 1 if the callback was called for all names. |
465 | A return value of 0 means that the callback was not called for any names. | |
466 | ||
a91dedca DSH |
467 | =head1 CIPHER LISTING |
468 | ||
469 | All algorithms have a fixed key length unless otherwise stated. | |
470 | ||
6e4618a0 | 471 | Refer to L</SEE ALSO> for the full list of ciphers available through the EVP |
8fa4d95e RT |
472 | interface. |
473 | ||
a91dedca DSH |
474 | =over 4 |
475 | ||
476 | =item EVP_enc_null() | |
477 | ||
478 | Null cipher: does nothing. | |
479 | ||
8fa4d95e | 480 | =back |
a91dedca | 481 | |
485d3361 | 482 | =head1 AEAD INTERFACE |
a91dedca | 483 | |
8fa4d95e RT |
484 | The EVP interface for Authenticated Encryption with Associated Data (AEAD) |
485 | modes are subtly altered and several additional I<ctrl> operations are supported | |
486 | depending on the mode specified. | |
a91dedca | 487 | |
8fa4d95e RT |
488 | To specify additional authenticated data (AAD), a call to EVP_CipherUpdate(), |
489 | EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output | |
490 | parameter B<out> set to B<NULL>. | |
a91dedca | 491 | |
8fa4d95e RT |
492 | When decrypting, the return value of EVP_DecryptFinal() or EVP_CipherFinal() |
493 | indicates whether the operation was successful. If it does not indicate success, | |
494 | the authentication operation has failed and any output data B<MUST NOT> be used | |
495 | as it is corrupted. | |
a91dedca | 496 | |
8fa4d95e | 497 | =head2 GCM and OCB Modes |
a91dedca | 498 | |
8fa4d95e | 499 | The following I<ctrl>s are supported in GCM and OCB modes. |
a91dedca | 500 | |
8fa4d95e | 501 | =over 4 |
a91dedca | 502 | |
8fa4d95e | 503 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL) |
a91dedca | 504 | |
8fa4d95e RT |
505 | Sets the IV length. This call can only be made before specifying an IV. If |
506 | not called a default IV length is used. | |
a91dedca | 507 | |
8fa4d95e RT |
508 | For GCM AES and OCB AES the default is 12 (i.e. 96 bits). For OCB mode the |
509 | maximum is 15. | |
a91dedca | 510 | |
8fa4d95e | 511 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag) |
a91dedca | 512 | |
8fa4d95e RT |
513 | Writes C<taglen> bytes of the tag value to the buffer indicated by C<tag>. |
514 | This call can only be made when encrypting data and B<after> all data has been | |
515 | processed (e.g. after an EVP_EncryptFinal() call). | |
a91dedca | 516 | |
8fa4d95e RT |
517 | For OCB, C<taglen> must either be 16 or the value previously set via |
518 | B<EVP_CTRL_AEAD_SET_TAG>. | |
a91dedca | 519 | |
8fa4d95e | 520 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag) |
a91dedca | 521 | |
8fa4d95e RT |
522 | Sets the expected tag to C<taglen> bytes from C<tag>. |
523 | The tag length can only be set before specifying an IV. | |
524 | C<taglen> must be between 1 and 16 inclusive. | |
a91dedca | 525 | |
8fa4d95e | 526 | For GCM, this call is only valid when decrypting data. |
a91dedca | 527 | |
8fa4d95e RT |
528 | For OCB, this call is valid when decrypting data to set the expected tag, |
529 | and before encryption to set the desired tag length. | |
a91dedca | 530 | |
8fa4d95e RT |
531 | In OCB mode, calling this before encryption with C<tag> set to C<NULL> sets the |
532 | tag length. If this is not called prior to encryption, a default tag length is | |
533 | used. | |
a91dedca | 534 | |
8fa4d95e RT |
535 | For OCB AES, the default tag length is 16 (i.e. 128 bits). It is also the |
536 | maximum tag length for OCB. | |
a91dedca | 537 | |
8fa4d95e | 538 | =back |
a91dedca | 539 | |
8fa4d95e | 540 | =head2 CCM Mode |
a91dedca | 541 | |
8fa4d95e RT |
542 | The EVP interface for CCM mode is similar to that of the GCM mode but with a |
543 | few additional requirements and different I<ctrl> values. | |
aa714f3a | 544 | |
8fa4d95e RT |
545 | For CCM mode, the total plaintext or ciphertext length B<MUST> be passed to |
546 | EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output | |
547 | and input parameters (B<in> and B<out>) set to B<NULL> and the length passed in | |
548 | the B<inl> parameter. | |
e4bbee96 | 549 | |
8fa4d95e | 550 | The following I<ctrl>s are supported in CCM mode. |
e4bbee96 | 551 | |
8fa4d95e | 552 | =over 4 |
aa714f3a | 553 | |
8fa4d95e | 554 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag) |
aa714f3a | 555 | |
8fa4d95e RT |
556 | This call is made to set the expected B<CCM> tag value when decrypting or |
557 | the length of the tag (with the C<tag> parameter set to NULL) when encrypting. | |
558 | The tag length is often referred to as B<M>. If not set a default value is | |
67c81ec3 TN |
559 | used (12 for AES). When decrypting, the tag needs to be set before passing |
560 | in data to be decrypted, but as in GCM and OCB mode, it can be set after | |
485d3361 | 561 | passing additional authenticated data (see L</AEAD INTERFACE>). |
aa714f3a | 562 | |
8fa4d95e | 563 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL) |
625b9d6b | 564 | |
8fa4d95e | 565 | Sets the CCM B<L> value. If not set a default is used (8 for AES). |
625b9d6b | 566 | |
8fa4d95e | 567 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL) |
625b9d6b | 568 | |
8c1cbc72 | 569 | Sets the CCM nonce (IV) length. This call can only be made before specifying a |
8fa4d95e RT |
570 | nonce value. The nonce length is given by B<15 - L> so it is 7 by default for |
571 | AES. | |
625b9d6b | 572 | |
a91dedca DSH |
573 | =back |
574 | ||
b1ceb439 TS |
575 | =head2 SIV Mode |
576 | ||
577 | For SIV mode ciphers the behaviour of the EVP interface is subtly | |
578 | altered and several additional ctrl operations are supported. | |
579 | ||
580 | To specify any additional authenticated data (AAD) and/or a Nonce, a call to | |
581 | EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made | |
582 | with the output parameter B<out> set to B<NULL>. | |
583 | ||
584 | RFC5297 states that the Nonce is the last piece of AAD before the actual | |
585 | encrypt/decrypt takes place. The API does not differentiate the Nonce from | |
586 | other AAD. | |
587 | ||
588 | When decrypting the return value of EVP_DecryptFinal() or EVP_CipherFinal() | |
589 | indicates if the operation was successful. If it does not indicate success | |
590 | the authentication operation has failed and any output data B<MUST NOT> | |
591 | be used as it is corrupted. | |
592 | ||
593 | The following ctrls are supported in both SIV modes. | |
594 | ||
595 | =over 4 | |
596 | ||
597 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag); | |
598 | ||
599 | Writes B<taglen> bytes of the tag value to the buffer indicated by B<tag>. | |
600 | This call can only be made when encrypting data and B<after> all data has been | |
601 | processed (e.g. after an EVP_EncryptFinal() call). For SIV mode the taglen must | |
602 | be 16. | |
603 | ||
604 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag); | |
605 | ||
606 | Sets the expected tag to B<taglen> bytes from B<tag>. This call is only legal | |
607 | when decrypting data and must be made B<before> any data is processed (e.g. | |
608 | before any EVP_DecryptUpdate() call). For SIV mode the taglen must be 16. | |
609 | ||
610 | =back | |
611 | ||
612 | SIV mode makes two passes over the input data, thus, only one call to | |
613 | EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made | |
614 | with B<out> set to a non-B<NULL> value. A call to EVP_Decrypt_Final() or | |
615 | EVP_CipherFinal() is not required, but will indicate if the update | |
616 | operation succeeded. | |
617 | ||
8fa4d95e | 618 | =head2 ChaCha20-Poly1305 |
aa714f3a | 619 | |
8fa4d95e | 620 | The following I<ctrl>s are supported for the ChaCha20-Poly1305 AEAD algorithm. |
aa714f3a | 621 | |
8fa4d95e | 622 | =over 4 |
aa714f3a | 623 | |
8fa4d95e | 624 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL) |
aa714f3a | 625 | |
8fa4d95e RT |
626 | Sets the nonce length. This call can only be made before specifying the nonce. |
627 | If not called a default nonce length of 12 (i.e. 96 bits) is used. The maximum | |
27d56312 MC |
628 | nonce length is 12 bytes (i.e. 96-bits). If a nonce of less than 12 bytes is set |
629 | then the nonce is automatically padded with leading 0 bytes to make it 12 bytes | |
630 | in length. | |
c7497f34 | 631 | |
8fa4d95e | 632 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag) |
aa714f3a | 633 | |
8fa4d95e | 634 | Writes C<taglen> bytes of the tag value to the buffer indicated by C<tag>. |
aa714f3a | 635 | This call can only be made when encrypting data and B<after> all data has been |
8fa4d95e | 636 | processed (e.g. after an EVP_EncryptFinal() call). |
c7497f34 | 637 | |
8fa4d95e RT |
638 | C<taglen> specified here must be 16 (B<POLY1305_BLOCK_SIZE>, i.e. 128-bits) or |
639 | less. | |
aa714f3a | 640 | |
8fa4d95e | 641 | =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag) |
aa714f3a | 642 | |
8fa4d95e RT |
643 | Sets the expected tag to C<taglen> bytes from C<tag>. |
644 | The tag length can only be set before specifying an IV. | |
645 | C<taglen> must be between 1 and 16 (B<POLY1305_BLOCK_SIZE>) inclusive. | |
646 | This call is only valid when decrypting data. | |
aa714f3a | 647 | |
8fa4d95e | 648 | =back |
aa714f3a | 649 | |
72b60351 DSH |
650 | =head1 NOTES |
651 | ||
652 | Where possible the B<EVP> interface to symmetric ciphers should be used in | |
8c1cbc72 | 653 | preference to the low-level interfaces. This is because the code then becomes |
75b76068 JW |
654 | transparent to the cipher used and much more flexible. Additionally, the |
655 | B<EVP> interface will ensure the use of platform specific cryptographic | |
8c1cbc72 | 656 | acceleration such as AES-NI (the low-level interfaces do not provide the |
75b76068 | 657 | guarantee). |
72b60351 | 658 | |
c7497f34 | 659 | PKCS padding works by adding B<n> padding bytes of value B<n> to make the total |
72b60351 DSH |
660 | length of the encrypted data a multiple of the block size. Padding is always |
661 | added so if the data is already a multiple of the block size B<n> will equal | |
662 | the block size. For example if the block size is 8 and 11 bytes are to be | |
663 | encrypted then 5 padding bytes of value 5 will be added. | |
664 | ||
665 | When decrypting the final block is checked to see if it has the correct form. | |
666 | ||
f2e5ca84 DSH |
667 | Although the decryption operation can produce an error if padding is enabled, |
668 | it is not a strong test that the input data or key is correct. A random block | |
669 | has better than 1 in 256 chance of being of the correct format and problems with | |
670 | the input data earlier on will not produce a final decrypt error. | |
671 | ||
672 | If padding is disabled then the decryption operation will always succeed if | |
673 | the total amount of data decrypted is a multiple of the block size. | |
72b60351 | 674 | |
3811eed8 DSH |
675 | The functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(), |
676 | EVP_CipherInit() and EVP_CipherFinal() are obsolete but are retained for | |
677 | compatibility with existing code. New code should use EVP_EncryptInit_ex(), | |
678 | EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), | |
679 | EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an | |
680 | existing context without allocating and freeing it up on each call. | |
a91dedca | 681 | |
32745fcc DB |
682 | There are some differences between functions EVP_CipherInit() and |
683 | EVP_CipherInit_ex(), significant in some circumstances. EVP_CipherInit() fills | |
684 | the passed context object with zeros. As a consequence, EVP_CipherInit() does | |
685 | not allow step-by-step initialization of the ctx when the I<key> and I<iv> are | |
686 | passed in separate calls. It also means that the flags set for the CTX are | |
687 | removed, and it is especially important for the | |
688 | B<EVP_CIPHER_CTX_FLAG_WRAP_ALLOW> flag treated specially in | |
689 | EVP_CipherInit_ex(). | |
690 | ||
91da5e77 RS |
691 | EVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as macros. |
692 | ||
72b60351 DSH |
693 | =head1 BUGS |
694 | ||
8fa4d95e RT |
695 | B<EVP_MAX_KEY_LENGTH> and B<EVP_MAX_IV_LENGTH> only refer to the internal |
696 | ciphers with default key lengths. If custom ciphers exceed these values the | |
697 | results are unpredictable. This is because it has become standard practice to | |
698 | define a generic key as a fixed unsigned char array containing | |
699 | B<EVP_MAX_KEY_LENGTH> bytes. | |
a91dedca | 700 | |
c8973693 | 701 | The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested |
a91dedca DSH |
702 | for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode. |
703 | ||
704 | =head1 EXAMPLES | |
705 | ||
fd4592be | 706 | Encrypt a string using IDEA: |
18135561 DSH |
707 | |
708 | int do_crypt(char *outfile) | |
2947af32 BB |
709 | { |
710 | unsigned char outbuf[1024]; | |
711 | int outlen, tmplen; | |
712 | /* | |
713 | * Bogus key and IV: we'd normally set these from | |
714 | * another source. | |
715 | */ | |
716 | unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; | |
717 | unsigned char iv[] = {1,2,3,4,5,6,7,8}; | |
718 | char intext[] = "Some Crypto Text"; | |
719 | EVP_CIPHER_CTX *ctx; | |
720 | FILE *out; | |
721 | ||
722 | ctx = EVP_CIPHER_CTX_new(); | |
723 | EVP_EncryptInit_ex(ctx, EVP_idea_cbc(), NULL, key, iv); | |
724 | ||
725 | if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) { | |
726 | /* Error */ | |
519a5d1e | 727 | EVP_CIPHER_CTX_free(ctx); |
2947af32 BB |
728 | return 0; |
729 | } | |
730 | /* | |
731 | * Buffer passed to EVP_EncryptFinal() must be after data just | |
732 | * encrypted to avoid overwriting it. | |
733 | */ | |
734 | if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) { | |
735 | /* Error */ | |
519a5d1e | 736 | EVP_CIPHER_CTX_free(ctx); |
2947af32 BB |
737 | return 0; |
738 | } | |
739 | outlen += tmplen; | |
740 | EVP_CIPHER_CTX_free(ctx); | |
741 | /* | |
742 | * Need binary mode for fopen because encrypted data is | |
743 | * binary data. Also cannot use strlen() on it because | |
744 | * it won't be NUL terminated and may contain embedded | |
745 | * NULs. | |
746 | */ | |
747 | out = fopen(outfile, "wb"); | |
519a5d1e GZ |
748 | if (out == NULL) { |
749 | /* Error */ | |
750 | return 0; | |
751 | } | |
2947af32 BB |
752 | fwrite(outbuf, 1, outlen, out); |
753 | fclose(out); | |
754 | return 1; | |
755 | } | |
18135561 DSH |
756 | |
757 | The ciphertext from the above example can be decrypted using the B<openssl> | |
fd4592be | 758 | utility with the command line (shown on two lines for clarity): |
c7497f34 | 759 | |
2947af32 BB |
760 | openssl idea -d \ |
761 | -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 <filename | |
18135561 | 762 | |
fd4592be JS |
763 | General encryption and decryption function example using FILE I/O and AES128 |
764 | with a 128-bit key: | |
18135561 DSH |
765 | |
766 | int do_crypt(FILE *in, FILE *out, int do_encrypt) | |
2947af32 BB |
767 | { |
768 | /* Allow enough space in output buffer for additional block */ | |
769 | unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; | |
770 | int inlen, outlen; | |
771 | EVP_CIPHER_CTX *ctx; | |
772 | /* | |
773 | * Bogus key and IV: we'd normally set these from | |
774 | * another source. | |
775 | */ | |
776 | unsigned char key[] = "0123456789abcdeF"; | |
777 | unsigned char iv[] = "1234567887654321"; | |
778 | ||
779 | /* Don't set key or IV right away; we want to check lengths */ | |
780 | ctx = EVP_CIPHER_CTX_new(); | |
d561b841 | 781 | EVP_CipherInit_ex(ctx, EVP_aes_128_cbc(), NULL, NULL, NULL, |
2947af32 BB |
782 | do_encrypt); |
783 | OPENSSL_assert(EVP_CIPHER_CTX_key_length(ctx) == 16); | |
784 | OPENSSL_assert(EVP_CIPHER_CTX_iv_length(ctx) == 16); | |
785 | ||
786 | /* Now we can set key and IV */ | |
787 | EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt); | |
788 | ||
789 | for (;;) { | |
790 | inlen = fread(inbuf, 1, 1024, in); | |
791 | if (inlen <= 0) | |
792 | break; | |
793 | if (!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, inlen)) { | |
794 | /* Error */ | |
795 | EVP_CIPHER_CTX_free(ctx); | |
796 | return 0; | |
797 | } | |
798 | fwrite(outbuf, 1, outlen, out); | |
799 | } | |
800 | if (!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) { | |
801 | /* Error */ | |
802 | EVP_CIPHER_CTX_free(ctx); | |
803 | return 0; | |
804 | } | |
805 | fwrite(outbuf, 1, outlen, out); | |
806 | ||
807 | EVP_CIPHER_CTX_free(ctx); | |
808 | return 1; | |
809 | } | |
18135561 | 810 | |
7cc355c2 SL |
811 | Encryption using AES-CBC with a 256-bit key with "CS1" ciphertext stealing. |
812 | ||
813 | int encrypt(const unsigned char *key, const unsigned char *iv, | |
814 | const unsigned char *msg, size_t msg_len, unsigned char *out) | |
815 | { | |
816 | /* | |
817 | * This assumes that key size is 32 bytes and the iv is 16 bytes. | |
818 | * For ciphertext stealing mode the length of the ciphertext "out" will be | |
819 | * the same size as the plaintext size "msg_len". | |
820 | * The "msg_len" can be any size >= 16. | |
821 | */ | |
822 | int ret = 0, encrypt = 1, outlen, len; | |
823 | EVP_CIPHER_CTX *ctx = NULL; | |
824 | EVP_CIPHER *cipher = NULL; | |
825 | OSSL_PARAM params[2]; | |
826 | ||
827 | ctx = EVP_CIPHER_CTX_new(); | |
828 | cipher = EVP_CIPHER_fetch(NULL, "AES-256-CBC-CTS", NULL); | |
829 | if (ctx == NULL || cipher == NULL) | |
830 | goto err; | |
831 | ||
832 | if (!EVP_CipherInit_ex(ctx, cipher, NULL, key, iv, encrypt)) | |
833 | goto err; | |
834 | /* | |
835 | * The default is "CS1" so this is not really needed, | |
836 | * but would be needed to set either "CS2" or "CS3". | |
837 | */ | |
838 | params[0] = OSSL_PARAM_construct_utf8_string(OSSL_CIPHER_PARAM_CTS_MODE, | |
839 | "CS1", 0); | |
840 | params[1] = OSSL_PARAM_construct_end(); | |
841 | if (!EVP_CIPHER_CTX_set_params(ctx, params)) | |
842 | goto err; | |
843 | ||
844 | /* NOTE: CTS mode does not support multiple calls to EVP_CipherUpdate() */ | |
845 | if (!EVP_CipherUpdate(ctx, encrypted, &outlen, msg, msglen)) | |
846 | goto err; | |
847 | if (!EVP_CipherFinal_ex(ctx, encrypted + outlen, &len)) | |
848 | goto err; | |
849 | ret = 1; | |
850 | err: | |
851 | EVP_CIPHER_free(cipher); | |
852 | EVP_CIPHER_CTX_free(ctx); | |
853 | return ret; | |
854 | } | |
18135561 | 855 | |
72b60351 DSH |
856 | =head1 SEE ALSO |
857 | ||
b97fdb57 | 858 | L<evp(7)> |
72b60351 | 859 | |
8fa4d95e RT |
860 | Supported ciphers are listed in: |
861 | ||
d7cea0b8 RS |
862 | L<EVP_aes_128_gcm(3)>, |
863 | L<EVP_aria_128_gcm(3)>, | |
864 | L<EVP_bf_cbc(3)>, | |
865 | L<EVP_camellia_128_ecb(3)>, | |
866 | L<EVP_cast5_cbc(3)>, | |
8fa4d95e | 867 | L<EVP_chacha20(3)>, |
d7cea0b8 RS |
868 | L<EVP_des_cbc(3)>, |
869 | L<EVP_desx_cbc(3)>, | |
870 | L<EVP_idea_cbc(3)>, | |
871 | L<EVP_rc2_cbc(3)>, | |
8fa4d95e | 872 | L<EVP_rc4(3)>, |
d7cea0b8 RS |
873 | L<EVP_rc5_32_12_16_cbc(3)>, |
874 | L<EVP_seed_cbc(3)>, | |
875 | L<EVP_sm4_cbc(3)> | |
8fa4d95e | 876 | |
72b60351 DSH |
877 | =head1 HISTORY |
878 | ||
fc5ecadd | 879 | Support for OCB mode was added in OpenSSL 1.1.0. |
a528d4f0 | 880 | |
05fdb8d3 RL |
881 | B<EVP_CIPHER_CTX> was made opaque in OpenSSL 1.1.0. As a result, |
882 | EVP_CIPHER_CTX_reset() appeared and EVP_CIPHER_CTX_cleanup() | |
883 | disappeared. EVP_CIPHER_CTX_init() remains as an alias for | |
884 | EVP_CIPHER_CTX_reset(). | |
885 | ||
550f974a RL |
886 | The EVP_CIPHER_fetch(), EVP_CIPHER_free(), EVP_CIPHER_up_ref(), |
887 | EVP_CIPHER_CTX_set_params() and EVP_CIPHER_CTX_get_params() functions | |
888 | were added in 3.0. | |
889 | ||
e2f92610 RS |
890 | =head1 COPYRIGHT |
891 | ||
33388b44 | 892 | Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 893 | |
4746f25a | 894 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
895 | this file except in compliance with the License. You can obtain a copy |
896 | in the file LICENSE in the source distribution or at | |
897 | L<https://www.openssl.org/source/license.html>. | |
898 | ||
899 | =cut |