1.\" $OpenBSD: EVP_DigestSignInit.3,v 1.11 2021/05/20 14:41:47 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: May 20 2021 $ 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 192In previous versions of OpenSSL, there was a link between message digest 193types and public key algorithms. 194This meant that "clone" digests such as 195.Xr EVP_dss1 3 196needed to be used to sign using SHA1 and DSA. 197This is no longer necessary and the use of clone digest is now 198discouraged. 199.Pp 200The call to 201.Fn EVP_DigestSignFinal 202internally finalizes a copy of the digest context. 203This means that 204.Fn EVP_DigestSignUpdate 205and 206.Fn EVP_DigestSignFinal 207can be called later to digest and sign additional data. 208.Pp 209Since only a copy of the digest context is ever finalized, the context 210must be cleaned up after use by calling 211.Xr EVP_MD_CTX_free 3 , 212or a memory leak will occur. 213.Pp 214The use of 215.Xr EVP_PKEY_size 3 216with these functions is discouraged because some signature operations 217may have a signature length which depends on the parameters set. 218As a result, 219.Xr EVP_PKEY_size 3 220would have to return a value which indicates the maximum possible 221signature for any set of parameters. 222.Sh RETURN VALUES 223.Fn EVP_DigestSignInit , 224.Fn EVP_DigestSignUpdate , 225.Fn EVP_DigestSignFinal , 226and 227.Fn EVP_DigestSign 228return 1 for success and 0 for failure. 229.Pp 230The error codes can be obtained from 231.Xr ERR_get_error 3 . 232.Sh SEE ALSO 233.Xr evp 3 , 234.Xr EVP_DigestInit 3 , 235.Xr EVP_DigestVerifyInit 3 , 236.Xr EVP_PKEY_meth_set_signctx 3 237.Sh HISTORY 238.Fn EVP_DigestSignInit , 239.Fn EVP_DigestSignUpdate , 240and 241.Fn EVP_DigestSignFinal 242first appeared in OpenSSL 1.0.0 and have been available since 243.Ox 4.9 . 244.Pp 245.Fn EVP_DigestSign 246first appeared in OpenSSL 1.1.1 and has been available since 247.Ox 7.0 . 248