xref: /freebsd/crypto/openssl/doc/man3/EVP_EncryptInit.pod (revision e71b70530d95c4f34d8bdbd78d1242df1ba4a945)
1*e71b7053SJung-uk Kim=pod
2*e71b7053SJung-uk Kim
3*e71b7053SJung-uk Kim=head1 NAME
4*e71b7053SJung-uk Kim
5*e71b7053SJung-uk KimEVP_CIPHER_CTX_new,
6*e71b7053SJung-uk KimEVP_CIPHER_CTX_reset,
7*e71b7053SJung-uk KimEVP_CIPHER_CTX_free,
8*e71b7053SJung-uk KimEVP_EncryptInit_ex,
9*e71b7053SJung-uk KimEVP_EncryptUpdate,
10*e71b7053SJung-uk KimEVP_EncryptFinal_ex,
11*e71b7053SJung-uk KimEVP_DecryptInit_ex,
12*e71b7053SJung-uk KimEVP_DecryptUpdate,
13*e71b7053SJung-uk KimEVP_DecryptFinal_ex,
14*e71b7053SJung-uk KimEVP_CipherInit_ex,
15*e71b7053SJung-uk KimEVP_CipherUpdate,
16*e71b7053SJung-uk KimEVP_CipherFinal_ex,
17*e71b7053SJung-uk KimEVP_CIPHER_CTX_set_key_length,
18*e71b7053SJung-uk KimEVP_CIPHER_CTX_ctrl,
19*e71b7053SJung-uk KimEVP_EncryptInit,
20*e71b7053SJung-uk KimEVP_EncryptFinal,
21*e71b7053SJung-uk KimEVP_DecryptInit,
22*e71b7053SJung-uk KimEVP_DecryptFinal,
23*e71b7053SJung-uk KimEVP_CipherInit,
24*e71b7053SJung-uk KimEVP_CipherFinal,
25*e71b7053SJung-uk KimEVP_get_cipherbyname,
26*e71b7053SJung-uk KimEVP_get_cipherbynid,
27*e71b7053SJung-uk KimEVP_get_cipherbyobj,
28*e71b7053SJung-uk KimEVP_CIPHER_nid,
29*e71b7053SJung-uk KimEVP_CIPHER_block_size,
30*e71b7053SJung-uk KimEVP_CIPHER_key_length,
31*e71b7053SJung-uk KimEVP_CIPHER_iv_length,
32*e71b7053SJung-uk KimEVP_CIPHER_flags,
33*e71b7053SJung-uk KimEVP_CIPHER_mode,
34*e71b7053SJung-uk KimEVP_CIPHER_type,
35*e71b7053SJung-uk KimEVP_CIPHER_CTX_cipher,
36*e71b7053SJung-uk KimEVP_CIPHER_CTX_nid,
37*e71b7053SJung-uk KimEVP_CIPHER_CTX_block_size,
38*e71b7053SJung-uk KimEVP_CIPHER_CTX_key_length,
39*e71b7053SJung-uk KimEVP_CIPHER_CTX_iv_length,
40*e71b7053SJung-uk KimEVP_CIPHER_CTX_get_app_data,
41*e71b7053SJung-uk KimEVP_CIPHER_CTX_set_app_data,
42*e71b7053SJung-uk KimEVP_CIPHER_CTX_type,
43*e71b7053SJung-uk KimEVP_CIPHER_CTX_flags,
44*e71b7053SJung-uk KimEVP_CIPHER_CTX_mode,
45*e71b7053SJung-uk KimEVP_CIPHER_param_to_asn1,
46*e71b7053SJung-uk KimEVP_CIPHER_asn1_to_param,
47*e71b7053SJung-uk KimEVP_CIPHER_CTX_set_padding,
48*e71b7053SJung-uk KimEVP_enc_null
49*e71b7053SJung-uk Kim- EVP cipher routines
50*e71b7053SJung-uk Kim
51*e71b7053SJung-uk Kim=head1 SYNOPSIS
52*e71b7053SJung-uk Kim
53*e71b7053SJung-uk Kim=for comment generic
54*e71b7053SJung-uk Kim
55*e71b7053SJung-uk Kim #include <openssl/evp.h>
56*e71b7053SJung-uk Kim
57*e71b7053SJung-uk Kim EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void);
58*e71b7053SJung-uk Kim int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx);
59*e71b7053SJung-uk Kim void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx);
60*e71b7053SJung-uk Kim
61*e71b7053SJung-uk Kim int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
62*e71b7053SJung-uk Kim                        ENGINE *impl, const unsigned char *key, const unsigned char *iv);
63*e71b7053SJung-uk Kim int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
64*e71b7053SJung-uk Kim                       int *outl, const unsigned char *in, int inl);
65*e71b7053SJung-uk Kim int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
66*e71b7053SJung-uk Kim
67*e71b7053SJung-uk Kim int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
68*e71b7053SJung-uk Kim                        ENGINE *impl, const unsigned char *key, const unsigned char *iv);
69*e71b7053SJung-uk Kim int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
70*e71b7053SJung-uk Kim                       int *outl, const unsigned char *in, int inl);
71*e71b7053SJung-uk Kim int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
72*e71b7053SJung-uk Kim
73*e71b7053SJung-uk Kim int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
74*e71b7053SJung-uk Kim                       ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc);
75*e71b7053SJung-uk Kim int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
76*e71b7053SJung-uk Kim                      int *outl, const unsigned char *in, int inl);
77*e71b7053SJung-uk Kim int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
78*e71b7053SJung-uk Kim
79*e71b7053SJung-uk Kim int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
80*e71b7053SJung-uk Kim                     const unsigned char *key, const unsigned char *iv);
81*e71b7053SJung-uk Kim int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
82*e71b7053SJung-uk Kim
83*e71b7053SJung-uk Kim int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
84*e71b7053SJung-uk Kim                     const unsigned char *key, const unsigned char *iv);
85*e71b7053SJung-uk Kim int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
86*e71b7053SJung-uk Kim
87*e71b7053SJung-uk Kim int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
88*e71b7053SJung-uk Kim                    const unsigned char *key, const unsigned char *iv, int enc);
89*e71b7053SJung-uk Kim int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
90*e71b7053SJung-uk Kim
91*e71b7053SJung-uk Kim int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);
92*e71b7053SJung-uk Kim int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);
93*e71b7053SJung-uk Kim int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);
94*e71b7053SJung-uk Kim int EVP_CIPHER_CTX_rand_key(EVP_CIPHER_CTX *ctx, unsigned char *key);
95*e71b7053SJung-uk Kim
96*e71b7053SJung-uk Kim const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
97*e71b7053SJung-uk Kim const EVP_CIPHER *EVP_get_cipherbynid(int nid);
98*e71b7053SJung-uk Kim const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a);
99*e71b7053SJung-uk Kim
100*e71b7053SJung-uk Kim int EVP_CIPHER_nid(const EVP_CIPHER *e);
101*e71b7053SJung-uk Kim int EVP_CIPHER_block_size(const EVP_CIPHER *e);
102*e71b7053SJung-uk Kim int EVP_CIPHER_key_length(const EVP_CIPHER *e);
103*e71b7053SJung-uk Kim int EVP_CIPHER_iv_length(const EVP_CIPHER *e);
104*e71b7053SJung-uk Kim unsigned long EVP_CIPHER_flags(const EVP_CIPHER *e);
105*e71b7053SJung-uk Kim unsigned long EVP_CIPHER_mode(const EVP_CIPHER *e);
106*e71b7053SJung-uk Kim int EVP_CIPHER_type(const EVP_CIPHER *ctx);
107*e71b7053SJung-uk Kim
108*e71b7053SJung-uk Kim const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx);
109*e71b7053SJung-uk Kim int EVP_CIPHER_CTX_nid(const EVP_CIPHER_CTX *ctx);
110*e71b7053SJung-uk Kim int EVP_CIPHER_CTX_block_size(const EVP_CIPHER_CTX *ctx);
111*e71b7053SJung-uk Kim int EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx);
112*e71b7053SJung-uk Kim int EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx);
113*e71b7053SJung-uk Kim void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx);
114*e71b7053SJung-uk Kim void EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data);
115*e71b7053SJung-uk Kim int EVP_CIPHER_CTX_type(const EVP_CIPHER_CTX *ctx);
116*e71b7053SJung-uk Kim int EVP_CIPHER_CTX_mode(const EVP_CIPHER_CTX *ctx);
117*e71b7053SJung-uk Kim
118*e71b7053SJung-uk Kim int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
119*e71b7053SJung-uk Kim int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
120*e71b7053SJung-uk Kim
121*e71b7053SJung-uk Kim=head1 DESCRIPTION
122*e71b7053SJung-uk Kim
123*e71b7053SJung-uk KimThe EVP cipher routines are a high level interface to certain
124*e71b7053SJung-uk Kimsymmetric ciphers.
125*e71b7053SJung-uk Kim
126*e71b7053SJung-uk KimEVP_CIPHER_CTX_new() creates a cipher context.
127*e71b7053SJung-uk Kim
128*e71b7053SJung-uk KimEVP_CIPHER_CTX_free() clears all information from a cipher context
129*e71b7053SJung-uk Kimand free up any allocated memory associate with it, including B<ctx>
130*e71b7053SJung-uk Kimitself. This function should be called after all operations using a
131*e71b7053SJung-uk Kimcipher are complete so sensitive information does not remain in
132*e71b7053SJung-uk Kimmemory.
133*e71b7053SJung-uk Kim
134*e71b7053SJung-uk KimEVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption
135*e71b7053SJung-uk Kimwith cipher B<type> from ENGINE B<impl>. B<ctx> must be created
136*e71b7053SJung-uk Kimbefore calling this function. B<type> is normally supplied
137*e71b7053SJung-uk Kimby a function such as EVP_aes_256_cbc(). If B<impl> is NULL then the
138*e71b7053SJung-uk Kimdefault implementation is used. B<key> is the symmetric key to use
139*e71b7053SJung-uk Kimand B<iv> is the IV to use (if necessary), the actual number of bytes
140*e71b7053SJung-uk Kimused for the key and IV depends on the cipher. It is possible to set
141*e71b7053SJung-uk Kimall parameters to NULL except B<type> in an initial call and supply
142*e71b7053SJung-uk Kimthe remaining parameters in subsequent calls, all of which have B<type>
143*e71b7053SJung-uk Kimset to NULL. This is done when the default cipher parameters are not
144*e71b7053SJung-uk Kimappropriate.
145*e71b7053SJung-uk Kim
146*e71b7053SJung-uk KimEVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and
147*e71b7053SJung-uk Kimwrites the encrypted version to B<out>. This function can be called
148*e71b7053SJung-uk Kimmultiple times to encrypt successive blocks of data. The amount
149*e71b7053SJung-uk Kimof data written depends on the block alignment of the encrypted data:
150*e71b7053SJung-uk Kimas a result the amount of data written may be anything from zero bytes
151*e71b7053SJung-uk Kimto (inl + cipher_block_size - 1) so B<out> should contain sufficient
152*e71b7053SJung-uk Kimroom. The actual number of bytes written is placed in B<outl>. It also
153*e71b7053SJung-uk Kimchecks if B<in> and B<out> are partially overlapping, and if they are
154*e71b7053SJung-uk Kim0 is returned to indicate failure.
155*e71b7053SJung-uk Kim
156*e71b7053SJung-uk KimIf padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts
157*e71b7053SJung-uk Kimthe "final" data, that is any data that remains in a partial block.
158*e71b7053SJung-uk KimIt uses standard block padding (aka PKCS padding) as described in
159*e71b7053SJung-uk Kimthe NOTES section, below. The encrypted
160*e71b7053SJung-uk Kimfinal data is written to B<out> which should have sufficient space for
161*e71b7053SJung-uk Kimone cipher block. The number of bytes written is placed in B<outl>. After
162*e71b7053SJung-uk Kimthis function is called the encryption operation is finished and no further
163*e71b7053SJung-uk Kimcalls to EVP_EncryptUpdate() should be made.
164*e71b7053SJung-uk Kim
165*e71b7053SJung-uk KimIf padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more
166*e71b7053SJung-uk Kimdata and it will return an error if any data remains in a partial block:
167*e71b7053SJung-uk Kimthat is if the total data length is not a multiple of the block size.
168*e71b7053SJung-uk Kim
169*e71b7053SJung-uk KimEVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the
170*e71b7053SJung-uk Kimcorresponding decryption operations. EVP_DecryptFinal() will return an
171*e71b7053SJung-uk Kimerror code if padding is enabled and the final block is not correctly
172*e71b7053SJung-uk Kimformatted. The parameters and restrictions are identical to the encryption
173*e71b7053SJung-uk Kimoperations except that if padding is enabled the decrypted data buffer B<out>
174*e71b7053SJung-uk Kimpassed to EVP_DecryptUpdate() should have sufficient room for
175*e71b7053SJung-uk Kim(B<inl> + cipher_block_size) bytes unless the cipher block size is 1 in
176*e71b7053SJung-uk Kimwhich case B<inl> bytes is sufficient.
177*e71b7053SJung-uk Kim
178*e71b7053SJung-uk KimEVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex() are
179*e71b7053SJung-uk Kimfunctions that can be used for decryption or encryption. The operation
180*e71b7053SJung-uk Kimperformed depends on the value of the B<enc> parameter. It should be set
181*e71b7053SJung-uk Kimto 1 for encryption, 0 for decryption and -1 to leave the value unchanged
182*e71b7053SJung-uk Kim(the actual value of 'enc' being supplied in a previous call).
183*e71b7053SJung-uk Kim
184*e71b7053SJung-uk KimEVP_CIPHER_CTX_reset() clears all information from a cipher context
185*e71b7053SJung-uk Kimand free up any allocated memory associate with it, except the B<ctx>
186*e71b7053SJung-uk Kimitself. This function should be called anytime B<ctx> is to be reused
187*e71b7053SJung-uk Kimfor another EVP_CipherInit() / EVP_CipherUpdate() / EVP_CipherFinal()
188*e71b7053SJung-uk Kimseries of calls.
189*e71b7053SJung-uk Kim
190*e71b7053SJung-uk KimEVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a
191*e71b7053SJung-uk Kimsimilar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex() and
192*e71b7053SJung-uk KimEVP_CipherInit_ex() except they always use the default cipher implementation.
193*e71b7053SJung-uk Kim
194*e71b7053SJung-uk KimEVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() are
195*e71b7053SJung-uk Kimidentical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and
196*e71b7053SJung-uk KimEVP_CipherFinal_ex(). In previous releases they also cleaned up
197*e71b7053SJung-uk Kimthe B<ctx>, but this is no longer done and EVP_CIPHER_CTX_clean()
198*e71b7053SJung-uk Kimmust be called to free any context resources.
199*e71b7053SJung-uk Kim
200*e71b7053SJung-uk KimEVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
201*e71b7053SJung-uk Kimreturn an EVP_CIPHER structure when passed a cipher name, a NID or an
202*e71b7053SJung-uk KimASN1_OBJECT structure.
203*e71b7053SJung-uk Kim
204*e71b7053SJung-uk KimEVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when
205*e71b7053SJung-uk Kimpassed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> structure.  The actual NID
206*e71b7053SJung-uk Kimvalue is an internal value which may not have a corresponding OBJECT
207*e71b7053SJung-uk KimIDENTIFIER.
208*e71b7053SJung-uk Kim
209*e71b7053SJung-uk KimEVP_CIPHER_CTX_set_padding() enables or disables padding. This
210*e71b7053SJung-uk Kimfunction should be called after the context is set up for encryption
211*e71b7053SJung-uk Kimor decryption with EVP_EncryptInit_ex(), EVP_DecryptInit_ex() or
212*e71b7053SJung-uk KimEVP_CipherInit_ex(). By default encryption operations are padded using
213*e71b7053SJung-uk Kimstandard block padding and the padding is checked and removed when
214*e71b7053SJung-uk Kimdecrypting. If the B<pad> parameter is zero then no padding is
215*e71b7053SJung-uk Kimperformed, the total amount of data encrypted or decrypted must then
216*e71b7053SJung-uk Kimbe a multiple of the block size or an error will occur.
217*e71b7053SJung-uk Kim
218*e71b7053SJung-uk KimEVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
219*e71b7053SJung-uk Kimlength of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
220*e71b7053SJung-uk Kimstructure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length
221*e71b7053SJung-uk Kimfor all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a
222*e71b7053SJung-uk Kimgiven cipher, the value of EVP_CIPHER_CTX_key_length() may be different
223*e71b7053SJung-uk Kimfor variable key length ciphers.
224*e71b7053SJung-uk Kim
225*e71b7053SJung-uk KimEVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx.
226*e71b7053SJung-uk KimIf the cipher is a fixed length cipher then attempting to set the key
227*e71b7053SJung-uk Kimlength to any value other than the fixed value is an error.
228*e71b7053SJung-uk Kim
229*e71b7053SJung-uk KimEVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
230*e71b7053SJung-uk Kimlength of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>.
231*e71b7053SJung-uk KimIt will return zero if the cipher does not use an IV.  The constant
232*e71b7053SJung-uk KimB<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers.
233*e71b7053SJung-uk Kim
234*e71b7053SJung-uk KimEVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block
235*e71b7053SJung-uk Kimsize of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
236*e71b7053SJung-uk Kimstructure. The constant B<EVP_MAX_BLOCK_LENGTH> is also the maximum block
237*e71b7053SJung-uk Kimlength for all ciphers.
238*e71b7053SJung-uk Kim
239*e71b7053SJung-uk KimEVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed
240*e71b7053SJung-uk Kimcipher or context. This "type" is the actual NID of the cipher OBJECT
241*e71b7053SJung-uk KimIDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and
242*e71b7053SJung-uk Kim128 bit RC2 have the same NID. If the cipher does not have an object
243*e71b7053SJung-uk Kimidentifier or does not have ASN1 support this function will return
244*e71b7053SJung-uk KimB<NID_undef>.
245*e71b7053SJung-uk Kim
246*e71b7053SJung-uk KimEVP_CIPHER_CTX_cipher() returns the B<EVP_CIPHER> structure when passed
247*e71b7053SJung-uk Kiman B<EVP_CIPHER_CTX> structure.
248*e71b7053SJung-uk Kim
249*e71b7053SJung-uk KimEVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode:
250*e71b7053SJung-uk KimEVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE,
251*e71b7053SJung-uk KimEVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE,
252*e71b7053SJung-uk KimEVP_CIPH_WRAP_MODE or EVP_CIPH_OCB_MODE. If the cipher is a stream cipher then
253*e71b7053SJung-uk KimEVP_CIPH_STREAM_CIPHER is returned.
254*e71b7053SJung-uk Kim
255*e71b7053SJung-uk KimEVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based
256*e71b7053SJung-uk Kimon the passed cipher. This will typically include any parameters and an
257*e71b7053SJung-uk KimIV. The cipher IV (if any) must be set when this call is made. This call
258*e71b7053SJung-uk Kimshould be made before the cipher is actually "used" (before any
259*e71b7053SJung-uk KimEVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function
260*e71b7053SJung-uk Kimmay fail if the cipher does not have any ASN1 support.
261*e71b7053SJung-uk Kim
262*e71b7053SJung-uk KimEVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1
263*e71b7053SJung-uk KimAlgorithmIdentifier "parameter". The precise effect depends on the cipher
264*e71b7053SJung-uk KimIn the case of RC2, for example, it will set the IV and effective key length.
265*e71b7053SJung-uk KimThis function should be called after the base cipher type is set but before
266*e71b7053SJung-uk Kimthe key is set. For example EVP_CipherInit() will be called with the IV and
267*e71b7053SJung-uk Kimkey set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally
268*e71b7053SJung-uk KimEVP_CipherInit() again with all parameters except the key set to NULL. It is
269*e71b7053SJung-uk Kimpossible for this function to fail if the cipher does not have any ASN1 support
270*e71b7053SJung-uk Kimor the parameters cannot be set (for example the RC2 effective key length
271*e71b7053SJung-uk Kimis not supported.
272*e71b7053SJung-uk Kim
273*e71b7053SJung-uk KimEVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined
274*e71b7053SJung-uk Kimand set.
275*e71b7053SJung-uk Kim
276*e71b7053SJung-uk KimEVP_CIPHER_CTX_rand_key() generates a random key of the appropriate length
277*e71b7053SJung-uk Kimbased on the cipher context. The EVP_CIPHER can provide its own random key
278*e71b7053SJung-uk Kimgeneration routine to support keys of a specific form. B<Key> must point to a
279*e71b7053SJung-uk Kimbuffer at least as big as the value returned by EVP_CIPHER_CTX_key_length().
280*e71b7053SJung-uk Kim
281*e71b7053SJung-uk Kim=head1 RETURN VALUES
282*e71b7053SJung-uk Kim
283*e71b7053SJung-uk KimEVP_CIPHER_CTX_new() returns a pointer to a newly created
284*e71b7053SJung-uk KimB<EVP_CIPHER_CTX> for success and B<NULL> for failure.
285*e71b7053SJung-uk Kim
286*e71b7053SJung-uk KimEVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex()
287*e71b7053SJung-uk Kimreturn 1 for success and 0 for failure.
288*e71b7053SJung-uk Kim
289*e71b7053SJung-uk KimEVP_DecryptInit_ex() and EVP_DecryptUpdate() return 1 for success and 0 for failure.
290*e71b7053SJung-uk KimEVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success.
291*e71b7053SJung-uk Kim
292*e71b7053SJung-uk KimEVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for failure.
293*e71b7053SJung-uk KimEVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success.
294*e71b7053SJung-uk Kim
295*e71b7053SJung-uk KimEVP_CIPHER_CTX_reset() returns 1 for success and 0 for failure.
296*e71b7053SJung-uk Kim
297*e71b7053SJung-uk KimEVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
298*e71b7053SJung-uk Kimreturn an B<EVP_CIPHER> structure or NULL on error.
299*e71b7053SJung-uk Kim
300*e71b7053SJung-uk KimEVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID.
301*e71b7053SJung-uk Kim
302*e71b7053SJung-uk KimEVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block
303*e71b7053SJung-uk Kimsize.
304*e71b7053SJung-uk Kim
305*e71b7053SJung-uk KimEVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
306*e71b7053SJung-uk Kimlength.
307*e71b7053SJung-uk Kim
308*e71b7053SJung-uk KimEVP_CIPHER_CTX_set_padding() always returns 1.
309*e71b7053SJung-uk Kim
310*e71b7053SJung-uk KimEVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
311*e71b7053SJung-uk Kimlength or zero if the cipher does not use an IV.
312*e71b7053SJung-uk Kim
313*e71b7053SJung-uk KimEVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher's
314*e71b7053SJung-uk KimOBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER.
315*e71b7053SJung-uk Kim
316*e71b7053SJung-uk KimEVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure.
317*e71b7053SJung-uk Kim
318*e71b7053SJung-uk KimEVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return greater
319*e71b7053SJung-uk Kimthan zero for success and zero or a negative number on failure.
320*e71b7053SJung-uk Kim
321*e71b7053SJung-uk KimEVP_CIPHER_CTX_rand_key() returns 1 for success.
322*e71b7053SJung-uk Kim
323*e71b7053SJung-uk Kim=head1 CIPHER LISTING
324*e71b7053SJung-uk Kim
325*e71b7053SJung-uk KimAll algorithms have a fixed key length unless otherwise stated.
326*e71b7053SJung-uk Kim
327*e71b7053SJung-uk KimRefer to L<SEE ALSO> for the full list of ciphers available through the EVP
328*e71b7053SJung-uk Kiminterface.
329*e71b7053SJung-uk Kim
330*e71b7053SJung-uk Kim=over 4
331*e71b7053SJung-uk Kim
332*e71b7053SJung-uk Kim=item EVP_enc_null()
333*e71b7053SJung-uk Kim
334*e71b7053SJung-uk KimNull cipher: does nothing.
335*e71b7053SJung-uk Kim
336*e71b7053SJung-uk Kim=back
337*e71b7053SJung-uk Kim
338*e71b7053SJung-uk Kim=head1 AEAD Interface
339*e71b7053SJung-uk Kim
340*e71b7053SJung-uk KimThe EVP interface for Authenticated Encryption with Associated Data (AEAD)
341*e71b7053SJung-uk Kimmodes are subtly altered and several additional I<ctrl> operations are supported
342*e71b7053SJung-uk Kimdepending on the mode specified.
343*e71b7053SJung-uk Kim
344*e71b7053SJung-uk KimTo specify additional authenticated data (AAD), a call to EVP_CipherUpdate(),
345*e71b7053SJung-uk KimEVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output
346*e71b7053SJung-uk Kimparameter B<out> set to B<NULL>.
347*e71b7053SJung-uk Kim
348*e71b7053SJung-uk KimWhen decrypting, the return value of EVP_DecryptFinal() or EVP_CipherFinal()
349*e71b7053SJung-uk Kimindicates whether the operation was successful. If it does not indicate success,
350*e71b7053SJung-uk Kimthe authentication operation has failed and any output data B<MUST NOT> be used
351*e71b7053SJung-uk Kimas it is corrupted.
352*e71b7053SJung-uk Kim
353*e71b7053SJung-uk Kim=head2 GCM and OCB Modes
354*e71b7053SJung-uk Kim
355*e71b7053SJung-uk KimThe following I<ctrl>s are supported in GCM and OCB modes.
356*e71b7053SJung-uk Kim
357*e71b7053SJung-uk Kim=over 4
358*e71b7053SJung-uk Kim
359*e71b7053SJung-uk Kim=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)
360*e71b7053SJung-uk Kim
361*e71b7053SJung-uk KimSets the IV length. This call can only be made before specifying an IV. If
362*e71b7053SJung-uk Kimnot called a default IV length is used.
363*e71b7053SJung-uk Kim
364*e71b7053SJung-uk KimFor GCM AES and OCB AES the default is 12 (i.e. 96 bits). For OCB mode the
365*e71b7053SJung-uk Kimmaximum is 15.
366*e71b7053SJung-uk Kim
367*e71b7053SJung-uk Kim=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)
368*e71b7053SJung-uk Kim
369*e71b7053SJung-uk KimWrites C<taglen> bytes of the tag value to the buffer indicated by C<tag>.
370*e71b7053SJung-uk KimThis call can only be made when encrypting data and B<after> all data has been
371*e71b7053SJung-uk Kimprocessed (e.g. after an EVP_EncryptFinal() call).
372*e71b7053SJung-uk Kim
373*e71b7053SJung-uk KimFor OCB, C<taglen> must either be 16 or the value previously set via
374*e71b7053SJung-uk KimB<EVP_CTRL_AEAD_SET_TAG>.
375*e71b7053SJung-uk Kim
376*e71b7053SJung-uk Kim=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)
377*e71b7053SJung-uk Kim
378*e71b7053SJung-uk KimSets the expected tag to C<taglen> bytes from C<tag>.
379*e71b7053SJung-uk KimThe tag length can only be set before specifying an IV.
380*e71b7053SJung-uk KimC<taglen> must be between 1 and 16 inclusive.
381*e71b7053SJung-uk Kim
382*e71b7053SJung-uk KimFor GCM, this call is only valid when decrypting data.
383*e71b7053SJung-uk Kim
384*e71b7053SJung-uk KimFor OCB, this call is valid when decrypting data to set the expected tag,
385*e71b7053SJung-uk Kimand before encryption to set the desired tag length.
386*e71b7053SJung-uk Kim
387*e71b7053SJung-uk KimIn OCB mode, calling this before encryption with C<tag> set to C<NULL> sets the
388*e71b7053SJung-uk Kimtag length.  If this is not called prior to encryption, a default tag length is
389*e71b7053SJung-uk Kimused.
390*e71b7053SJung-uk Kim
391*e71b7053SJung-uk KimFor OCB AES, the default tag length is 16 (i.e. 128 bits).  It is also the
392*e71b7053SJung-uk Kimmaximum tag length for OCB.
393*e71b7053SJung-uk Kim
394*e71b7053SJung-uk Kim=back
395*e71b7053SJung-uk Kim
396*e71b7053SJung-uk Kim=head2 CCM Mode
397*e71b7053SJung-uk Kim
398*e71b7053SJung-uk KimThe EVP interface for CCM mode is similar to that of the GCM mode but with a
399*e71b7053SJung-uk Kimfew additional requirements and different I<ctrl> values.
400*e71b7053SJung-uk Kim
401*e71b7053SJung-uk KimFor CCM mode, the total plaintext or ciphertext length B<MUST> be passed to
402*e71b7053SJung-uk KimEVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output
403*e71b7053SJung-uk Kimand input parameters (B<in> and B<out>) set to B<NULL> and the length passed in
404*e71b7053SJung-uk Kimthe B<inl> parameter.
405*e71b7053SJung-uk Kim
406*e71b7053SJung-uk KimThe following I<ctrl>s are supported in CCM mode.
407*e71b7053SJung-uk Kim
408*e71b7053SJung-uk Kim=over 4
409*e71b7053SJung-uk Kim
410*e71b7053SJung-uk Kim=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)
411*e71b7053SJung-uk Kim
412*e71b7053SJung-uk KimThis call is made to set the expected B<CCM> tag value when decrypting or
413*e71b7053SJung-uk Kimthe length of the tag (with the C<tag> parameter set to NULL) when encrypting.
414*e71b7053SJung-uk KimThe tag length is often referred to as B<M>. If not set a default value is
415*e71b7053SJung-uk Kimused (12 for AES).
416*e71b7053SJung-uk Kim
417*e71b7053SJung-uk Kim=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL)
418*e71b7053SJung-uk Kim
419*e71b7053SJung-uk KimSets the CCM B<L> value. If not set a default is used (8 for AES).
420*e71b7053SJung-uk Kim
421*e71b7053SJung-uk Kim=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)
422*e71b7053SJung-uk Kim
423*e71b7053SJung-uk KimSets the CCM nonce (IV) length. This call can only be made before specifying an
424*e71b7053SJung-uk Kimnonce value. The nonce length is given by B<15 - L> so it is 7 by default for
425*e71b7053SJung-uk KimAES.
426*e71b7053SJung-uk Kim
427*e71b7053SJung-uk Kim=back
428*e71b7053SJung-uk Kim
429*e71b7053SJung-uk Kim=head2 ChaCha20-Poly1305
430*e71b7053SJung-uk Kim
431*e71b7053SJung-uk KimThe following I<ctrl>s are supported for the ChaCha20-Poly1305 AEAD algorithm.
432*e71b7053SJung-uk Kim
433*e71b7053SJung-uk Kim=over 4
434*e71b7053SJung-uk Kim
435*e71b7053SJung-uk Kim=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)
436*e71b7053SJung-uk Kim
437*e71b7053SJung-uk KimSets the nonce length. This call can only be made before specifying the nonce.
438*e71b7053SJung-uk KimIf not called a default nonce length of 12 (i.e. 96 bits) is used. The maximum
439*e71b7053SJung-uk Kimnonce length is 16 (B<CHACHA_CTR_SIZE>, i.e. 128-bits).
440*e71b7053SJung-uk Kim
441*e71b7053SJung-uk Kim=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)
442*e71b7053SJung-uk Kim
443*e71b7053SJung-uk KimWrites C<taglen> bytes of the tag value to the buffer indicated by C<tag>.
444*e71b7053SJung-uk KimThis call can only be made when encrypting data and B<after> all data has been
445*e71b7053SJung-uk Kimprocessed (e.g. after an EVP_EncryptFinal() call).
446*e71b7053SJung-uk Kim
447*e71b7053SJung-uk KimC<taglen> specified here must be 16 (B<POLY1305_BLOCK_SIZE>, i.e. 128-bits) or
448*e71b7053SJung-uk Kimless.
449*e71b7053SJung-uk Kim
450*e71b7053SJung-uk Kim=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)
451*e71b7053SJung-uk Kim
452*e71b7053SJung-uk KimSets the expected tag to C<taglen> bytes from C<tag>.
453*e71b7053SJung-uk KimThe tag length can only be set before specifying an IV.
454*e71b7053SJung-uk KimC<taglen> must be between 1 and 16 (B<POLY1305_BLOCK_SIZE>) inclusive.
455*e71b7053SJung-uk KimThis call is only valid when decrypting data.
456*e71b7053SJung-uk Kim
457*e71b7053SJung-uk Kim=back
458*e71b7053SJung-uk Kim
459*e71b7053SJung-uk Kim=head1 NOTES
460*e71b7053SJung-uk Kim
461*e71b7053SJung-uk KimWhere possible the B<EVP> interface to symmetric ciphers should be used in
462*e71b7053SJung-uk Kimpreference to the low level interfaces. This is because the code then becomes
463*e71b7053SJung-uk Kimtransparent to the cipher used and much more flexible. Additionally, the
464*e71b7053SJung-uk KimB<EVP> interface will ensure the use of platform specific cryptographic
465*e71b7053SJung-uk Kimacceleration such as AES-NI (the low level interfaces do not provide the
466*e71b7053SJung-uk Kimguarantee).
467*e71b7053SJung-uk Kim
468*e71b7053SJung-uk KimPKCS padding works by adding B<n> padding bytes of value B<n> to make the total
469*e71b7053SJung-uk Kimlength of the encrypted data a multiple of the block size. Padding is always
470*e71b7053SJung-uk Kimadded so if the data is already a multiple of the block size B<n> will equal
471*e71b7053SJung-uk Kimthe block size. For example if the block size is 8 and 11 bytes are to be
472*e71b7053SJung-uk Kimencrypted then 5 padding bytes of value 5 will be added.
473*e71b7053SJung-uk Kim
474*e71b7053SJung-uk KimWhen decrypting the final block is checked to see if it has the correct form.
475*e71b7053SJung-uk Kim
476*e71b7053SJung-uk KimAlthough the decryption operation can produce an error if padding is enabled,
477*e71b7053SJung-uk Kimit is not a strong test that the input data or key is correct. A random block
478*e71b7053SJung-uk Kimhas better than 1 in 256 chance of being of the correct format and problems with
479*e71b7053SJung-uk Kimthe input data earlier on will not produce a final decrypt error.
480*e71b7053SJung-uk Kim
481*e71b7053SJung-uk KimIf padding is disabled then the decryption operation will always succeed if
482*e71b7053SJung-uk Kimthe total amount of data decrypted is a multiple of the block size.
483*e71b7053SJung-uk Kim
484*e71b7053SJung-uk KimThe functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(),
485*e71b7053SJung-uk KimEVP_CipherInit() and EVP_CipherFinal() are obsolete but are retained for
486*e71b7053SJung-uk Kimcompatibility with existing code. New code should use EVP_EncryptInit_ex(),
487*e71b7053SJung-uk KimEVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(),
488*e71b7053SJung-uk KimEVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an
489*e71b7053SJung-uk Kimexisting context without allocating and freeing it up on each call.
490*e71b7053SJung-uk Kim
491*e71b7053SJung-uk KimEVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as macros.
492*e71b7053SJung-uk Kim
493*e71b7053SJung-uk Kim=head1 BUGS
494*e71b7053SJung-uk Kim
495*e71b7053SJung-uk KimB<EVP_MAX_KEY_LENGTH> and B<EVP_MAX_IV_LENGTH> only refer to the internal
496*e71b7053SJung-uk Kimciphers with default key lengths. If custom ciphers exceed these values the
497*e71b7053SJung-uk Kimresults are unpredictable. This is because it has become standard practice to
498*e71b7053SJung-uk Kimdefine a generic key as a fixed unsigned char array containing
499*e71b7053SJung-uk KimB<EVP_MAX_KEY_LENGTH> bytes.
500*e71b7053SJung-uk Kim
501*e71b7053SJung-uk KimThe ASN1 code is incomplete (and sometimes inaccurate) it has only been tested
502*e71b7053SJung-uk Kimfor certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode.
503*e71b7053SJung-uk Kim
504*e71b7053SJung-uk Kim=head1 EXAMPLES
505*e71b7053SJung-uk Kim
506*e71b7053SJung-uk KimEncrypt a string using IDEA:
507*e71b7053SJung-uk Kim
508*e71b7053SJung-uk Kim int do_crypt(char *outfile)
509*e71b7053SJung-uk Kim {
510*e71b7053SJung-uk Kim     unsigned char outbuf[1024];
511*e71b7053SJung-uk Kim     int outlen, tmplen;
512*e71b7053SJung-uk Kim     /*
513*e71b7053SJung-uk Kim      * Bogus key and IV: we'd normally set these from
514*e71b7053SJung-uk Kim      * another source.
515*e71b7053SJung-uk Kim      */
516*e71b7053SJung-uk Kim     unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
517*e71b7053SJung-uk Kim     unsigned char iv[] = {1,2,3,4,5,6,7,8};
518*e71b7053SJung-uk Kim     char intext[] = "Some Crypto Text";
519*e71b7053SJung-uk Kim     EVP_CIPHER_CTX *ctx;
520*e71b7053SJung-uk Kim     FILE *out;
521*e71b7053SJung-uk Kim
522*e71b7053SJung-uk Kim     ctx = EVP_CIPHER_CTX_new();
523*e71b7053SJung-uk Kim     EVP_EncryptInit_ex(ctx, EVP_idea_cbc(), NULL, key, iv);
524*e71b7053SJung-uk Kim
525*e71b7053SJung-uk Kim     if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) {
526*e71b7053SJung-uk Kim         /* Error */
527*e71b7053SJung-uk Kim         EVP_CIPHER_CTX_free(ctx);
528*e71b7053SJung-uk Kim         return 0;
529*e71b7053SJung-uk Kim     }
530*e71b7053SJung-uk Kim     /*
531*e71b7053SJung-uk Kim      * Buffer passed to EVP_EncryptFinal() must be after data just
532*e71b7053SJung-uk Kim      * encrypted to avoid overwriting it.
533*e71b7053SJung-uk Kim      */
534*e71b7053SJung-uk Kim     if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) {
535*e71b7053SJung-uk Kim         /* Error */
536*e71b7053SJung-uk Kim         EVP_CIPHER_CTX_free(ctx);
537*e71b7053SJung-uk Kim         return 0;
538*e71b7053SJung-uk Kim     }
539*e71b7053SJung-uk Kim     outlen += tmplen;
540*e71b7053SJung-uk Kim     EVP_CIPHER_CTX_free(ctx);
541*e71b7053SJung-uk Kim     /*
542*e71b7053SJung-uk Kim      * Need binary mode for fopen because encrypted data is
543*e71b7053SJung-uk Kim      * binary data. Also cannot use strlen() on it because
544*e71b7053SJung-uk Kim      * it won't be NUL terminated and may contain embedded
545*e71b7053SJung-uk Kim      * NULs.
546*e71b7053SJung-uk Kim      */
547*e71b7053SJung-uk Kim     out = fopen(outfile, "wb");
548*e71b7053SJung-uk Kim     if (out == NULL) {
549*e71b7053SJung-uk Kim         /* Error */
550*e71b7053SJung-uk Kim         return 0;
551*e71b7053SJung-uk Kim     }
552*e71b7053SJung-uk Kim     fwrite(outbuf, 1, outlen, out);
553*e71b7053SJung-uk Kim     fclose(out);
554*e71b7053SJung-uk Kim     return 1;
555*e71b7053SJung-uk Kim }
556*e71b7053SJung-uk Kim
557*e71b7053SJung-uk KimThe ciphertext from the above example can be decrypted using the B<openssl>
558*e71b7053SJung-uk Kimutility with the command line (shown on two lines for clarity):
559*e71b7053SJung-uk Kim
560*e71b7053SJung-uk Kim openssl idea -d \
561*e71b7053SJung-uk Kim     -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 <filename
562*e71b7053SJung-uk Kim
563*e71b7053SJung-uk KimGeneral encryption and decryption function example using FILE I/O and AES128
564*e71b7053SJung-uk Kimwith a 128-bit key:
565*e71b7053SJung-uk Kim
566*e71b7053SJung-uk Kim int do_crypt(FILE *in, FILE *out, int do_encrypt)
567*e71b7053SJung-uk Kim {
568*e71b7053SJung-uk Kim     /* Allow enough space in output buffer for additional block */
569*e71b7053SJung-uk Kim     unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
570*e71b7053SJung-uk Kim     int inlen, outlen;
571*e71b7053SJung-uk Kim     EVP_CIPHER_CTX *ctx;
572*e71b7053SJung-uk Kim     /*
573*e71b7053SJung-uk Kim      * Bogus key and IV: we'd normally set these from
574*e71b7053SJung-uk Kim      * another source.
575*e71b7053SJung-uk Kim      */
576*e71b7053SJung-uk Kim     unsigned char key[] = "0123456789abcdeF";
577*e71b7053SJung-uk Kim     unsigned char iv[] = "1234567887654321";
578*e71b7053SJung-uk Kim
579*e71b7053SJung-uk Kim     /* Don't set key or IV right away; we want to check lengths */
580*e71b7053SJung-uk Kim     ctx = EVP_CIPHER_CTX_new();
581*e71b7053SJung-uk Kim     EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL,
582*e71b7053SJung-uk Kim                       do_encrypt);
583*e71b7053SJung-uk Kim     OPENSSL_assert(EVP_CIPHER_CTX_key_length(ctx) == 16);
584*e71b7053SJung-uk Kim     OPENSSL_assert(EVP_CIPHER_CTX_iv_length(ctx) == 16);
585*e71b7053SJung-uk Kim
586*e71b7053SJung-uk Kim     /* Now we can set key and IV */
587*e71b7053SJung-uk Kim     EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt);
588*e71b7053SJung-uk Kim
589*e71b7053SJung-uk Kim     for (;;) {
590*e71b7053SJung-uk Kim         inlen = fread(inbuf, 1, 1024, in);
591*e71b7053SJung-uk Kim         if (inlen <= 0)
592*e71b7053SJung-uk Kim             break;
593*e71b7053SJung-uk Kim         if (!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, inlen)) {
594*e71b7053SJung-uk Kim             /* Error */
595*e71b7053SJung-uk Kim             EVP_CIPHER_CTX_free(ctx);
596*e71b7053SJung-uk Kim             return 0;
597*e71b7053SJung-uk Kim         }
598*e71b7053SJung-uk Kim         fwrite(outbuf, 1, outlen, out);
599*e71b7053SJung-uk Kim     }
600*e71b7053SJung-uk Kim     if (!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) {
601*e71b7053SJung-uk Kim         /* Error */
602*e71b7053SJung-uk Kim         EVP_CIPHER_CTX_free(ctx);
603*e71b7053SJung-uk Kim         return 0;
604*e71b7053SJung-uk Kim     }
605*e71b7053SJung-uk Kim     fwrite(outbuf, 1, outlen, out);
606*e71b7053SJung-uk Kim
607*e71b7053SJung-uk Kim     EVP_CIPHER_CTX_free(ctx);
608*e71b7053SJung-uk Kim     return 1;
609*e71b7053SJung-uk Kim }
610*e71b7053SJung-uk Kim
611*e71b7053SJung-uk Kim
612*e71b7053SJung-uk Kim=head1 SEE ALSO
613*e71b7053SJung-uk Kim
614*e71b7053SJung-uk KimL<evp(7)>
615*e71b7053SJung-uk Kim
616*e71b7053SJung-uk KimSupported ciphers are listed in:
617*e71b7053SJung-uk Kim
618*e71b7053SJung-uk KimL<EVP_aes(3)>,
619*e71b7053SJung-uk KimL<EVP_aria(3)>,
620*e71b7053SJung-uk KimL<EVP_bf(3)>,
621*e71b7053SJung-uk KimL<EVP_camellia(3)>,
622*e71b7053SJung-uk KimL<EVP_cast5(3)>,
623*e71b7053SJung-uk KimL<EVP_chacha20(3)>,
624*e71b7053SJung-uk KimL<EVP_des(3)>,
625*e71b7053SJung-uk KimL<EVP_desx(3)>,
626*e71b7053SJung-uk KimL<EVP_idea(3)>,
627*e71b7053SJung-uk KimL<EVP_rc2(3)>,
628*e71b7053SJung-uk KimL<EVP_rc4(3)>,
629*e71b7053SJung-uk KimL<EVP_rc5(3)>,
630*e71b7053SJung-uk KimL<EVP_seed(3)>,
631*e71b7053SJung-uk KimL<EVP_sm4(3)>
632*e71b7053SJung-uk Kim
633*e71b7053SJung-uk Kim=head1 HISTORY
634*e71b7053SJung-uk Kim
635*e71b7053SJung-uk KimSupport for OCB mode was added in OpenSSL 1.1.0
636*e71b7053SJung-uk Kim
637*e71b7053SJung-uk KimB<EVP_CIPHER_CTX> was made opaque in OpenSSL 1.1.0.  As a result,
638*e71b7053SJung-uk KimEVP_CIPHER_CTX_reset() appeared and EVP_CIPHER_CTX_cleanup()
639*e71b7053SJung-uk Kimdisappeared.  EVP_CIPHER_CTX_init() remains as an alias for
640*e71b7053SJung-uk KimEVP_CIPHER_CTX_reset().
641*e71b7053SJung-uk Kim
642*e71b7053SJung-uk Kim=head1 COPYRIGHT
643*e71b7053SJung-uk Kim
644*e71b7053SJung-uk KimCopyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
645*e71b7053SJung-uk Kim
646*e71b7053SJung-uk KimLicensed under the OpenSSL license (the "License").  You may not use
647*e71b7053SJung-uk Kimthis file except in compliance with the License.  You can obtain a copy
648*e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at
649*e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>.
650*e71b7053SJung-uk Kim
651*e71b7053SJung-uk Kim=cut
652