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