summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authortb <>2023-03-16 15:05:23 +0000
committertb <>2023-03-16 15:05:23 +0000
commit8d510aab1bc83283d625dfcaeb03171f6389a95c (patch)
treec10d4cd3c543b98dcbd4b53da87fc80aa602c12b
parentf585206aaf511686270f4af4d348d979a0926dbb (diff)
downloadopenbsd-8d510aab1bc83283d625dfcaeb03171f6389a95c.tar.gz
openbsd-8d510aab1bc83283d625dfcaeb03171f6389a95c.tar.bz2
openbsd-8d510aab1bc83283d625dfcaeb03171f6389a95c.zip
Add EVP_CIPHER_meth_* documentation from OpenSSL 1.1
This is essentially the original text with a few tweaks and fixes by me, removing parts inapplicable to LibreSSL. There are dangling references to EVP_CIPHER_CTX_copy(3) and EVP_CIPHER_CTX_get_cipher_data(3). This all isn't great, but it's better than nothing. Probably good enough for these rarely used functions.
Diffstat
-rw-r--r--src/lib/libcrypto/man/EVP_CIPHER_meth_new.3335
1 files changed, 335 insertions, 0 deletions
diff --git a/src/lib/libcrypto/man/EVP_CIPHER_meth_new.3 b/src/lib/libcrypto/man/EVP_CIPHER_meth_new.3
new file mode 100644
index 0000000000..21555edfd3
--- /dev/null
+++ b/src/lib/libcrypto/man/EVP_CIPHER_meth_new.3
@@ -0,0 +1,335 @@
1.\" $OpenBSD: EVP_CIPHER_meth_new.3,v 1.1 2023/03/16 15:05:23 tb Exp $
2.\" selective merge up to: OpenSSL b0edda11 Mar 20 13:00:17 2018 +0000
3.\"
4.\" The original file was written by Richard Levitte <levitte@openssl.org>
5.\" Copyright (c) 2015 The OpenSSL Project.
6.\" All rights reserved.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\"
12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer.
14.\"
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\" notice, this list of conditions and the following disclaimer in
17.\" the documentation and/or other materials provided with the
18.\" distribution.
19.\"
20.\" 3. All advertising materials mentioning features or use of this
21.\" software must display the following acknowledgment:
22.\" "This product includes software developed by the OpenSSL Project
23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24.\"
25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26.\" endorse or promote products derived from this software without
27.\" prior written permission. For written permission, please contact
28.\" openssl-core@openssl.org.
29.\"
30.\" 5. Products derived from this software may not be called "OpenSSL"
31.\" nor may "OpenSSL" appear in their names without prior written
32.\" permission of the OpenSSL Project.
33.\"
34.\" 6. Redistributions of any form whatsoever must retain the following
35.\" acknowledgment:
36.\" "This product includes software developed by the OpenSSL Project
37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38.\"
39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50.\" OF THE POSSIBILITY OF SUCH DAMAGE.
51.\"
52.Dd $Mdocdate: March 16 2023 $
53.Dt EVP_CIPHER_METH_NEW 3
54.Os
55.Sh NAME
56.Nm EVP_CIPHER_meth_new ,
57.Nm EVP_CIPHER_meth_dup ,
58.Nm EVP_CIPHER_meth_free ,
59.Nm EVP_CIPHER_meth_set_iv_length ,
60.Nm EVP_CIPHER_meth_set_flags ,
61.Nm EVP_CIPHER_meth_set_impl_ctx_size ,
62.Nm EVP_CIPHER_meth_set_init ,
63.Nm EVP_CIPHER_meth_set_do_cipher ,
64.Nm EVP_CIPHER_meth_set_cleanup ,
65.Nm EVP_CIPHER_meth_set_set_asn1_params ,
66.Nm EVP_CIPHER_meth_set_get_asn1_params ,
67.Nm EVP_CIPHER_meth_set_ctrl
68.Nd Routines to build up EVP_CIPHER methods
69.Sh SYNOPSIS
70.In openssl/evp.h
71.Ft EVP_CIPHER *
72.Fo EVP_CIPHER_meth_new
73.Fa "int cipher_type"
74.Fa "int block_size"
75.Fa "int key_len"
76.Fc
77.Ft EVP_CIPHER *
78.Fo EVP_CIPHER_meth_dup
79.Fa "const EVP_CIPHER *cipher"
80.Fc
81.Ft void
82.Fo EVP_CIPHER_meth_free
83.Fa "EVP_CIPHER *cipher"
84.Fc
85.Ft int
86.Fo EVP_CIPHER_meth_set_iv_length
87.Fa "EVP_CIPHER *cipher"
88.Fa "int iv_len"
89.Fc
90.Ft int
91.Fo EVP_CIPHER_meth_set_flags
92.Fa "EVP_CIPHER *cipher"
93.Fa "unsigned long flags"
94.Fc
95.Ft int
96.Fo EVP_CIPHER_meth_set_impl_ctx_size
97.Fa "EVP_CIPHER *cipher"
98.Fa "int ctx_size"
99.Fc
100.Ft int
101.Fo EVP_CIPHER_meth_set_init
102.Fa "EVP_CIPHER *cipher"
103.Fa "int (*init)(EVP_CIPHER_CTX *ctx, const unsigned char *key,\
104 const unsigned char *iv, int enc)"
105.Fc
106.Ft int
107.Fo EVP_CIPHER_meth_set_do_cipher
108.Fa "EVP_CIPHER *cipher"
109.Fa "int (*do_cipher)(EVP_CIPHER_CTX *ctx, unsigned char *out,\
110 const unsigned char *in, size_t inl)"
111.Fc
112.Ft int
113.Fo EVP_CIPHER_meth_set_cleanup
114.Fa "EVP_CIPHER *cipher"
115.Fa "int (*cleanup)(EVP_CIPHER_CTX *)"
116.Fc
117.Ft int
118.Fo EVP_CIPHER_meth_set_set_asn1_params
119.Fa "EVP_CIPHER *cipher"
120.Fa "int (*set_asn1_parameters)(EVP_CIPHER_CTX *, ASN1_TYPE *)"
121.Fc
122.Ft int
123.Fo EVP_CIPHER_meth_set_get_asn1_params
124.Fa "EVP_CIPHER *cipher"
125.Fa "int (*get_asn1_parameters)(EVP_CIPHER_CTX *, ASN1_TYPE *)"
126.Fc
127.Ft int
128.Fo EVP_CIPHER_meth_set_ctrl
129.Fa "EVP_CIPHER *cipher"
130.Fa "int (*ctrl)(EVP_CIPHER_CTX *, int type, int arg, void *ptr)"
131.Fc
132.Sh DESCRIPTION
133The
134.Vt EVP_CIPHER
135type is a structure holding function pointers for
136a symmetric cipher implementation.
137.Pp
138.Fn EVP_CIPHER_meth_new
139allocates a new
140.Vt EVP_CIPHER
141structure.
142The cipher's NID (see
143.Xr EVP_CIPHER_nid 3 )
144is set to
145.Fa cipher_type ,
146the block size and key length are set to
147.Fa block_size
148and
149.Fa key_len ,
150respectively.
151.Pp
152.Fn EVP_CIPHER_meth_dup
153creates a copy of
154.Fa cipher .
155.Pp
156.Fn EVP_CIPHER_meth_free
157frees an
158.Vt EVP_CIPHER
159structure.
160.Pp
161.Fn EVP_CIPHER_meth_set_iv_length
162sets the length of the initialization vector.
163This is only needed when the implemented cipher mode requires it.
164.Pp
165.Fn EVP_CIPHER_meth_set_flags
166overwrites the flags to describe optional behaviours in
167.Fa cipher
168with
169.Fa flags .
170At most one of the following cipher modes can be set:
171.Dv EVP_CIPH_STREAM_CIPHER ,
172.Dv EVP_CIPH_ECB_MODE ,
173.Dv EVP_CIPH_CBC_MODE ,
174.Dv EVP_CIPH_CFB_MODE ,
175.Dv EVP_CIPH_OFB_MODE ,
176.Dv EVP_CIPH_CTR_MODE ,
177.Dv EVP_CIPH_GCM_MODE ,
178.Dv EVP_CIPH_CCM_MODE ,
179.Dv EVP_CIPH_XTS_MODE ,
180and
181.Dv EVP_CIPH_WRAP_MODE .
182The available flags are:
183.Bl -tag -width Ds
184.It EVP_CIPH_VARIABLE_LENGTH
185This cipher is of variable length.
186.It EVP_CIPH_CUSTOM_IV
187Storing and initialising the IV is left entirely to the implementation.
188.It EVP_CIPH_ALWAYS_CALL_INIT
189Set this if the implementation's
190.Fn init
191function should be called even if
192.Fa key
193is
194.Dv NULL .
195.It EVP_CIPH_CTRL_INIT
196Set this to have the implementation's
197.Fn ctrl
198function called with command code
199.Dv EVP_CTRL_INIT
200early in its setup.
201.It EVP_CIPH_CUSTOM_KEY_LENGTH
202Checking and setting the key length after creating the
203.Vt EVP_CIPHER
204is left to the implementation.
205Whenever someone uses
206.Xr EVP_CIPHER_CTX_set_key_length 3
207on a
208.Vt EVP_CIPHER
209with this flag set, the implementation's
210.Fn ctrl
211function will be called with the control code
212.Dv EVP_CTRL_SET_KEY_LENGTH
213and the key length in
214.Fa arg .
215.It EVP_CIPH_NO_PADDING
216Don't use standard block padding.
217.It EVP_CIPH_RAND_KEY
218Making a key with random content is left to the implementation.
219This is done by calling the implementation's
220.Fn ctrl
221function with the control code
222.Dv EVP_CTRL_RAND_KEY
223and the pointer to the key memory storage in
224.Fa ptr .
225.It EVP_CIPH_CUSTOM_COPY
226Set this to have the implementation's
227.Fn ctrl
228function called with command code
229.Dv EVP_CTRL_COPY
230at the end of
231.Xr EVP_CIPHER_CTX_copy 3 .
232The intended use is for further things to deal with after the
233implementation specific data block has been copied.
234The destination
235.Vt EVP_CIPHER_CTX
236object is passed to the control with the
237.Fa ptr
238parameter.
239The implementation-specific data block is reached with
240.Xr EVP_CIPHER_CTX_get_cipher_data 3 .
241.It EVP_CIPH_FLAG_DEFAULT_ASN1
242Use the default EVP routines to pass IV to and from ASN.1.
243.It EVP_CIPH_FLAG_LENGTH_BITS
244Signals that the length of the input buffer for encryption / decryption
245is to be understood as the number of bits instead of bytes for this
246implementation.
247This is only useful for CFB1 ciphers.
248.It EVP_CIPH_FLAG_CUSTOM_CIPHER
249This indicates that the implementation takes care of everything,
250including padding, buffering and finalization.
251The EVP routines will simply give them control and do nothing more.
252.It EVP_CIPH_FLAG_AEAD_CIPHER
253This indicates that this is an AEAD cipher implementation.
254.El
255.Pp
256.Fn EVP_CIPHER_meth_set_impl_ctx_size
257sets the size of the EVP_CIPHER's implementation context so that it can
258be automatically allocated.
259.Pp
260.Fn EVP_CIPHER_meth_set_init
261sets the cipher init function for
262.Fa cipher .
263The cipher init function is called by
264.Xr EVP_CipherInit 3 ,
265.Xr EVP_CipherInit_ex 3 ,
266.Xr EVP_EncryptInit 3 ,
267.Xr EVP_EncryptInit_ex 3 ,
268.Xr EVP_DecryptInit 3 ,
269.Xr EVP_DecryptInit_ex 3 .
270.Pp
271.Fn EVP_CIPHER_meth_set_do_cipher
272sets the cipher function for
273.Fa cipher .
274The cipher function is called by
275.Xr EVP_CipherUpdate 3 ,
276.Xr EVP_EncryptUpdate 3 ,
277.Xr EVP_DecryptUpdate 3 ,
278.Xr EVP_CipherFinal 3 ,
279.Xr EVP_EncryptFinal 3 ,
280.Xr EVP_EncryptFinal_ex 3 ,
281.Xr EVP_DecryptFinal 3
282and
283.Xr EVP_DecryptFinal_ex 3 .
284.Pp
285.Fn EVP_CIPHER_meth_set_cleanup
286sets the function for
287.Fa cipher
288to do extra cleanup before the method's private data structure is
289cleaned out and freed.
290Note that the cleanup function is passed a
291.Sy EVP_CIPHER_CTX * ,
292the private data structure is then available with
293.Xr EVP_CIPHER_CTX_get_cipher_data 3 .
294This cleanup function is called by
295.Xr EVP_CIPHER_CTX_reset 3
296and
297.Xr EVP_CIPHER_CTX_free 3 .
298.Pp
299.Fn EVP_CIPHER_meth_set_set_asn1_params
300sets the function for
301.Fa cipher
302to set the AlgorithmIdentifier "parameter" based on the passed cipher.
303This function is called by
304.Xr EVP_CIPHER_param_to_asn1 3 .
305.Fn EVP_CIPHER_meth_set_get_asn1_params
306sets the function for
307.Fa cipher
308that sets the cipher parameters based on an ASN.1 AlgorithmIdentifier
309"parameter".
310Both these functions are needed when there is a need for custom data
311(more or other than the cipher IV). They are called by
312.Xr EVP_CIPHER_param_to_asn1 3
313and
314.Xr EVP_CIPHER_asn1_to_param 3
315respectively if defined.
316.Pp
317.Fn EVP_CIPHER_meth_set_ctrl
318sets the control function for
319.Fa cipher .
320.Sh RETURN VALUES
321.Fn EVP_CIPHER_meth_new
322and
323.Fn EVP_CIPHER_meth_dup
324return a pointer to a newly created
325.Vt EVP_CIPHER ,
326or NULL on failure.
327.Pp
328All
329.Fn EVP_CIPHER_meth_set_*
330functions return 1.
331.Sh SEE ALSO
332.Xr EVP_EncryptInit 3
333.Sh HISTORY
334These functions first appeared in OpenSSL 1.1.0 and have been available since
335.Ox 7.3 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-22 03:45:18 +0000