1.\" $OpenBSD: EVP_SignInit.3,v 1.16 2022/07/13 19:10:40 schwarze Exp $ 2.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 3.\" selective merge up to: OpenSSL 79b49fb0 Mar 20 10:03:10 2018 +1000 4.\" 5.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 6.\" Copyright (c) 2000-2002, 2005, 2006, 2014-2016 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: July 13 2022 $ 54.Dt EVP_SIGNINIT 3 55.Os 56.Sh NAME 57.Nm EVP_SignInit_ex , 58.Nm EVP_SignUpdate , 59.Nm EVP_SignFinal , 60.Nm EVP_SignInit 61.Nd EVP signing functions 62.Sh SYNOPSIS 63.In openssl/evp.h 64.Ft int 65.Fo EVP_SignInit_ex 66.Fa "EVP_MD_CTX *ctx" 67.Fa "const EVP_MD *type" 68.Fa "ENGINE *impl" 69.Fc 70.Ft int 71.Fo EVP_SignUpdate 72.Fa "EVP_MD_CTX *ctx" 73.Fa "const void *d" 74.Fa "unsigned int cnt" 75.Fc 76.Ft int 77.Fo EVP_SignFinal 78.Fa "EVP_MD_CTX *ctx" 79.Fa "unsigned char *sig" 80.Fa "unsigned int *s" 81.Fa "EVP_PKEY *pkey" 82.Fc 83.Ft void 84.Fo EVP_SignInit 85.Fa "EVP_MD_CTX *ctx" 86.Fa "const EVP_MD *type" 87.Fc 88.Sh DESCRIPTION 89The EVP signature routines are a high level interface to digital 90signatures. 91.Pp 92.Fn EVP_SignInit_ex 93sets up a signing context 94.Fa ctx 95to use the digest 96.Fa type 97from 98.Vt ENGINE 99.Fa impl . 100.Fa ctx 101must be initialized with 102.Xr EVP_MD_CTX_init 3 103before calling this function. 104.Pp 105.Fn EVP_SignUpdate 106hashes 107.Fa cnt 108bytes of data at 109.Fa d 110into the signature context 111.Fa ctx . 112This function can be called several times on the same 113.Fa ctx 114to include additional data. 115.Pp 116.Fn EVP_SignFinal 117signs the data in 118.Fa ctx 119using the private key 120.Fa pkey 121and places the signature in 122.Fa sig . 123.Fa sig 124must be at least 125.Xr EVP_PKEY_size 3 126bytes in size. 127.Fa s 128is an OUT parameter, and not used as an IN parameter. 129The number of bytes of data written (i.e.\& 130the length of the signature) will be written to the integer at 131.Fa s . 132At most 133.Xr EVP_PKEY_size 3 134bytes will be written. 135.Pp 136.Fn EVP_SignInit 137initializes a signing context 138.Fa ctx 139to use the default implementation of digest 140.Fa type . 141.Pp 142The EVP interface to digital signatures should almost always be 143used in preference to the low level interfaces. 144This is because the code then becomes transparent to the algorithm used 145and much more flexible. 146.Pp 147The call to 148.Fn EVP_SignFinal 149internally finalizes a copy of the digest context. 150This means that calls to 151.Fn EVP_SignUpdate 152and 153.Fn EVP_SignFinal 154can be called later to digest and sign additional data. 155.Pp 156Since only a copy of the digest context is ever finalized, the context 157must be cleaned up after use by calling 158.Xr EVP_MD_CTX_free 3 159or a memory leak will occur. 160.Sh RETURN VALUES 161.Fn EVP_SignInit_ex , 162.Fn EVP_SignUpdate , 163and 164.Fn EVP_SignFinal 165return 1 for success and 0 for failure. 166.Pp 167The error codes can be obtained by 168.Xr ERR_get_error 3 . 169.Sh SEE ALSO 170.Xr evp 3 , 171.Xr EVP_DigestInit 3 , 172.Xr EVP_PKEY_asn1_set_public 3 , 173.Xr EVP_PKEY_size 3 , 174.Xr EVP_VerifyInit 3 175.Sh HISTORY 176.Fn EVP_SignInit , 177.Fn EVP_SignUpdate , 178and 179.Fn EVP_SignFinal 180first appeared in SSLeay 0.5.1 and have been available since 181.Ox 2.4 . 182.Pp 183.Fn EVP_SignInit_ex 184first appeared in OpenSSL 0.9.7 and has been available since 185.Ox 3.2 . 186.Sh BUGS 187Older versions of this documentation wrongly stated that calls to 188.Fn EVP_SignUpdate 189could not be made after calling 190.Fn EVP_SignFinal . 191.Pp 192Since the private key is passed in the call to 193.Fn EVP_SignFinal , 194any error relating to the private key (for example an unsuitable key and 195digest combination) will not be indicated until after potentially large 196amounts of data have been passed through 197.Fn EVP_SignUpdate . 198.Pp 199It is not possible to change the signing parameters using these 200function. 201.Pp 202The previous two bugs are fixed in the newer EVP_DigestSign* function. 203