From 52b4c7b70e668c9594f97c7ad401edc746a17961 Mon Sep 17 00:00:00 2001 From: schwarze Date: Thu, 7 Sep 2023 14:22:11 +0000 Subject: [PATCH] Split two new manual pages EVP_MD_nid(3) and EVP_MD_CTX_ctrl(3) out of the large EVP_DigestInit(3). No text change. --- lib/libcrypto/man/EVP_DigestInit.3 | 319 +--------------------------- lib/libcrypto/man/EVP_MD_CTX_ctrl.3 | 274 ++++++++++++++++++++++++ lib/libcrypto/man/EVP_MD_nid.3 | 213 +++++++++++++++++++ lib/libcrypto/man/Makefile | 4 +- lib/libcrypto/man/evp.3 | 6 +- 5 files changed, 501 insertions(+), 315 deletions(-) create mode 100644 lib/libcrypto/man/EVP_MD_CTX_ctrl.3 create mode 100644 lib/libcrypto/man/EVP_MD_nid.3 diff --git a/lib/libcrypto/man/EVP_DigestInit.3 b/lib/libcrypto/man/EVP_DigestInit.3 index 54cc771b107..562592b3c88 100644 --- a/lib/libcrypto/man/EVP_DigestInit.3 +++ b/lib/libcrypto/man/EVP_DigestInit.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EVP_DigestInit.3,v 1.29 2023/08/27 15:33:08 schwarze Exp $ +.\" $OpenBSD: EVP_DigestInit.3,v 1.30 2023/09/07 14:22:11 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 .\" @@ -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 27 2023 $ +.Dd $Mdocdate: September 7 2023 $ .Dt EVP_DIGESTINIT 3 .Os .Sh NAME @@ -81,10 +81,6 @@ .Nm EVP_MD_CTX_create , .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 , @@ -94,18 +90,7 @@ .Nm EVP_DigestFinal , .Nm EVP_MD_CTX_copy , .Nm EVP_MAX_MD_SIZE , -.Nm EVP_MD_type , -.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_sha224 , .Nm EVP_sha256 , @@ -145,28 +130,6 @@ .Fa "EVP_MD_CTX *ctx" .Fc .Ft int -.Fo EVP_MD_CTX_ctrl -.Fa "EVP_MD_CTX *ctx" -.Fa "int command" -.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" .Fa "const EVP_MD *type" @@ -215,55 +178,10 @@ .Fa "EVP_MD_CTX *in" .Fc .Fd #define EVP_MAX_MD_SIZE 64 /* SHA512 */ -.Ft int -.Fo EVP_MD_type -.Fa "const EVP_MD *md" -.Fc -.Ft int -.Fo EVP_MD_pkey_type -.Fa "const EVP_MD *md" -.Fc -.Ft int -.Fo EVP_MD_size -.Fa "const EVP_MD *md" -.Fc -.Ft int -.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 *ctx" -.Fc -.Ft int -.Fo EVP_MD_CTX_block_size -.Fa "const EVP_MD_CTX *ctx" -.Fc -.Ft int -.Fo EVP_MD_CTX_type -.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 .Ft const EVP_MD * @@ -329,70 +247,6 @@ and .Fn EVP_MD_CTX_free , respectively. .Pp -.Fn EVP_MD_CTX_ctrl -performs the digest-specific control -.Fa command -with the command-specific arguments -.Fa p1 -and -.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 command -is -.Dv EVP_MD_CTRL_MICALG , -.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 -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_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 sets up the digest context .Fa ctx @@ -505,111 +359,6 @@ except that it requires before a context that was already used can be passed as .Fa out . .Pp -.Fn EVP_MD_size -and -.Fn EVP_MD_CTX_size -return the size of the message digest when passed an -.Vt EVP_MD -or an -.Vt EVP_MD_CTX -structure, i.e. the size of the hash. -.Pp -.Fn EVP_MD_block_size -and -.Fn EVP_MD_CTX_block_size -return the block size of the message digest when passed an -.Vt EVP_MD -or an -.Vt EVP_MD_CTX -structure. -.Pp -.Fn EVP_MD_type -and -.Fn EVP_MD_CTX_type -return the NID of the OBJECT IDENTIFIER representing the message digest. -For example -.Fn EVP_MD_type EVP_sha512() -returns -.Dv NID_sha512 . -These functions are 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. -For example -.Fn EVP_sha512 -is associated with RSA so this will return -.Dv NID_sha512WithRSAEncryption . -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 normally used to provide a customized -.Vt EVP_PKEY_CTX -to -.Xr EVP_DigestSignInit 3 -or -.Xr EVP_DigestVerifyInit 3 . -The caller retains ownership of the -.Fa pctx -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 -argument is also allowed. -In that case, any -.Vt EVP_PKEY_CTX -already assigned to -.Fa ctx -is dissociated from it as described above, but no new -.Vt EVP_PKEY_CTX -is assigned. -.Pp .Fn EVP_sha224 , .Fn EVP_sha256 , .Fn EVP_sha384 , @@ -642,10 +391,7 @@ return an structure when passed a digest name, a digest NID, or an ASN1_OBJECT structure respectively. .Pp -.Fn EVP_MD_CTX_size , -.Fn EVP_MD_CTX_block_size , -.Fn EVP_MD_CTX_type , -.Fn EVP_get_digestbynid , +.Fn EVP_get_digestbynid and .Fn EVP_get_digestbyobj are implemented as macros. @@ -693,7 +439,6 @@ and .Fn EVP_MD_CTX_cleanup always return 1. .Pp -.Fn EVP_MD_CTX_ctrl , .Fn EVP_DigestInit_ex , .Fn EVP_DigestUpdate , .Fn EVP_DigestFinal_ex , @@ -705,27 +450,6 @@ 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 -.Fn EVP_MD_CTX_type -return the NID of the corresponding OBJECT IDENTIFIER or -.Dv NID_undef -if none exists. -.Pp -.Fn EVP_MD_size , -.Fn EVP_MD_block_size , -.Fn EVP_MD_CTX_size , -and -.Fn EVP_MD_CTX_block_size -return the digest or block size in bytes. -.Pp .Fn EVP_MD_CTX_md returns the .Vt EVP_MD @@ -805,7 +529,9 @@ main(int argc, char *argv[]) .Xr EVP_BytesToKey 3 , .Xr EVP_DigestSignInit 3 , .Xr EVP_DigestVerifyInit 3 , +.Xr EVP_MD_CTX_ctrl 3 , .Xr EVP_MD_meth_new 3 , +.Xr EVP_MD_nid 3 , .Xr EVP_PKEY_CTX_set_signature_md 3 , .Xr EVP_PKEY_meth_set_signctx 3 , .Xr EVP_sha1 3 , @@ -829,24 +555,14 @@ main(int argc, char *argv[]) and .Dv EVP_MAX_MD_SIZE first appeared in SSLeay 0.5.1. -.Fn EVP_MD_size -first appeared in SSLeay 0.6.6. -.Fn EVP_MD_CTX_size , -.Fn EVP_MD_CTX_type , -.Fn EVP_md_null , +.Fn EVP_md_null and .Fn EVP_get_digestbyname first appeared in SSLeay 0.8.0. -.Fn EVP_MD_type , -.Fn EVP_MD_pkey_type , -.Fn EVP_get_digestbynid , +.Fn EVP_get_digestbynid and .Fn EVP_get_digestbyobj first appeared in SSLeay 0.8.1. -.Fn EVP_MD_block_size , -.Fn EVP_MD_CTX_size , -.Fn EVP_MD_CTX_block_size , -and .Fn EVP_ripemd160 first appeared in SSLeay 0.9.0. All these functions have been available since @@ -864,9 +580,6 @@ 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 , @@ -884,15 +597,6 @@ first appeared in OpenSSL 0.9.7h and 0.9.8a and have been available since .Ox 4.0 . .Pp -.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 -.Ox 5.7 . -.Pp .Fn EVP_MD_CTX_new , .Fn EVP_MD_CTX_reset , and @@ -900,15 +604,6 @@ 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 -in OpenSSL 1.1.1. -These functions have been available since -.Ox 7.1 . -.Pp .Fn EVP_sha512_224 and .Fn EVP_sha512_256 diff --git a/lib/libcrypto/man/EVP_MD_CTX_ctrl.3 b/lib/libcrypto/man/EVP_MD_CTX_ctrl.3 new file mode 100644 index 00000000000..8b6f8724fcb --- /dev/null +++ b/lib/libcrypto/man/EVP_MD_CTX_ctrl.3 @@ -0,0 +1,274 @@ +.\" $OpenBSD: EVP_MD_CTX_ctrl.3,v 1.1 2023/09/07 14:22:11 schwarze Exp $ +.\" full merge up to: OpenSSL man3/EVP_DigestInit.pod +.\" 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) 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 +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" 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 Richard Levitte , +.\" Todd Short , Paul Yang , +.\" and Antoine Salon . +.\" Copyright (c) 2015, 2016, 2018, 2019 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: September 7 2023 $ +.Dt EVP_MD_CTX_CTRL 3 +.Os +.Sh NAME +.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_MD_CTX_pkey_ctx , +.Nm EVP_MD_CTX_set_pkey_ctx , +.Nm EVP_MD_CTX_md_data +.Nd configure EVP message digest contexts +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_MD_CTX_ctrl +.Fa "EVP_MD_CTX *ctx" +.Fa "int command" +.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 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 void * +.Fo EVP_MD_CTX_md_data +.Fa "const EVP_MD_CTX *ctx" +.Fc +.Sh DESCRIPTION +.Fn EVP_MD_CTX_ctrl +performs the digest-specific control +.Fa command +with the command-specific arguments +.Fa p1 +and +.Fa p2 +on +.Fa ctx , +which needs to already be set up with +.Xr EVP_DigestInit_ex 3 +before calling this function. +Other restrictions may apply depending on the control +.Fa command +and digest implementation. +.Pp +If the +.Fa command +is +.Dv EVP_MD_CTRL_MICALG , +.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 +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 +.Xr EVP_DigestInit_ex 3 +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_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 normally used to provide a customized +.Vt EVP_PKEY_CTX +to +.Xr EVP_DigestSignInit 3 +or +.Xr EVP_DigestVerifyInit 3 . +The caller retains ownership of the +.Fa pctx +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 +argument is also allowed. +In that case, any +.Vt EVP_PKEY_CTX +already assigned to +.Fa ctx +is dissociated from it as described above, but no new +.Vt EVP_PKEY_CTX +is assigned. +.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 . +.Sh RETURN VALUES +.Fn EVP_MD_CTX_ctrl +returns 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 . +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_MD_meth_new 3 , +.Xr EVP_MD_nid 3 +.Sh HISTORY +.Fn EVP_MD_CTX_set_flags , +.Fn EVP_MD_CTX_clear_flags , +and +.Fn EVP_MD_CTX_test_flags , +first appeared in OpenSSL 0.9.7 and have been available since +.Ox 3.2 . +.Pp +.Fn EVP_MD_CTX_ctrl +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 5.7 . +.Pp +.Fn EVP_MD_CTX_pkey_ctx +and +.Fn EVP_MD_CTX_md_data +first appeared in OpenSSL 1.1.0 and +.Fn EVP_MD_CTX_set_pkey_ctx +in OpenSSL 1.1.1. +These functions have been available since +.Ox 7.1 . diff --git a/lib/libcrypto/man/EVP_MD_nid.3 b/lib/libcrypto/man/EVP_MD_nid.3 new file mode 100644 index 00000000000..30836535903 --- /dev/null +++ b/lib/libcrypto/man/EVP_MD_nid.3 @@ -0,0 +1,213 @@ +.\" $OpenBSD: EVP_MD_nid.3,v 1.1 2023/09/07 14:22:11 schwarze Exp $ +.\" full merge up to: OpenSSL man3/EVP_DigestInit.pod +.\" 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) 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 +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" 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 Antoine Salon . +.\" Copyright (c) 2000, 2012, 2019 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: September 7 2023 $ +.Dt EVP_MD_TYPE 3 +.Os +.Sh NAME +.Nm EVP_MD_type , +.Nm EVP_MD_CTX_type , +.Nm EVP_MD_size , +.Nm EVP_MD_CTX_size , +.Nm EVP_MD_block_size , +.Nm EVP_MD_CTX_block_size , +.Nm EVP_MD_flags , +.Nm EVP_MD_pkey_type +.Nd inspect EVP_MD objects +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_MD_type +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_MD_CTX_type +.Fa "const EVP_MD_CTX *ctx" +.Fc +.Ft int +.Fo EVP_MD_size +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_MD_CTX_size +.Fa "const EVP_MD_CTX *ctx" +.Fc +.Ft int +.Fo EVP_MD_block_size +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_MD_CTX_block_size +.Fa "const EVP_MD_CTX *ctx" +.Fc +.Ft unsigned long +.Fo EVP_MD_flags +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_MD_pkey_type +.Fa "const EVP_MD *md" +.Fc +.Sh DESCRIPTION +.Fn EVP_MD_type +and +.Fn EVP_MD_CTX_type +return the NID of the OBJECT IDENTIFIER representing the message digest. +For example +.Fn EVP_MD_type EVP_sha512() +returns +.Dv NID_sha512 . +These functions are normally used when setting ASN.1 OIDs. +.Pp +.Fn EVP_MD_size +and +.Fn EVP_MD_CTX_size +return the size of the message digest when passed an +.Vt EVP_MD +or an +.Vt EVP_MD_CTX +structure, i.e. the size of the hash. +.Pp +.Fn EVP_MD_block_size +and +.Fn EVP_MD_CTX_block_size +return the block size of the message digest when passed an +.Vt EVP_MD +or an +.Vt EVP_MD_CTX +structure. +.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. +For example +.Fn EVP_sha512 +is associated with RSA so this will return +.Dv NID_sha512WithRSAEncryption . +Since digests and signature algorithms are no longer linked, this +function is only retained for compatibility reasons. +.Pp +.Fn EVP_MD_CTX_size , +.Fn EVP_MD_CTX_block_size , +and +.Fn EVP_MD_CTX_type +are implemented as macros. +.Sh RETURN VALUES +.Fn EVP_MD_type , +.Fn EVP_MD_CTX_type , +and +.Fn EVP_MD_pkey_type +return the NID of the corresponding OBJECT IDENTIFIER or +.Dv NID_undef +if none exists. +.Pp +.Fn EVP_MD_size , +.Fn EVP_MD_CTX_size , +.Fn EVP_MD_block_size , +and +.Fn EVP_MD_CTX_block_size +return the digest or block size in bytes. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_MD_CTX_ctrl 3 +.Sh HISTORY +.Fn EVP_MD_size +first appeared in SSLeay 0.6.6, +.Fn EVP_MD_CTX_size +and +.Fn EVP_MD_CTX_type +in SSLeay 0.8.0, +.Fn EVP_MD_type +and +.Fn EVP_MD_pkey_type +in SSLeay 0.8.1, and +.Fn EVP_MD_block_size +and +.Fn EVP_MD_CTX_block_size +in SSLeay 0.9.0. +All these functions have been available since +.Ox 2.4 . +.Pp +.Fn EVP_MD_flags +first appeared in OpenSSL 1.0.0 +and has been available since +.Ox 4.9 . diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 654a4f02a20..c7a79fa7b6f 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.266 2023/08/31 17:27:41 schwarze Exp $ +# $OpenBSD: Makefile,v 1.267 2023/09/07 14:22:11 schwarze Exp $ .include @@ -175,7 +175,9 @@ MAN= \ EVP_DigestVerifyInit.3 \ EVP_EncodeInit.3 \ EVP_EncryptInit.3 \ + EVP_MD_CTX_ctrl.3 \ EVP_MD_meth_new.3 \ + EVP_MD_nid.3 \ EVP_OpenInit.3 \ EVP_PKCS82PKEY.3 \ EVP_PKEY_CTX_ctrl.3 \ diff --git a/lib/libcrypto/man/evp.3 b/lib/libcrypto/man/evp.3 index d2b92ae6a5e..2f2d07c7a7e 100644 --- a/lib/libcrypto/man/evp.3 +++ b/lib/libcrypto/man/evp.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: evp.3,v 1.22 2023/08/31 17:27:41 schwarze Exp $ +.\" $OpenBSD: evp.3,v 1.23 2023/09/07 14:22:11 schwarze Exp $ .\" full merge up to: OpenSSL man7/evp 24a535ea Sep 22 13:14:20 2020 +0100 .\" .\" This file was written by Ulf Moeller , @@ -51,7 +51,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: August 31 2023 $ +.Dd $Mdocdate: September 7 2023 $ .Dt EVP 3 .Os .Sh NAME @@ -211,7 +211,9 @@ operations are more efficient using the high-level interfaces. .Xr EVP_DigestVerifyInit 3 , .Xr EVP_EncodeInit 3 , .Xr EVP_EncryptInit 3 , +.Xr EVP_MD_CTX_ctrl 3 , .Xr EVP_MD_meth_new 3 , +.Xr EVP_MD_nid 3 , .Xr EVP_OpenInit 3 , .Xr EVP_PKCS82PKEY 3 , .Xr EVP_PKEY_add1_attr 3 , -- 2.20.1