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