From 94cbdd02134df6ff030490f83bc50ecced563084 Mon Sep 17 00:00:00 2001 From: schwarze Date: Fri, 11 Aug 2023 18:08:43 +0000 Subject: [PATCH] Merge various improvements from the OpenSSL 1.1 branch, which is still under a free license. * document EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags * document EVP_MD_flags, EVP_MD_CTX_md_data * document EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx * correct arg type of EVP_MD_CTX_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type * more information about EVP_MD_CTX_ctrl * add missing and correct one variable type below EXAMPLES * two orthographic improvements with a few wording tweaks by me --- lib/libcrypto/man/EVP_DigestInit.3 | 161 ++++++++++++++++++++++++++--- 1 file changed, 148 insertions(+), 13 deletions(-) diff --git a/lib/libcrypto/man/EVP_DigestInit.3 b/lib/libcrypto/man/EVP_DigestInit.3 index ba9d6a04810..08b64b59b24 100644 --- a/lib/libcrypto/man/EVP_DigestInit.3 +++ b/lib/libcrypto/man/EVP_DigestInit.3 @@ -1,6 +1,6 @@ -.\" $OpenBSD: EVP_DigestInit.3,v 1.25 2023/04/23 18:24:01 job Exp $ +.\" $OpenBSD: EVP_DigestInit.3,v 1.26 2023/08/11 18:08:43 schwarze Exp $ .\" full merge up to: OpenSSL 7f572e95 Dec 2 13:57:04 2015 +0000 -.\" selective merge up to: OpenSSL a95d7574 Jul 2 12:16:38 2017 -0400 +.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 .\" .\" This file is a derived work. .\" The changes are covered by the following Copyright and license: @@ -19,9 +19,11 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.\" The original file was written by Dr. Stephen Henson -.\" and Richard Levitte . -.\" Copyright (c) 2000-2004, 2009, 2012-2016 The OpenSSL Project. +.\" The original file was written by Dr. Stephen Henson , +.\" Richard Levitte , +.\" Paul Yang , and +.\" Antoine Salon . +.\" Copyright (c) 2000-2004, 2009, 2012-2016, 2018, 2019 The OpenSSL Project. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -68,7 +70,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: April 23 2023 $ +.Dd $Mdocdate: August 11 2023 $ .Dt EVP_DIGESTINIT 3 .Os .Sh NAME @@ -80,6 +82,9 @@ .Nm EVP_MD_CTX_cleanup , .Nm EVP_MD_CTX_destroy , .Nm EVP_MD_CTX_ctrl , +.Nm EVP_MD_CTX_set_flags , +.Nm EVP_MD_CTX_clear_flags , +.Nm EVP_MD_CTX_test_flags , .Nm EVP_DigestInit_ex , .Nm EVP_DigestUpdate , .Nm EVP_DigestFinal_ex , @@ -93,10 +98,14 @@ .Nm EVP_MD_pkey_type , .Nm EVP_MD_size , .Nm EVP_MD_block_size , +.Nm EVP_MD_flags , .Nm EVP_MD_CTX_md , .Nm EVP_MD_CTX_size , .Nm EVP_MD_CTX_block_size , .Nm EVP_MD_CTX_type , +.Nm EVP_MD_CTX_md_data , +.Nm EVP_MD_CTX_pkey_ctx , +.Nm EVP_MD_CTX_set_pkey_ctx , .Nm EVP_md_null , .Nm EVP_md5 , .Nm EVP_md5_sha1 , @@ -145,6 +154,21 @@ .Fa "int p1" .Fa "void* p2" .Fc +.Ft void +.Fo EVP_MD_CTX_set_flags +.Fa "EVP_MD_CTX *ctx" +.Fa "int flags" +.Fc +.Ft void +.Fo EVP_MD_CTX_clear_flags +.Fa "EVP_MD_CTX *ctx" +.Fa "int flags" +.Fc +.Ft int +.Fo EVP_MD_CTX_test_flags +.Fa "const EVP_MD_CTX *ctx" +.Fa "int flags" +.Fc .Ft int .Fo EVP_DigestInit_ex .Fa "EVP_MD_CTX *ctx" @@ -210,21 +234,38 @@ .Fo EVP_MD_block_size .Fa "const EVP_MD *md" .Fc +.Ft unsigned long +.Fo EVP_MD_flags +.Fa "const EVP_MD *md" +.Fc .Ft const EVP_MD * .Fo EVP_MD_CTX_md .Fa "const EVP_MD_CTX *ctx" .Fc .Ft int .Fo EVP_MD_CTX_size -.Fa "const EVP_MD *ctx" +.Fa "const EVP_MD_CTX *ctx" .Fc .Ft int .Fo EVP_MD_CTX_block_size -.Fa "const EVP_MD *ctx" +.Fa "const EVP_MD_CTX *ctx" .Fc .Ft int .Fo EVP_MD_CTX_type -.Fa "const EVP_MD *ctx" +.Fa "const EVP_MD_CTX *ctx" +.Fc +.Ft void * +.Fo EVP_MD_CTX_md_data +.Fa "const EVP_MD_CTX *ctx" +.Fc +.Ft EVP_PKEY_CTX * +.Fo EVP_MD_CTX_pkey_ctx +.Fa "const EVP_MD_CTX *ctx" +.Fc +.Ft void +.Fo EVP_MD_CTX_set_pkey_ctx +.Fa "EVP_MD_CTX *ctx" +.Fa "EVP_PKEY_CTX *pctx" .Fc .Ft const EVP_MD * .Fn EVP_md_null void @@ -261,7 +302,7 @@ .Fa "const ASN1_OBJECT *o" .Fc .Sh DESCRIPTION -The EVP digest routines are a high level interface to message digests +The EVP digest routines are a high-level interface to message digests and should be used instead of the cipher-specific functions. .Pp .Fn EVP_MD_CTX_new @@ -300,6 +341,42 @@ respectively. .Fn EVP_MD_CTX_ctrl performs digest-specific control actions on the context .Fa ctx . +The control command is indicated in +.Fa cmd +and any additional arguments in +.Fa p1 +and +.Fa p2 . +.Fn EVP_MD_CTX_ctrl +must be called after +.Fn EVP_DigestInit_ex . +Other restrictions may apply depending on the control type +and digest implementation. +.Pp +If the +.Fa cmd +is +.Dv EVP_MD_CTRL_MICALG , +the digest Message Integrity Check algorithm string is written to +.Pf * p2 . +This is used when creating S/MIME multipart/signed messages +as specified in RFC 3851. +.Pp +.Fn EVP_MD_CTX_set_flags , +.Fn EVP_MD_CTX_clear_flags , +and +.Fn EVP_MD_CTX_test_flags +set, clear and test the following +.Fa ctx +flags: +.Bl -tag -width Ds -offset 2n +.It Dv EVP_MD_CTX_FLAG_NO_INIT +Instruct +.Fn EVP_DigestInit +and similar functions not to initialise the implementation specific data. +.It Dv EVP_MD_CTX_FLAG_ONESHOT +Instruct the digest to optimize for one update only, if possible. +.El .Pp .Fn EVP_DigestInit_ex sets up the digest context @@ -431,7 +508,8 @@ or an .Vt EVP_MD_CTX structure. .Pp -.Fn EVP_MD_type +.Fn EVP_MD_type , +.Fn EVP_MD_pkey_type , and .Fn EVP_MD_CTX_type return the NID of the OBJECT IDENTIFIER representing the given message @@ -444,6 +522,23 @@ returns .Dv NID_sha1 . This function is normally used when setting ASN.1 OIDs. .Pp +.Fn EVP_MD_CTX_md_data +returns the digest method private data of +.Fa ctx . +The space was allocated and its size set with +.Xr EVP_MD_meth_set_app_datasize 3 . +.Pp +.Fn EVP_MD_flags +returns the +.Fa md +flags. +These are different from the +.Vt EVP_MD_CTX +ones. +See +.Xr EVP_MD_meth_set_flags 3 +for more information. +.Pp .Fn EVP_MD_pkey_type returns the NID of the public key signing algorithm associated with this digest. @@ -454,6 +549,40 @@ is associated with RSA so this will return Since digests and signature algorithms are no longer linked, this function is only retained for compatibility reasons. .Pp +.Fn EVP_MD_CTX_pkey_ctx +returns the +.Vt EVP_PKEY_CTX +assigned to +.Fa ctx . +The returned pointer should not be freed by the caller. +.Pp +.Fn EVP_MD_CTX_set_pkey_ctx +assigns +.Fa pctx +to +.Fa ctx . +This is usually used to provide a customized +.Vt EVP_PKEY_CTX +to +.Xr EVP_DigestSignInit 3 +or +.Xr EVP_DigestVerifyInit 3 . +The +.Fa pctx +passed to this function should be freed by the caller. +A +.Dv NULL +.Fa pctx +pointer is also allowed to clear the +.Vt EVP_PKEY_CTX +assigned to +.Fa ctx . +In this case, freeing the cleared +.Vt EVP_PKEY_CTX +or not depends on how the +.Vt EVP_PKEY_CTX +was created. +.Pp .Fn EVP_md5 , .Fn EVP_sha1 , .Fn EVP_sha224 , @@ -502,7 +631,7 @@ and are implemented as macros. .Pp The EVP interface to message digests should almost always be used -in preference to the low level interfaces. +in preference to the low-level interfaces. This is because the code then becomes transparent to the digest used and much more flexible. .Pp @@ -610,6 +739,7 @@ This example digests the data "Test Message\en" and "Hello World\en", using the digest name passed on the command line. .Bd -literal -offset indent #include +#include #include int @@ -620,7 +750,7 @@ main(int argc, char *argv[]) const char mess1[] = "Test Message\en"; const char mess2[] = "Hello World\en"; unsigned char md_value[EVP_MAX_MD_SIZE]; - int md_len, i; + unsigned int md_len, i; if (argc <= 1) { printf("Usage: mdtest digestname\en"); @@ -655,6 +785,7 @@ main(int argc, char *argv[]) .Xr EVP_BytesToKey 3 , .Xr EVP_DigestSignInit 3 , .Xr EVP_DigestVerifyInit 3 , +.Xr EVP_MD_meth_new 3 , .Xr EVP_PKEY_CTX_set_signature_md 3 , .Xr EVP_PKEY_meth_set_signctx 3 , .Xr EVP_SignInit 3 , @@ -750,6 +881,10 @@ and first appeared in OpenSSL 1.1.0 and have been available since .Ox 6.3 . .Pp +.Fn EVP_MD_CTX_set_pkey_ctx +first appeared in OpenSSL 1.1.1 and has been available since +.Ox 7.1 . +.Pp The link between digests and signing algorithms was fixed in OpenSSL 1.0 and later, so now .Fn EVP_sha1 -- 2.20.1