1.\" $OpenBSD: EVP_MD_CTX_ctrl.3,v 1.3 2024/03/05 17:21:40 tb Exp $ 2.\" full merge up to: OpenSSL man3/EVP_DigestInit.pod 3.\" 24a535ea Sep 22 13:14:20 2020 +0100 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org> 9.\" 10.\" Permission to use, copy, modify, and distribute this software for any 11.\" purpose with or without fee is hereby granted, provided that the above 12.\" copyright notice and this permission notice appear in all copies. 13.\" 14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 21.\" 22.\" The original file was written by Richard Levitte <levitte@openssl.org>, 23.\" Todd Short <tshort@akamai.com>, Paul Yang <yang.yang@baishancloud.com>, 24.\" and Antoine Salon <asalon@vmware.com>. 25.\" Copyright (c) 2015, 2016, 2018, 2019 The OpenSSL Project. 26.\" All rights reserved. 27.\" 28.\" Redistribution and use in source and binary forms, with or without 29.\" modification, are permitted provided that the following conditions 30.\" are met: 31.\" 32.\" 1. Redistributions of source code must retain the above copyright 33.\" notice, this list of conditions and the following disclaimer. 34.\" 35.\" 2. Redistributions in binary form must reproduce the above copyright 36.\" notice, this list of conditions and the following disclaimer in 37.\" the documentation and/or other materials provided with the 38.\" distribution. 39.\" 40.\" 3. All advertising materials mentioning features or use of this 41.\" software must display the following acknowledgment: 42.\" "This product includes software developed by the OpenSSL Project 43.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 44.\" 45.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 46.\" endorse or promote products derived from this software without 47.\" prior written permission. For written permission, please contact 48.\" openssl-core@openssl.org. 49.\" 50.\" 5. Products derived from this software may not be called "OpenSSL" 51.\" nor may "OpenSSL" appear in their names without prior written 52.\" permission of the OpenSSL Project. 53.\" 54.\" 6. Redistributions of any form whatsoever must retain the following 55.\" acknowledgment: 56.\" "This product includes software developed by the OpenSSL Project 57.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 58.\" 59.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 60.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 61.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 62.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 63.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 64.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 65.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 66.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 67.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 68.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 69.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 70.\" OF THE POSSIBILITY OF SUCH DAMAGE. 71.\" 72.Dd $Mdocdate: March 5 2024 $ 73.Dt EVP_MD_CTX_CTRL 3 74.Os 75.Sh NAME 76.Nm EVP_MD_CTX_ctrl , 77.Nm EVP_MD_CTX_set_flags , 78.Nm EVP_MD_CTX_clear_flags , 79.Nm EVP_MD_CTX_test_flags , 80.Nm EVP_MD_CTX_pkey_ctx , 81.Nm EVP_MD_CTX_set_pkey_ctx , 82.Nm EVP_MD_CTX_md_data 83.Nd configure EVP message digest contexts 84.Sh SYNOPSIS 85.In openssl/evp.h 86.Ft int 87.Fo EVP_MD_CTX_ctrl 88.Fa "EVP_MD_CTX *ctx" 89.Fa "int command" 90.Fa "int p1" 91.Fa "void* p2" 92.Fc 93.Ft void 94.Fo EVP_MD_CTX_set_flags 95.Fa "EVP_MD_CTX *ctx" 96.Fa "int flags" 97.Fc 98.Ft void 99.Fo EVP_MD_CTX_clear_flags 100.Fa "EVP_MD_CTX *ctx" 101.Fa "int flags" 102.Fc 103.Ft int 104.Fo EVP_MD_CTX_test_flags 105.Fa "const EVP_MD_CTX *ctx" 106.Fa "int flags" 107.Fc 108.Ft EVP_PKEY_CTX * 109.Fo EVP_MD_CTX_pkey_ctx 110.Fa "const EVP_MD_CTX *ctx" 111.Fc 112.Ft void 113.Fo EVP_MD_CTX_set_pkey_ctx 114.Fa "EVP_MD_CTX *ctx" 115.Fa "EVP_PKEY_CTX *pctx" 116.Fc 117.Ft void * 118.Fo EVP_MD_CTX_md_data 119.Fa "const EVP_MD_CTX *ctx" 120.Fc 121.Sh DESCRIPTION 122.Fn EVP_MD_CTX_ctrl 123performs the digest-specific control 124.Fa command 125with the command-specific arguments 126.Fa p1 127and 128.Fa p2 129on 130.Fa ctx , 131which needs to already be set up with 132.Xr EVP_DigestInit_ex 3 133before calling this function. 134Other restrictions may apply depending on the control 135.Fa command 136and digest implementation. 137.Pp 138If the 139.Fa command 140is 141.Dv EVP_MD_CTRL_MICALG , 142.Fa p1 143is ignored and 144.Fa p2 145is an output argument of the type 146.Fa "char **p2" . 147A string specifying the digest Message Integrity Check algorithm 148is allocated and a pointer to this string is returned in 149.Pf * Fa p2 . 150It is the responsibility of the caller to 151.Xr free 3 152.Pf * Fa p2 153when it is no longer needed. 154This 155.Fa command 156is used by 157.Xr SMIME_write_ASN1 3 158when creating S/MIME multipart/signed messages as specified in RFC 3851. 159.Pp 160.Fn EVP_MD_CTX_set_flags 161sets and 162.Fn EVP_MD_CTX_clear_flags 163clears all the flag bits in 164.Fa ctx 165that are set in the 166.Fa flags 167argument. 168.Fn EVP_MD_CTX_test_flags 169tests which of the flag bits that are set in the 170.Fa flags 171argument are also set in 172.Fa ctx . 173Possible flag bits are: 174.Bl -tag -width Ds -offset 2n 175.It Dv EVP_MD_CTX_FLAG_NO_INIT 176Instruct 177.Xr EVP_DigestInit_ex 3 178and functions calling it not to initialise the internal data 179that is specific to the digest method and its implementation. 180.It Dv EVP_MD_CTX_FLAG_ONESHOT 181Instruct the digest to optimize for one update only, if possible. 182For digest algorithms built into the library, this flag usually 183has no effect. 184.El 185.Pp 186.Fn EVP_MD_CTX_pkey_ctx 187returns the 188.Vt EVP_PKEY_CTX 189assigned to 190.Fa ctx . 191The returned pointer should not be freed by the caller. 192.Pp 193.Fn EVP_MD_CTX_set_pkey_ctx 194assigns 195.Fa pctx 196to 197.Fa ctx . 198This is normally used to provide a customized 199.Vt EVP_PKEY_CTX 200to 201.Xr EVP_DigestSignInit 3 202or 203.Xr EVP_DigestVerifyInit 3 . 204The caller retains ownership of the 205.Fa pctx 206passed to this function and is responsible for freeing it 207when it is no longer needed. 208.Pp 209If the 210.Fa ctx 211already contains a 212.Vt EVP_PKEY_CTX 213when this function is called, that old 214.Vt EVP_PKEY_CTX 215is freed if it was created internally, but if it was also installed with 216.Fn EVP_MD_CTX_set_pkey_ctx , 217the pointer to the old 218.Vt EVP_PKEY_CTX 219is merely replaced by the new pointer and ownership of the old 220.Vt EVP_PKEY_CTX 221remains with the previous caller. 222.Pp 223Passing a 224.Dv NULL 225pointer for the 226.Fa pctx 227argument is also allowed. 228In that case, any 229.Vt EVP_PKEY_CTX 230already assigned to 231.Fa ctx 232is dissociated from it as described above, but no new 233.Vt EVP_PKEY_CTX 234is assigned. 235.Pp 236.Fn EVP_MD_CTX_md_data 237returns the digest method private data of 238.Fa ctx . 239The space is allocated with a size determined at compile time. 240The size is not exposed by an API. 241.Sh RETURN VALUES 242.Fn EVP_MD_CTX_ctrl 243returns 1 for success or 0 for failure. 244.Pp 245.Fn EVP_MD_CTX_test_flags 246returns the bitwise OR of the 247.Fa flags 248argument and the flags set in 249.Fa ctx . 250.Pp 251.Fn EVP_MD_CTX_pkey_ctx 252and 253.Fn EVP_MD_CTX_md_data 254return pointers to storage owned by 255.Fa ctx . 256.Sh SEE ALSO 257.Xr evp 3 , 258.Xr EVP_DigestInit 3 , 259.Xr EVP_MD_nid 3 260.Sh HISTORY 261.Fn EVP_MD_CTX_set_flags , 262.Fn EVP_MD_CTX_clear_flags , 263and 264.Fn EVP_MD_CTX_test_flags , 265first appeared in OpenSSL 0.9.7 and have been available since 266.Ox 3.2 . 267.Pp 268.Fn EVP_MD_CTX_ctrl 269first appeared in OpenSSL 1.1.0 and has been available since 270.Ox 5.7 . 271.Pp 272.Fn EVP_MD_CTX_pkey_ctx 273and 274.Fn EVP_MD_CTX_md_data 275first appeared in OpenSSL 1.1.0 and 276.Fn EVP_MD_CTX_set_pkey_ctx 277in OpenSSL 1.1.1. 278These functions have been available since 279.Ox 7.1 . 280