From: tb Date: Sat, 8 Jul 2023 20:01:26 +0000 (+0000) Subject: Import EVP_MD_meth_new.3 from OpenSSL 1.1.1 head X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=ef7b131135f1069c37993b8a7bc5f231f085a18c;p=openbsd 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. --- diff --git a/lib/libcrypto/man/EVP_MD_meth_new.3 b/lib/libcrypto/man/EVP_MD_meth_new.3 new file mode 100644 index 00000000000..704c5161071 --- /dev/null +++ b/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 +.\" 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 .