From 4d855df4d5fdcecd40fe3e138b83a9a28ac736d8 Mon Sep 17 00:00:00 2001 From: schwarze Date: Sat, 12 Aug 2023 16:12:19 +0000 Subject: [PATCH] 1. Tweak the descriptions of EVP_MD_CTX_ctrl(3), EVP_MD_CTX_set_flags(3), EVP_MD_CTX_clear_flags(3), EVP_MD_CTX_test_flags(3), and the atrocious EVP_MD_CTX_set_pkey_ctx(3) for precision. 2. Tweak the description of EVP_MD_type(3) and EVP_MD_CTX_type(3) for conciseness. 3. Add a few missing HISTORY bits. --- lib/libcrypto/man/EVP_DigestInit.3 | 159 +++++++++++++++++++---------- 1 file changed, 107 insertions(+), 52 deletions(-) diff --git a/lib/libcrypto/man/EVP_DigestInit.3 b/lib/libcrypto/man/EVP_DigestInit.3 index 08b64b59b24..6c75adcc98b 100644 --- a/lib/libcrypto/man/EVP_DigestInit.3 +++ b/lib/libcrypto/man/EVP_DigestInit.3 @@ -1,11 +1,11 @@ -.\" $OpenBSD: EVP_DigestInit.3,v 1.26 2023/08/11 18:08:43 schwarze Exp $ +.\" $OpenBSD: EVP_DigestInit.3,v 1.27 2023/08/12 16:12:19 schwarze Exp $ .\" full merge up to: OpenSSL 7f572e95 Dec 2 13:57:04 2015 +0000 .\" 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: .\" -.\" Copyright (c) 2019 Ingo Schwarze +.\" Copyright (c) 2019, 2023 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -70,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: August 11 2023 $ +.Dd $Mdocdate: August 12 2023 $ .Dt EVP_DIGESTINIT 3 .Os .Sh NAME @@ -150,7 +150,7 @@ .Ft int .Fo EVP_MD_CTX_ctrl .Fa "EVP_MD_CTX *ctx" -.Fa "int cmd" +.Fa "int command" .Fa "int p1" .Fa "void* p2" .Fc @@ -339,43 +339,67 @@ and respectively. .Pp .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 +performs the digest-specific control +.Fa command +with the command-specific arguments .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 +.Fa p2 +on +.Fa ctx , +which needs to already be set up with +.Fn EVP_DigestInit_ex +before calling this function. +Other restrictions may apply depending on the control +.Fa command and digest implementation. .Pp If the -.Fa cmd +.Fa command 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 p1 +is ignored and +.Fa p2 +is an output argument of the type +.Fa "char **p2" . +A string specifying the digest Message Integrity Check algorithm +is allocated and a pointer to this string is returned in +.Pf * Fa p2 . +It is the responsibility of the caller to +.Xr free 3 +.Pf * Fa p2 +when it is no longer needed. +This +.Fa command +is used by +.Xr SMIME_write_ASN1 3 +when creating S/MIME multipart/signed messages as specified in RFC 3851. +.Pp +.Fn EVP_MD_CTX_set_flags +sets and +.Fn EVP_MD_CTX_clear_flags +clears all the flag bits in .Fa ctx -flags: +that are set in the +.Fa flags +argument. +.Fn EVP_MD_CTX_test_flags +tests which of the flag bits that are set in the +.Fa flags +argument are also set in +.Fa ctx . +Possible flag bits are: .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. +.Fn EVP_DigestInit_ex +and functions calling it not to initialise the internal data +that is specific to the digest method and its implementation. .It Dv EVP_MD_CTX_FLAG_ONESHOT Instruct the digest to optimize for one update only, if possible. +For digest algorithms built into the library, this flag usually +has no effect. .El .Pp .Fn EVP_DigestInit_ex @@ -508,19 +532,15 @@ or an .Vt EVP_MD_CTX structure. .Pp -.Fn EVP_MD_type , -.Fn EVP_MD_pkey_type , +.Fn EVP_MD_type and .Fn EVP_MD_CTX_type -return the NID of the OBJECT IDENTIFIER representing the given message -digest when passed an -.Vt EVP_MD -structure. +return the NID of the OBJECT IDENTIFIER representing the message digest. For example .Fn EVP_MD_type EVP_sha1() returns .Dv NID_sha1 . -This function is normally used when setting ASN.1 OIDs. +These functions are normally used when setting ASN.1 OIDs. .Pp .Fn EVP_MD_CTX_md_data returns the digest method private data of @@ -561,27 +581,43 @@ assigns .Fa pctx to .Fa ctx . -This is usually used to provide a customized +This is normally used to provide a customized .Vt EVP_PKEY_CTX to .Xr EVP_DigestSignInit 3 or .Xr EVP_DigestVerifyInit 3 . -The +The caller retains ownership of the .Fa pctx -passed to this function should be freed by the caller. -A +passed to this function and is responsible for freeing it +when it is no longer needed. +.Pp +If the +.Fa ctx +already contains a +.Vt EVP_PKEY_CTX +when this function is called, that old +.Vt EVP_PKEY_CTX +is freed if it was created internally, but if it was also installed with +.Fn EVP_MD_CTX_set_pkey_ctx , +the pointer to the old +.Vt EVP_PKEY_CTX +is merely replaced by the new pointer and ownership of the old +.Vt EVP_PKEY_CTX +remains with the previous caller. +.Pp +Passing a .Dv NULL +pointer for the .Fa pctx -pointer is also allowed to clear the -.Vt EVP_PKEY_CTX -assigned to -.Fa ctx . -In this case, freeing the cleared +argument is also allowed. +In that case, any .Vt EVP_PKEY_CTX -or not depends on how the +already assigned to +.Fa ctx +is dissociated from it as described above, but no new .Vt EVP_PKEY_CTX -was created. +is assigned. .Pp .Fn EVP_md5 , .Fn EVP_sha1 , @@ -688,6 +724,12 @@ and .Fn EVP_MD_CTX_copy return 1 for success or 0 for failure. .Pp +.Fn EVP_MD_CTX_test_flags +returns the bitwise OR of the +.Fa flags +argument and the flags set in +.Fa ctx . +.Pp .Fn EVP_MD_type , .Fn EVP_MD_pkey_type , and @@ -846,6 +888,9 @@ first appeared in OpenSSL 0.9.5 and has been available since .Fn EVP_MD_CTX_create , .Fn EVP_MD_CTX_cleanup , .Fn EVP_MD_CTX_destroy , +.Fn EVP_MD_CTX_set_flags , +.Fn EVP_MD_CTX_clear_flags , +.Fn EVP_MD_CTX_test_flags , .Fn EVP_DigestInit_ex , .Fn EVP_DigestFinal_ex , .Fn EVP_Digest , @@ -863,11 +908,10 @@ first appeared in OpenSSL 0.9.7h and 0.9.8a and have been available since .Ox 4.0 . .Pp -.Fn EVP_sha512_224 -and -.Fn EVP_sha512_256 -first appeared in OpenSSL 1.1.1 and has been available since -.Ox 7.4 . +.Fn EVP_MD_flags +first appeared in OpenSSL 1.0.0 +and has been available since +.Ox 4.9 . .Pp .Fn EVP_MD_CTX_ctrl first appeared in OpenSSL 1.1.0 and has been available since @@ -881,10 +925,21 @@ and first appeared in OpenSSL 1.1.0 and have been available since .Ox 6.3 . .Pp +.Fn EVP_MD_CTX_md_data +and +.Fn EVP_MD_CTX_pkey_ctx +first appeared in OpenSSL 1.1.0 and .Fn EVP_MD_CTX_set_pkey_ctx -first appeared in OpenSSL 1.1.1 and has been available since +in OpenSSL 1.1.1. +These functions have been available since .Ox 7.1 . .Pp +.Fn EVP_sha512_224 +and +.Fn EVP_sha512_256 +first appeared in OpenSSL 1.1.1 and have been available since +.Ox 7.4 . +.Pp The link between digests and signing algorithms was fixed in OpenSSL 1.0 and later, so now .Fn EVP_sha1 -- 2.20.1