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