From ac20bb42fcec4c75215a5bca5b62760f3476c869 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Thu, 7 Sep 2023 14:22:11 +0000 Subject: 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. --- src/lib/libcrypto/man/EVP_MD_CTX_ctrl.3 | 274 ++++++++++++++++++++++++++++++++ 1 file changed, 274 insertions(+) create mode 100644 src/lib/libcrypto/man/EVP_MD_CTX_ctrl.3 (limited to 'src/lib/libcrypto/man/EVP_MD_CTX_ctrl.3') diff --git a/src/lib/libcrypto/man/EVP_MD_CTX_ctrl.3 b/src/lib/libcrypto/man/EVP_MD_CTX_ctrl.3 new file mode 100644 index 0000000000..8b6f8724fc --- /dev/null +++ b/src/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 . -- cgit v1.2.3-55-g6feb