Import EVP_MD_meth_new.3 from OpenSSL 1.1.1 head

As usual, this has a lot of room for improvement, but it is better than
nothing at all. It leaves a dangling reference to EVP_MD_CTX_md_data(),
which I leave for schwarze to document. This is a terrible API and the
way it is used in the wild is terrifying.

1 files changed, 292 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/EVP_MD_meth_new.3 b/src/lib/libcrypto/man/EVP_MD_meth_new.3
new file mode 100644
index 0000000000..704c516107
--- /dev/null
+++ b/src/lib/libcrypto/man/EVP_MD_meth_new.3
@@ -0,0 +1,292 @@
+.\" $OpenBSD: EVP_MD_meth_new.3,v 1.1 2023/07/08 20:01:26 tb Exp $
+.\" selective merge up to:
+.\" OpenSSL man3/EVP_MD_meth_new 0388d212 Dec 14 12:47:07 2018 -0800
+.\"
+.\" This file was written by Richard Levitte <levitte@openssl.org>
+.\" Copyright (c) 2015 The OpenSSL Project.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: July 8 2023 $
+.Dt EVP_MD_METH_NEW 3
+.Os
+.Sh NAME
+.Nm EVP_MD_meth_dup ,
+.Nm EVP_MD_meth_new ,
+.Nm EVP_MD_meth_free ,
+.Nm EVP_MD_meth_set_input_blocksize ,
+.Nm EVP_MD_meth_set_result_size ,
+.Nm EVP_MD_meth_set_app_datasize ,
+.Nm EVP_MD_meth_set_flags ,
+.Nm EVP_MD_meth_set_init ,
+.Nm EVP_MD_meth_set_update ,
+.Nm EVP_MD_meth_set_final ,
+.Nm EVP_MD_meth_set_copy ,
+.Nm EVP_MD_meth_set_cleanup ,
+.Nm EVP_MD_meth_set_ctrl
+.Nd Routines to build up EVP_MD methods
+.Sh SYNOPSIS
+.In openssl/evp.h
+.Ft EVP_MD *
+.Fo EVP_MD_meth_new
+.Fa "int md_type"
+.Fa "int pkey_type"
+.Fc
+.Ft void
+.Fo EVP_MD_meth_free
+.Fa "EVP_MD *md"
+.Fc
+.Ft EVP_MD *
+.Fo EVP_MD_meth_dup
+.Fa "const EVP_MD *md"
+.Fc
+.Ft int
+.Fo EVP_MD_meth_set_input_blocksize
+.Fa "EVP_MD *md"
+.Fa "int blocksize"
+.Fc
+.Ft int
+.Fo EVP_MD_meth_set_result_size
+.Fa "EVP_MD *md"
+.Fa "int resultsize"
+.Fc
+.Ft int
+.Fo EVP_MD_meth_set_app_datasize
+.Fa "EVP_MD *md"
+.Fa "int datasize"
+.Fc
+.Ft int
+.Fo EVP_MD_meth_set_flags
+.Fa "EVP_MD *md"
+.Fa "unsigned long flags"
+.Fc
+.Ft int
+.Fo EVP_MD_meth_set_init
+.Fa "EVP_MD *md"
+.Fa "int (*init)(EVP_MD_CTX *ctx)"
+.Fc
+.Ft int
+.Fo EVP_MD_meth_set_update
+.Fa "EVP_MD *md"
+.Fa "int (*update)(EVP_MD_CTX *ctx, const void *data, size_t count)"
+.Fc
+.Ft int
+.Fo EVP_MD_meth_set_final
+.Fa "EVP_MD *md"
+.Fa "int (*final)(EVP_MD_CTX *ctx, unsigned char *md)"
+.Fc
+.Ft int
+.Fo EVP_MD_meth_set_copy
+.Fa "EVP_MD *md"
+.Fa "int (*copy)(EVP_MD_CTX *to, const EVP_MD_CTX *from)"
+.Fc
+.Ft int
+.Fo EVP_MD_meth_set_cleanup
+.Fa "EVP_MD *md"
+.Fa "int (*cleanup)(EVP_MD_CTX *ctx)"
+.Fc
+.Ft int
+.Fo EVP_MD_meth_set_ctrl
+.Fa "EVP_MD *md"
+.Fa "int (*ctrl)(EVP_MD_CTX *ctx, int cmd, int p1, void *p2)"
+.Fc
+.Sh DESCRIPTION
+The
+.Vt EVP_MD
+type is a structure for digest method implementation.
+It can also have associated public/private key signing and verifying
+routines.
+.Pp
+.Fn EVP_MD_meth_new
+creates a new
+.Vt EVP_MD
+structure.
+.Pp
+.Fn EVP_MD_meth_dup
+creates a copy of
+.Fa md .
+.Pp
+.Fn EVP_MD_meth_free
+destroys a
+.Vt EVP_MD
+structure.
+.Pp
+.Fn EVP_MD_meth_set_input_blocksize
+sets the internal input block size for the method
+.Fa md
+to
+.Fa blocksize
+bytes.
+.Pp
+.Fn EVP_MD_meth_set_result_size
+sets the size of the result that the digest method in
+.Fa md
+is expected to produce to
+.Fa resultsize
+bytes.
+.Pp
+The digest method may have its own private data, which OpenSSL will
+allocate for it.
+.Fn EVP_MD_meth_set_app_datasize
+should be used to set the size for it to
+.Fa datasize .
+.Pp
+.Fn EVP_MD_meth_set_flags
+sets the flags to describe optional behaviours in the particular
+.Fa md .
+Several flags can be or'd together.
+The available flags are:
+.Bl -tag -width Ds
+.It EVP_MD_FLAG_ONESHOT
+This digest method can only handle one block of input.
+.It EVP_MD_FLAG_DIGALGID_NULL
+When setting up a DigestAlgorithmIdentifier, this flag will have the
+parameter set to NULL by default.
+Use this for PKCS#1.
+.Em Note: if combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.
+.It EVP_MD_FLAG_DIGALGID_ABSENT
+When setting up a DigestAlgorithmIdentifier, this flag will have the
+parameter be left absent by default.
+.Em Note: if combined with EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.
+.It EVP_MD_FLAG_DIGALGID_CUSTOM
+Custom DigestAlgorithmIdentifier handling via ctrl, with
+.Sy EVP_MD_FLAG_DIGALGID_ABSENT
+as default.
+.Em Note: if combined with EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.
+Currently unused.
+.It EVP_MD_FLAG_FIPS
+This digest method is suitable for use in FIPS mode.
+Currently unused.
+.El
+.Pp
+.Fn EVP_MD_meth_set_init
+sets the digest init function for
+.Fa md .
+The digest init function is called by
+.Xr EVP_Digest 3 ,
+.Xr EVP_DigestInit 3 ,
+.Xr EVP_DigestInit_ex 3 ,
+EVP_SignInit,
+.Xr EVP_SignInit_ex 3 ,
+.Xr EVP_VerifyInit 3
+and
+.Xr EVP_VerifyInit_ex 3 .
+.Pp
+.Fn EVP_MD_meth_set_update
+sets the digest update function for
+.Fa md .
+The digest update function is called by
+.Xr EVP_Digest 3 ,
+.Xr EVP_DigestUpdate 3
+and
+.Xr EVP_SignUpdate 3 .
+.Pp
+.Fn EVP_MD_meth_set_final
+sets the digest final function for
+.Fa md .
+The digest final function is called by
+.Xr EVP_Digest 3 ,
+.Xr EVP_DigestFinal 3 ,
+.Xr EVP_DigestFinal_ex 3 ,
+.Xr EVP_SignFinal 3
+and
+.Xr EVP_VerifyFinal 3 .
+.Pp
+.Fn EVP_MD_meth_set_copy
+sets the function for
+.Fa md
+to do extra computations after the method's private data structure has
+been copied from one
+.Vt EVP_MD_CTX
+object to another.
+If all that's needed is to copy the data, there is no need for this copy
+function.
+The copy function is passed two
+.Vt EVP_MD_CTX
+objects, the private data structure is then available with
+.Xr EVP_MD_CTX_md_data 3 .
+This copy function is called by
+.Xr EVP_MD_CTX_copy 3
+and
+.Xr EVP_MD_CTX_copy_ex 3 .
+.Pp
+.Fn EVP_MD_meth_set_cleanup
+sets the function for
+.Fa md
+to do extra cleanup before the method's private data structure is
+cleaned out and freed.
+The cleanup function is passed an
+.Vt EVP_MD_CTX
+object, the private data structure is then available with
+.Xr EVP_MD_CTX_md_data 3 .
+This cleanup function is called by
+.Xr EVP_MD_CTX_reset 3
+and
+.Xr EVP_MD_CTX_free 3 .
+.Pp
+.Fn EVP_MD_meth_set_ctrl
+sets the control function for
+.Fa md .
+See
+.Xr EVP_MD_CTX_ctrl 3
+for the available controls.
+.Sh RETURN VALUES
+.Fn EVP_MD_meth_new
+and
+.Fn EVP_MD_meth_dup
+return a pointer to a newly created
+.Vt EVP_MD ,
+or NULL on failure.
+All
+.Fn EVP_MD_meth_set_*
+functions return 1.
+.Sh SEE ALSO
+.Xr EVP_DigestInit 3 ,
+.Xr EVP_SignInit 3 ,
+.Xr EVP_VerifyInit 3
+.Sh HISTORY
+All these functions
+first appeared in OpenSSL 1.1.0 and have been available since
+.Ox 7.0 .