]>
Commit | Line | Data |
---|---|---|
05fdb8d3 RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_CIPHER_meth_new, EVP_CIPHER_meth_dup, EVP_CIPHER_meth_free, | |
6 | EVP_CIPHER_meth_set_iv_length, EVP_CIPHER_meth_set_flags, | |
7 | EVP_CIPHER_meth_set_impl_ctx_size, EVP_CIPHER_meth_set_init, | |
8 | EVP_CIPHER_meth_set_do_cipher, EVP_CIPHER_meth_set_cleanup, | |
9 | EVP_CIPHER_meth_set_set_asn1_params, EVP_CIPHER_meth_set_get_asn1_params, | |
10 | EVP_CIPHER_meth_set_ctrl, EVP_CIPHER_meth_get_init, | |
11 | EVP_CIPHER_meth_get_do_cipher, EVP_CIPHER_meth_get_cleanup, | |
12 | EVP_CIPHER_meth_get_set_asn1_params, EVP_CIPHER_meth_get_get_asn1_params, | |
550f974a | 13 | EVP_CIPHER_meth_get_ctrl |
0da1d43a | 14 | - Routines to build up EVP_CIPHER methods |
05fdb8d3 RL |
15 | |
16 | =head1 SYNOPSIS | |
17 | ||
18 | #include <openssl/evp.h> | |
19 | ||
20 | EVP_CIPHER *EVP_CIPHER_meth_new(int cipher_type, int block_size, int key_len); | |
21 | EVP_CIPHER *EVP_CIPHER_meth_dup(const EVP_CIPHER *cipher); | |
22 | void EVP_CIPHER_meth_free(EVP_CIPHER *cipher); | |
1bc74519 | 23 | |
05fdb8d3 RL |
24 | int EVP_CIPHER_meth_set_iv_length(EVP_CIPHER *cipher, int iv_len); |
25 | int EVP_CIPHER_meth_set_flags(EVP_CIPHER *cipher, unsigned long flags); | |
26 | int EVP_CIPHER_meth_set_impl_ctx_size(EVP_CIPHER *cipher, int ctx_size); | |
27 | int EVP_CIPHER_meth_set_init(EVP_CIPHER *cipher, | |
e9b77246 BB |
28 | int (*init)(EVP_CIPHER_CTX *ctx, |
29 | const unsigned char *key, | |
30 | const unsigned char *iv, | |
31 | int enc)); | |
05fdb8d3 | 32 | int EVP_CIPHER_meth_set_do_cipher(EVP_CIPHER *cipher, |
e9b77246 BB |
33 | int (*do_cipher)(EVP_CIPHER_CTX *ctx, |
34 | unsigned char *out, | |
35 | const unsigned char *in, | |
36 | size_t inl)); | |
05fdb8d3 | 37 | int EVP_CIPHER_meth_set_cleanup(EVP_CIPHER *cipher, |
e9b77246 | 38 | int (*cleanup)(EVP_CIPHER_CTX *)); |
05fdb8d3 | 39 | int EVP_CIPHER_meth_set_set_asn1_params(EVP_CIPHER *cipher, |
e9b77246 BB |
40 | int (*set_asn1_parameters)(EVP_CIPHER_CTX *, |
41 | ASN1_TYPE *)); | |
05fdb8d3 | 42 | int EVP_CIPHER_meth_set_get_asn1_params(EVP_CIPHER *cipher, |
e9b77246 BB |
43 | int (*get_asn1_parameters)(EVP_CIPHER_CTX *, |
44 | ASN1_TYPE *)); | |
05fdb8d3 | 45 | int EVP_CIPHER_meth_set_ctrl(EVP_CIPHER *cipher, |
e9b77246 BB |
46 | int (*ctrl)(EVP_CIPHER_CTX *, int type, |
47 | int arg, void *ptr)); | |
1bc74519 | 48 | |
05fdb8d3 RL |
49 | int (*EVP_CIPHER_meth_get_init(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx, |
50 | const unsigned char *key, | |
51 | const unsigned char *iv, | |
52 | int enc); | |
53 | int (*EVP_CIPHER_meth_get_do_cipher(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx, | |
54 | unsigned char *out, | |
55 | const unsigned char *in, | |
56 | size_t inl); | |
57 | int (*EVP_CIPHER_meth_get_cleanup(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *); | |
58 | int (*EVP_CIPHER_meth_get_set_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, | |
59 | ASN1_TYPE *); | |
60 | int (*EVP_CIPHER_meth_get_get_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, | |
e9b77246 | 61 | ASN1_TYPE *); |
05fdb8d3 RL |
62 | int (*EVP_CIPHER_meth_get_ctrl(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, |
63 | int type, int arg, | |
64 | void *ptr); | |
65 | ||
66 | =head1 DESCRIPTION | |
67 | ||
68 | The B<EVP_CIPHER> type is a structure for symmetric cipher method | |
69 | implementation. | |
70 | ||
71 | EVP_CIPHER_meth_new() creates a new B<EVP_CIPHER> structure. | |
72 | ||
73 | EVP_CIPHER_meth_dup() creates a copy of B<cipher>. | |
74 | ||
75 | EVP_CIPHER_meth_free() destroys a B<EVP_CIPHER> structure. | |
76 | ||
b3f9064c | 77 | EVP_CIPHER_meth_set_iv_length() sets the length of the IV. |
05fdb8d3 RL |
78 | This is only needed when the implemented cipher mode requires it. |
79 | ||
80 | EVP_CIPHER_meth_set_flags() sets the flags to describe optional | |
81 | behaviours in the particular B<cipher>. | |
82 | With the exception of cipher modes, of which only one may be present, | |
83 | several flags can be or'd together. | |
84 | The available flags are: | |
85 | ||
e1271ac2 | 86 | =over 4 |
05fdb8d3 | 87 | |
1bc74519 RS |
88 | =item EVP_CIPH_STREAM_CIPHER, EVP_CIPH_ECB_MODE EVP_CIPH_CBC_MODE, |
89 | EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, | |
90 | EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE, EVP_CIPH_WRAP_MODE, | |
b1ceb439 | 91 | EVP_CIPH_OCB_MODE, EVP_CIPH_SIV_MODE |
05fdb8d3 | 92 | |
1bc74519 | 93 | The cipher mode. |
05fdb8d3 RL |
94 | |
95 | =item EVP_CIPH_VARIABLE_LENGTH | |
96 | ||
97 | This cipher is of variable length. | |
98 | ||
99 | =item EVP_CIPH_CUSTOM_IV | |
100 | ||
101 | Storing and initialising the IV is left entirely to the | |
102 | implementation. | |
103 | ||
104 | =item EVP_CIPH_ALWAYS_CALL_INIT | |
105 | ||
106 | Set this if the implementation's init() function should be called even | |
107 | if B<key> is B<NULL>. | |
108 | ||
109 | =item EVP_CIPH_CTRL_INIT | |
110 | ||
111 | Set this to have the implementation's ctrl() function called with | |
112 | command code B<EVP_CTRL_INIT> early in its setup. | |
113 | ||
114 | =item EVP_CIPH_CUSTOM_KEY_LENGTH | |
115 | ||
116 | Checking and setting the key length after creating the B<EVP_CIPHER> | |
117 | is left to the implementation. | |
118 | Whenever someone uses EVP_CIPHER_CTX_set_key_length() on a | |
119 | B<EVP_CIPHER> with this flag set, the implementation's ctrl() function | |
120 | will be called with the control code B<EVP_CTRL_SET_KEY_LENGTH> and | |
121 | the key length in B<arg>. | |
122 | ||
123 | =item EVP_CIPH_NO_PADDING | |
124 | ||
125 | Don't use standard block padding. | |
126 | ||
127 | =item EVP_CIPH_RAND_KEY | |
128 | ||
129 | Making a key with random content is left to the implementation. | |
130 | This is done by calling the implementation's ctrl() function with the | |
131 | control code B<EVP_CTRL_RAND_KEY> and the pointer to the key memory | |
132 | storage in B<ptr>. | |
133 | ||
134 | =item EVP_CIPH_CUSTOM_COPY | |
135 | ||
136 | Set this to have the implementation's ctrl() function called with | |
137 | command code B<EVP_CTRL_COPY> at the end of EVP_CIPHER_CTX_copy(). | |
138 | The intended use is for further things to deal with after the | |
139 | implementation specific data block has been copied. | |
140 | The destination B<EVP_CIPHER_CTX> is passed to the control with the | |
141 | B<ptr> parameter. | |
142 | The implementation specific data block is reached with | |
44ab2dfd | 143 | EVP_CIPHER_CTX_get_cipher_data(). |
05fdb8d3 RL |
144 | |
145 | =item EVP_CIPH_FLAG_DEFAULT_ASN1 | |
146 | ||
147 | Use the default EVP routines to pass IV to and from ASN.1. | |
148 | ||
149 | =item EVP_CIPH_FLAG_LENGTH_BITS | |
150 | ||
151 | Signals that the length of the input buffer for encryption / | |
a970b14f | 152 | decryption is to be understood as the number of bits instead of |
05fdb8d3 RL |
153 | bytes for this implementation. |
154 | This is only useful for CFB1 ciphers. | |
155 | ||
156 | =begin comment | |
157 | The FIPS flags seem to be unused, so I'm hiding them until I get an | |
158 | explanation or they get removed. /RL | |
159 | ||
160 | =item EVP_CIPH_FLAG_FIPS | |
161 | ||
162 | =item EVP_CIPH_FLAG_NON_FIPS_ALLOW | |
163 | ||
164 | =end comment | |
165 | ||
166 | =item EVP_CIPH_FLAG_CUSTOM_CIPHER | |
167 | ||
168 | This indicates that the implementation takes care of everything, | |
169 | including padding, buffering and finalization. | |
170 | The EVP routines will simply give them control and do nothing more. | |
171 | ||
172 | =item EVP_CIPH_FLAG_AEAD_CIPHER | |
173 | ||
b9b6a7e5 | 174 | This indicates that this is an AEAD cipher implementation. |
05fdb8d3 RL |
175 | |
176 | =item EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK | |
177 | ||
1bc74519 RS |
178 | Allow interleaving of crypto blocks, a particular optimization only applicable |
179 | to certain TLS ciphers. | |
05fdb8d3 RL |
180 | |
181 | =back | |
182 | ||
98ee7543 MC |
183 | EVP_CIPHER_meth_set_impl_ctx_size() sets the size of the EVP_CIPHER's |
184 | implementation context so that it can be automatically allocated. | |
185 | ||
05fdb8d3 RL |
186 | EVP_CIPHER_meth_set_init() sets the cipher init function for |
187 | B<cipher>. | |
188 | The cipher init function is called by EVP_CipherInit(), | |
189 | EVP_CipherInit_ex(), EVP_EncryptInit(), EVP_EncryptInit_ex(), | |
190 | EVP_DecryptInit(), EVP_DecryptInit_ex(). | |
191 | ||
192 | EVP_CIPHER_meth_set_do_cipher() sets the cipher function for | |
193 | B<cipher>. | |
194 | The cipher function is called by EVP_CipherUpdate(), | |
195 | EVP_EncryptUpdate(), EVP_DecryptUpdate(), EVP_CipherFinal(), | |
196 | EVP_EncryptFinal(), EVP_EncryptFinal_ex(), EVP_DecryptFinal() and | |
197 | EVP_DecryptFinal_ex(). | |
198 | ||
199 | EVP_CIPHER_meth_set_cleanup() sets the function for B<cipher> to do | |
9d22666e | 200 | extra cleanup before the method's private data structure is cleaned |
05fdb8d3 RL |
201 | out and freed. |
202 | Note that the cleanup function is passed a B<EVP_CIPHER_CTX *>, the | |
203 | private data structure is then available with | |
44ab2dfd | 204 | EVP_CIPHER_CTX_get_cipher_data(). |
05fdb8d3 RL |
205 | This cleanup function is called by EVP_CIPHER_CTX_reset() and |
206 | EVP_CIPHER_CTX_free(). | |
207 | ||
51e47d5f RL |
208 | EVP_CIPHER_meth_set_set_asn1_params() sets the function for B<cipher> |
209 | to set the AlgorithmIdentifier "parameter" based on the passed cipher. | |
210 | This function is called by EVP_CIPHER_param_to_asn1(). | |
211 | EVP_CIPHER_meth_set_get_asn1_params() sets the function for B<cipher> | |
212 | that sets the cipher parameters based on an ASN.1 AlgorithmIdentifier | |
213 | "parameter". | |
214 | Both these functions are needed when there is a need for custom data | |
215 | (more or other than the cipher IV). | |
216 | They are called by EVP_CIPHER_param_to_asn1() and | |
217 | EVP_CIPHER_asn1_to_param() respectively if defined. | |
218 | ||
05fdb8d3 RL |
219 | EVP_CIPHER_meth_set_ctrl() sets the control function for B<cipher>. |
220 | ||
51e47d5f RL |
221 | EVP_CIPHER_meth_get_init(), EVP_CIPHER_meth_get_do_cipher(), |
222 | EVP_CIPHER_meth_get_cleanup(), EVP_CIPHER_meth_get_set_asn1_params(), | |
223 | EVP_CIPHER_meth_get_get_asn1_params() and EVP_CIPHER_meth_get_ctrl() | |
224 | are all used to retrieve the method data given with the | |
225 | EVP_CIPHER_meth_set_*() functions above. | |
226 | ||
1bc74519 | 227 | =head1 RETURN VALUES |
05fdb8d3 | 228 | |
51e47d5f RL |
229 | EVP_CIPHER_meth_new() and EVP_CIPHER_meth_dup() return a pointer to a |
230 | newly created B<EVP_CIPHER>, or NULL on failure. | |
231 | All EVP_CIPHER_meth_set_*() functions return 1. | |
232 | All EVP_CIPHER_meth_get_*() functions return pointers to their | |
233 | respective B<cipher> function. | |
05fdb8d3 RL |
234 | |
235 | =head1 SEE ALSO | |
236 | ||
237 | L<EVP_EncryptInit> | |
238 | ||
239 | =head1 HISTORY | |
240 | ||
e90fc053 | 241 | The functions described here were added in OpenSSL 1.1.0. |
550f974a RL |
242 | The B<EVP_CIPHER> structure created with these functions became reference |
243 | counted in OpenSSL 3.0. | |
05fdb8d3 | 244 | |
e2f92610 RS |
245 | =head1 COPYRIGHT |
246 | ||
b0edda11 | 247 | Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 248 | |
4746f25a | 249 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
250 | this file except in compliance with the License. You can obtain a copy |
251 | in the file LICENSE in the source distribution or at | |
252 | L<https://www.openssl.org/source/license.html>. | |
253 | ||
254 | =cut |