1.\" $OpenBSD: EVP_DigestSignInit.3,v 1.15 2024/12/06 14:27:49 schwarze Exp $ 2.\" full merge up to: OpenSSL 28428130 Apr 17 15:18:40 2018 +0200 3.\" selective merge up to: OpenSSL 6328d367 Jul 4 21:58:30 2020 +0200 4.\" 5.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 6.\" Copyright (c) 2006, 2009, 2015, 2016, 2017 The OpenSSL Project. 7.\" All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in 18.\" the documentation and/or other materials provided with the 19.\" distribution. 20.\" 21.\" 3. All advertising materials mentioning features or use of this 22.\" software must display the following acknowledgment: 23.\" "This product includes software developed by the OpenSSL Project 24.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 25.\" 26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 27.\" endorse or promote products derived from this software without 28.\" prior written permission. For written permission, please contact 29.\" openssl-core@openssl.org. 30.\" 31.\" 5. Products derived from this software may not be called "OpenSSL" 32.\" nor may "OpenSSL" appear in their names without prior written 33.\" permission of the OpenSSL Project. 34.\" 35.\" 6. Redistributions of any form whatsoever must retain the following 36.\" acknowledgment: 37.\" "This product includes software developed by the OpenSSL Project 38.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 39.\" 40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 43.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 51.\" OF THE POSSIBILITY OF SUCH DAMAGE. 52.\" 53.Dd $Mdocdate: December 6 2024 $ 54.Dt EVP_DIGESTSIGNINIT 3 55.Os 56.Sh NAME 57.Nm EVP_DigestSignInit , 58.Nm EVP_DigestSignUpdate , 59.Nm EVP_DigestSignFinal , 60.Nm EVP_DigestSign 61.Nd EVP signing functions 62.Sh SYNOPSIS 63.In openssl/evp.h 64.Ft int 65.Fo EVP_DigestSignInit 66.Fa "EVP_MD_CTX *ctx" 67.Fa "EVP_PKEY_CTX **pctx" 68.Fa "const EVP_MD *type" 69.Fa "ENGINE *engine" 70.Fa "EVP_PKEY *pkey" 71.Fc 72.Ft int 73.Fo EVP_DigestSignUpdate 74.Fa "EVP_MD_CTX *ctx" 75.Fa "const void *d" 76.Fa "size_t cnt" 77.Fc 78.Ft int 79.Fo EVP_DigestSignFinal 80.Fa "EVP_MD_CTX *ctx" 81.Fa "unsigned char *sig" 82.Fa "size_t *siglen" 83.Fc 84.Ft int 85.Fo EVP_DigestSign 86.Fa "EVP_MD_CTX *ctx" 87.Fa "unsigned char *sigret" 88.Fa "size_t *siglen" 89.Fa "const unsigned char *tbs" 90.Fa "size_t tbslen" 91.Fc 92.Sh DESCRIPTION 93The EVP signature routines are a high-level interface to digital 94signatures. 95.Pp 96.Fn EVP_DigestSignInit 97sets up the signing context 98.Fa ctx 99to use the digest 100.Fa type 101and the private key 102.Fa pkey . 103Before calling this function, obtain 104.Fa ctx 105from 106.Xr EVP_MD_CTX_new 3 107or call 108.Xr EVP_MD_CTX_reset 3 109on it. 110The 111.Fa engine 112argument is always ignored and passing 113.Dv NULL 114is recommended. 115.Pp 116If 117.Fa pctx 118is not 119.Dv NULL , 120any pointer passed in as 121.Pf * Fa pctx 122is ignored and overwritten by an internal pointer to the 123.Vt EVP_PKEY_CTX 124used by the signing operation: 125this can be used to set alternative signing options. 126The returned 127.Vt EVP_PKEY_CTX 128must not be freed by the application. 129It is freed automatically when the 130.Vt EVP_MD_CTX 131is freed. 132.Pp 133.Fn EVP_DigestSignUpdate 134hashes 135.Fa cnt 136bytes of data at 137.Fa d 138into the signature context 139.Fa ctx . 140This function can be called several times on the same 141.Fa ctx 142to include additional data. 143This function is currently implemented using a macro. 144.Pp 145.Fn EVP_DigestSignFinal 146signs the data in 147.Fa ctx 148and places the signature in 149.Fa sig . 150If 151.Fa sig 152is 153.Dv NULL , 154then the maximum size of the output buffer is written to 155.Pf * Fa siglen . 156If 157.Fa sig 158is not 159.Dv NULL , 160then before the call 161.Fa siglen 162should contain the length of the 163.Fa sig 164buffer. 165If the call is successful, the signature is written to 166.Fa sig 167and the amount of data written to 168.Fa siglen . 169.Pp 170.Fn EVP_DigestSign 171signs 172.Fa tbslen 173bytes of data at 174.Fa tbs 175and places the signature in 176.Fa sigret 177and its length in 178.Fa siglen 179in a similar way to 180.Fn EVP_DigestSignFinal . 181.Fn EVP_DigestSign 182is a one shot operation which signs a single block of data 183with one function call. 184For algorithms that support streaming it is equivalent to calling 185.Fn EVP_DigestSignUpdate 186and 187.Fn EVP_DigestSignFinal . 188.\" For algorithms which do not support streaming 189.\" (e.g. PureEdDSA) 190.\" it is the only way to sign data. 191.Pp 192The EVP interface to digital signatures should almost always be 193used in preference to the low-level interfaces. 194This is because the code then becomes transparent to the algorithm used 195and much more flexible. 196.Pp 197The call to 198.Fn EVP_DigestSignFinal 199internally finalizes a copy of the digest context. 200This means that 201.Fn EVP_DigestSignUpdate 202and 203.Fn EVP_DigestSignFinal 204can be called later to digest and sign additional data. 205.Pp 206Since only a copy of the digest context is ever finalized, the context 207must be cleaned up after use by calling 208.Xr EVP_MD_CTX_free 3 , 209or a memory leak will occur. 210.Pp 211The use of 212.Xr EVP_PKEY_size 3 213with these functions is discouraged because some signature operations 214may have a signature length which depends on the parameters set. 215As a result, 216.Xr EVP_PKEY_size 3 217would have to return a value which indicates the maximum possible 218signature for any set of parameters. 219.Sh RETURN VALUES 220.Fn EVP_DigestSignInit , 221.Fn EVP_DigestSignUpdate , 222.Fn EVP_DigestSignFinal , 223and 224.Fn EVP_DigestSign 225return 1 for success and 0 for failure. 226.Pp 227The error codes can be obtained from 228.Xr ERR_get_error 3 . 229.Sh SEE ALSO 230.Xr evp 3 , 231.Xr EVP_DigestInit 3 , 232.Xr EVP_DigestVerifyInit 3 233.Sh HISTORY 234.Fn EVP_DigestSignInit , 235.Fn EVP_DigestSignUpdate , 236and 237.Fn EVP_DigestSignFinal 238first appeared in OpenSSL 1.0.0 and have been available since 239.Ox 4.9 . 240.Pp 241.Fn EVP_DigestSign 242first appeared in OpenSSL 1.1.1 and has been available since 243.Ox 7.0 . 244