summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/EVP_MD_meth_new.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/lib/libcrypto/man/EVP_MD_meth_new.3352
1 files changed, 0 insertions, 352 deletions
diff --git a/src/lib/libcrypto/man/EVP_MD_meth_new.3 b/src/lib/libcrypto/man/EVP_MD_meth_new.3
deleted file mode 100644
index 8a80cca06e..0000000000
--- a/src/lib/libcrypto/man/EVP_MD_meth_new.3
+++ /dev/null
@@ -1,352 +0,0 @@
1.\" $OpenBSD: EVP_MD_meth_new.3,v 1.5 2023/09/12 16:26:30 schwarze Exp $
2.\" selective merge up to:
3.\" OpenSSL man3/EVP_MD_meth_new 0388d212 Dec 14 12:47:07 2018 -0800
4.\"
5.\" This file is a derived work.
6.\" The changes are covered by the following Copyright and license:
7.\"
8.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org>
9.\"
10.\" Permission to use, copy, modify, and distribute this software for any
11.\" purpose with or without fee is hereby granted, provided that the above
12.\" copyright notice and this permission notice appear in all copies.
13.\"
14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21.\"
22.\" The original file was written by Richard Levitte <levitte@openssl.org>
23.\" Copyright (c) 2015 The OpenSSL Project. All rights reserved.
24.\"
25.\" Redistribution and use in source and binary forms, with or without
26.\" modification, are permitted provided that the following conditions
27.\" are met:
28.\"
29.\" 1. Redistributions of source code must retain the above copyright
30.\" notice, this list of conditions and the following disclaimer.
31.\"
32.\" 2. Redistributions in binary form must reproduce the above copyright
33.\" notice, this list of conditions and the following disclaimer in
34.\" the documentation and/or other materials provided with the
35.\" distribution.
36.\"
37.\" 3. All advertising materials mentioning features or use of this
38.\" software must display the following acknowledgment:
39.\" "This product includes software developed by the OpenSSL Project
40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
41.\"
42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
43.\" endorse or promote products derived from this software without
44.\" prior written permission. For written permission, please contact
45.\" openssl-core@openssl.org.
46.\"
47.\" 5. Products derived from this software may not be called "OpenSSL"
48.\" nor may "OpenSSL" appear in their names without prior written
49.\" permission of the OpenSSL Project.
50.\"
51.\" 6. Redistributions of any form whatsoever must retain the following
52.\" acknowledgment:
53.\" "This product includes software developed by the OpenSSL Project
54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
55.\"
56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
67.\" OF THE POSSIBILITY OF SUCH DAMAGE.
68.\"
69.Dd $Mdocdate: September 12 2023 $
70.Dt EVP_MD_METH_NEW 3
71.Os
72.Sh NAME
73.Nm EVP_MD_meth_dup ,
74.Nm EVP_MD_meth_new ,
75.Nm EVP_MD_meth_free ,
76.Nm EVP_MD_meth_set_input_blocksize ,
77.Nm EVP_MD_meth_set_result_size ,
78.Nm EVP_MD_meth_set_app_datasize ,
79.Nm EVP_MD_meth_set_flags ,
80.Nm EVP_MD_meth_set_init ,
81.Nm EVP_MD_meth_set_update ,
82.Nm EVP_MD_meth_set_final ,
83.Nm EVP_MD_meth_set_copy ,
84.Nm EVP_MD_meth_set_cleanup ,
85.Nm EVP_MD_meth_set_ctrl
86.Nd Routines to build up EVP_MD methods
87.Sh SYNOPSIS
88.In openssl/evp.h
89.Ft EVP_MD *
90.Fo EVP_MD_meth_new
91.Fa "int md_type"
92.Fa "int pkey_type"
93.Fc
94.Ft void
95.Fo EVP_MD_meth_free
96.Fa "EVP_MD *md"
97.Fc
98.Ft EVP_MD *
99.Fo EVP_MD_meth_dup
100.Fa "const EVP_MD *md"
101.Fc
102.Ft int
103.Fo EVP_MD_meth_set_input_blocksize
104.Fa "EVP_MD *md"
105.Fa "int blocksize"
106.Fc
107.Ft int
108.Fo EVP_MD_meth_set_result_size
109.Fa "EVP_MD *md"
110.Fa "int resultsize"
111.Fc
112.Ft int
113.Fo EVP_MD_meth_set_app_datasize
114.Fa "EVP_MD *md"
115.Fa "int datasize"
116.Fc
117.Ft int
118.Fo EVP_MD_meth_set_flags
119.Fa "EVP_MD *md"
120.Fa "unsigned long flags"
121.Fc
122.Ft int
123.Fo EVP_MD_meth_set_init
124.Fa "EVP_MD *md"
125.Fa "int (*init)(EVP_MD_CTX *ctx)"
126.Fc
127.Ft int
128.Fo EVP_MD_meth_set_update
129.Fa "EVP_MD *md"
130.Fa "int (*update)(EVP_MD_CTX *ctx, const void *data, size_t count)"
131.Fc
132.Ft int
133.Fo EVP_MD_meth_set_final
134.Fa "EVP_MD *md"
135.Fa "int (*final)(EVP_MD_CTX *ctx, unsigned char *md)"
136.Fc
137.Ft int
138.Fo EVP_MD_meth_set_copy
139.Fa "EVP_MD *md"
140.Fa "int (*copy)(EVP_MD_CTX *to, const EVP_MD_CTX *from)"
141.Fc
142.Ft int
143.Fo EVP_MD_meth_set_cleanup
144.Fa "EVP_MD *md"
145.Fa "int (*cleanup)(EVP_MD_CTX *ctx)"
146.Fc
147.Ft int
148.Fo EVP_MD_meth_set_ctrl
149.Fa "EVP_MD *md"
150.Fa "int (*control)(EVP_MD_CTX *ctx, int command, int p1, void *p2)"
151.Fc
152.Sh DESCRIPTION
153The
154.Vt EVP_MD
155type is a structure for digest method implementation.
156It can also have associated public/private key signing and verifying
157routines.
158.Pp
159.Fn EVP_MD_meth_new
160creates a new
161.Vt EVP_MD
162structure.
163.Pp
164.Fn EVP_MD_meth_dup
165creates a copy of
166.Fa md .
167.Pp
168.Fn EVP_MD_meth_free
169destroys a
170.Vt EVP_MD
171structure.
172.Pp
173.Fn EVP_MD_meth_set_input_blocksize
174sets the internal input block size for the method
175.Fa md
176to
177.Fa blocksize
178bytes.
179.Pp
180.Fn EVP_MD_meth_set_result_size
181sets the size of the result that the digest method in
182.Fa md
183is expected to produce to
184.Fa resultsize
185bytes.
186.Pp
187The digest method may have its own private data, which OpenSSL will
188allocate for it.
189.Fn EVP_MD_meth_set_app_datasize
190should be used to set the size for it to
191.Fa datasize .
192.Pp
193.Fn EVP_MD_meth_set_flags
194sets the flags to describe optional behaviours in the particular
195.Fa md .
196Several flags can be or'd together.
197The available flags are:
198.Bl -tag -width Ds
199.It Dv EVP_MD_FLAG_DIGALGID_NULL
200When setting up a
201.Vt DigestAlgorithmIdentifier
202with
203.Xr X509_ALGOR_set_md 3 ,
204set the parameter type to
205.Dv V_ASN1_NULL
206and the parameter value to
207.Dv NULL .
208This is the default, which means that it takes effect for
209.Vt EVP_MD
210objects that do not have
211.Dv EVP_MD_FLAG_DIGALGID_ABSENT
212set.
213Use this for PKCS#1.
214.It Dv EVP_MD_FLAG_DIGALGID_ABSENT
215When setting up a
216.Vt DigestAlgorithmIdentifier
217with
218.Xr X509_ALGOR_set_md 3 ,
219set the parameter type to
220.Dv V_ASN1_UNDEF
221and the parameter value to
222.Dv NULL .
223This is used by the
224.Vt EVP_MD
225objects documented in the manual page
226.Xr EVP_sha3_224 3
227and by the objects returned from
228.Xr EVP_sha512 3 ,
229.Xr EVP_sha512_256 3 ,
230.Xr EVP_sha512_224 3 ,
231.Xr EVP_sha384 3 ,
232.Xr EVP_sha256 3 ,
233.Xr EVP_sha224 3 ,
234.Xr EVP_sha1 3 ,
235and
236.Xr EVP_sm3 3 .
237.It Dv EVP_MD_FLAG_DIGALGID_CUSTOM
238This flag is reserved for user-defined
239.Vt EVP_MD
240objects supporting custom
241.Vt DigestAlgorithmIdentifier
242handling via
243.Xr EVP_MD_CTX_ctrl 3 ,
244but actually, it is ignored by both LibreSSL and OpenSSL
245and such user-defined behaviour is not supported by the libraries.
246.It Dv EVP_MD_FLAG_FIPS
247Mark the digest method as suitable for FIPS mode.
248This flag is ignored by both LibreSSL and OpenSSL.
249.It Dv EVP_MD_FLAG_ONESHOT
250Intended to indicate that the digest method can only handle one block
251of input, but actually, this flag is ignored by both LibreSSL and OpenSSL.
252.El
253.Pp
254.Fn EVP_MD_meth_set_init
255sets the digest init function for
256.Fa md .
257The digest init function is called by
258.Xr EVP_Digest 3 ,
259.Xr EVP_DigestInit 3 ,
260.Xr EVP_DigestInit_ex 3 ,
261EVP_SignInit,
262.Xr EVP_SignInit_ex 3 ,
263.Xr EVP_VerifyInit 3
264and
265.Xr EVP_VerifyInit_ex 3 .
266.Pp
267.Fn EVP_MD_meth_set_update
268sets the digest update function for
269.Fa md .
270The digest update function is called by
271.Xr EVP_Digest 3 ,
272.Xr EVP_DigestUpdate 3
273and
274.Xr EVP_SignUpdate 3 .
275.Pp
276.Fn EVP_MD_meth_set_final
277sets the digest final function for
278.Fa md .
279The digest final function is called by
280.Xr EVP_Digest 3 ,
281.Xr EVP_DigestFinal 3 ,
282.Xr EVP_DigestFinal_ex 3 ,
283.Xr EVP_SignFinal 3
284and
285.Xr EVP_VerifyFinal 3 .
286.Pp
287.Fn EVP_MD_meth_set_copy
288sets the function for
289.Fa md
290to do extra computations after the method's private data structure has
291been copied from one
292.Vt EVP_MD_CTX
293object to another.
294If all that's needed is to copy the data, there is no need for this copy
295function.
296The copy function is passed two
297.Vt EVP_MD_CTX
298objects, the private data structure is then available with
299.Xr EVP_MD_CTX_md_data 3 .
300This copy function is called by
301.Xr EVP_MD_CTX_copy 3
302and
303.Xr EVP_MD_CTX_copy_ex 3 .
304.Pp
305.Fn EVP_MD_meth_set_cleanup
306sets the function for
307.Fa md
308to do extra cleanup before the method's private data structure is
309cleaned out and freed.
310The cleanup function is passed an
311.Vt EVP_MD_CTX
312object, the private data structure is then available with
313.Xr EVP_MD_CTX_md_data 3 .
314This cleanup function is called by
315.Xr EVP_MD_CTX_reset 3
316and
317.Xr EVP_MD_CTX_free 3 .
318.Pp
319.Fn EVP_MD_meth_set_ctrl
320sets the
321.Fa control
322function for
323.Fa md .
324The
325.Fa control
326function supplied by the application program has to return 1 to indicate
327success, 0 to indicate failure, or \-1 if the
328.Fa command
329is not supported for this digest method.
330See
331.Xr EVP_MD_CTX_ctrl 3
332for the available
333.Fa command
334arguments.
335.Sh RETURN VALUES
336.Fn EVP_MD_meth_new
337and
338.Fn EVP_MD_meth_dup
339return a pointer to a newly created
340.Vt EVP_MD ,
341or NULL on failure.
342All
343.Fn EVP_MD_meth_set_*
344functions return 1.
345.Sh SEE ALSO
346.Xr EVP_DigestInit 3 ,
347.Xr EVP_SignInit 3 ,
348.Xr EVP_VerifyInit 3
349.Sh HISTORY
350All these functions
351first appeared in OpenSSL 1.1.0 and have been available since
352.Ox 7.1 .