secure/lib/libcrypto/man/man3/EVP_DigestSignInit.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.41)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "EVP_DIGESTSIGNINIT 3"
 136 .TH EVP_DIGESTSIGNINIT 3 "2020-12-08" "1.1.1i" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal, EVP_DigestSign \- EVP signing functions
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/evp.h>
 147 \&
 148 \& int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
 149 \&                        const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
 150 \& int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
 151 \& int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen);
 152 \&
 153 \& int EVP_DigestSign(EVP_MD_CTX *ctx, unsigned char *sigret,
 154 \&                    size_t *siglen, const unsigned char *tbs,
 155 \&                    size_t tbslen);
 156 .Ve
 157 .SH "DESCRIPTION"
 158 .IX Header "DESCRIPTION"
 159 The \s-1EVP\s0 signature routines are a high-level interface to digital signatures.
 160 .PP
 161 \&\fBEVP_DigestSignInit()\fR sets up signing context \fBctx\fR to use digest \fBtype\fR from
 162 \&\s-1ENGINE\s0 \fBe\fR and private key \fBpkey\fR. \fBctx\fR must be created with
 163 \&\fBEVP_MD_CTX_new()\fR before calling this function. If \fBpctx\fR is not \s-1NULL,\s0 the
 164 \&\s-1EVP_PKEY_CTX\s0 of the signing operation will be written to \fB*pctx\fR: this can
 165 be used to set alternative signing options. Note that any existing value in
 166 \&\fB*pctx\fR is overwritten. The \s-1EVP_PKEY_CTX\s0 value returned must not be freed
 167 directly by the application if \fBctx\fR is not assigned an \s-1EVP_PKEY_CTX\s0 value before
 168 being passed to \fBEVP_DigestSignInit()\fR (which means the \s-1EVP_PKEY_CTX\s0 is created
 169 inside \fBEVP_DigestSignInit()\fR and it will be freed automatically when the
 170 \&\s-1EVP_MD_CTX\s0 is freed).
 171 .PP
 172 The digest \fBtype\fR may be \s-1NULL\s0 if the signing algorithm supports it.
 173 .PP
 174 No \fB\s-1EVP_PKEY_CTX\s0\fR will be created by \fBEVP_DigestSignInit()\fR if the passed \fBctx\fR
 175 has already been assigned one via \fBEVP_MD_CTX_set_pkey_ctx\fR\|(3). See also \s-1\fBSM2\s0\fR\|(7).
 176 .PP
 177 Only \s-1EVP_PKEY\s0 types that support signing can be used with these functions. This
 178 includes \s-1MAC\s0 algorithms where the \s-1MAC\s0 generation is considered as a form of
 179 \&\*(L"signing\*(R". Built-in \s-1EVP_PKEY\s0 types supported by these functions are \s-1CMAC,\s0
 180 Poly1305, \s-1DSA, ECDSA, HMAC, RSA,\s0 SipHash, Ed25519 and Ed448.
 181 .PP
 182 Not all digests can be used for all key types. The following combinations apply.
 183 .IP "\s-1DSA\s0" 4
 184 .IX Item "DSA"
 185 Supports \s-1SHA1, SHA224, SHA256, SHA384\s0 and \s-1SHA512\s0
 186 .IP "\s-1ECDSA\s0" 4
 187 .IX Item "ECDSA"
 188 Supports \s-1SHA1, SHA224, SHA256, SHA384, SHA512\s0 and \s-1SM3\s0
 189 .IP "\s-1RSA\s0 with no padding" 4
 190 .IX Item "RSA with no padding"
 191 Supports no digests (the digest \fBtype\fR must be \s-1NULL\s0)
 192 .IP "\s-1RSA\s0 with X931 padding" 4
 193 .IX Item "RSA with X931 padding"
 194 Supports \s-1SHA1, SHA256, SHA384\s0 and \s-1SHA512\s0
 195 .IP "All other \s-1RSA\s0 padding types" 4
 196 .IX Item "All other RSA padding types"
 197 Support \s-1SHA1, SHA224, SHA256, SHA384, SHA512, MD5, MD5_SHA1, MD2, MD4, MDC2,
 198 SHA3\-224, SHA3\-256, SHA3\-384, SHA3\-512\s0
 199 .IP "Ed25519 and Ed448" 4
 200 .IX Item "Ed25519 and Ed448"
 201 Support no digests (the digest \fBtype\fR must be \s-1NULL\s0)
 202 .IP "\s-1HMAC\s0" 4
 203 .IX Item "HMAC"
 204 Supports any digest
 205 .IP "\s-1CMAC,\s0 Poly1305 and SipHash" 4
 206 .IX Item "CMAC, Poly1305 and SipHash"
 207 Will ignore any digest provided.
 208 .PP
 209 If RSA-PSS is used and restrictions apply then the digest must match.
 210 .PP
 211 \&\fBEVP_DigestSignUpdate()\fR hashes \fBcnt\fR bytes of data at \fBd\fR into the
 212 signature context \fBctx\fR. This function can be called several times on the
 213 same \fBctx\fR to include additional data. This function is currently implemented
 214 using a macro.
 215 .PP
 216 \&\fBEVP_DigestSignFinal()\fR signs the data in \fBctx\fR and places the signature in \fBsig\fR.
 217 If \fBsig\fR is \fB\s-1NULL\s0\fR then the maximum size of the output buffer is written to
 218 the \fBsiglen\fR parameter. If \fBsig\fR is not \fB\s-1NULL\s0\fR then before the call the
 219 \&\fBsiglen\fR parameter should contain the length of the \fBsig\fR buffer. If the
 220 call is successful the signature is written to \fBsig\fR and the amount of data
 221 written to \fBsiglen\fR.
 222 .PP
 223 \&\fBEVP_DigestSign()\fR signs \fBtbslen\fR bytes of data at \fBtbs\fR and places the
 224 signature in \fBsig\fR and its length in \fBsiglen\fR in a similar way to
 225 \&\fBEVP_DigestSignFinal()\fR.
 226 .SH "RETURN VALUES"
 227 .IX Header "RETURN VALUES"
 228 \&\fBEVP_DigestSignInit()\fR, \fBEVP_DigestSignUpdate()\fR, \fBEVP_DigestSignFinal()\fR and
 229 \&\fBEVP_DigestSign()\fR return 1 for success and 0 for failure.
 230 .PP
 231 The error codes can be obtained from \fBERR_get_error\fR\|(3).
 232 .SH "NOTES"
 233 .IX Header "NOTES"
 234 The \fB\s-1EVP\s0\fR interface to digital signatures should almost always be used in
 235 preference to the low-level interfaces. This is because the code then becomes
 236 transparent to the algorithm used and much more flexible.
 237 .PP
 238 \&\fBEVP_DigestSign()\fR is a one shot operation which signs a single block of data
 239 in one function. For algorithms that support streaming it is equivalent to
 240 calling \fBEVP_DigestSignUpdate()\fR and \fBEVP_DigestSignFinal()\fR. For algorithms which
 241 do not support streaming (e.g. PureEdDSA) it is the only way to sign data.
 242 .PP
 243 In previous versions of OpenSSL there was a link between message digest types
 244 and public key algorithms. This meant that \*(L"clone\*(R" digests such as \fBEVP_dss1()\fR
 245 needed to be used to sign using \s-1SHA1\s0 and \s-1DSA.\s0 This is no longer necessary and
 246 the use of clone digest is now discouraged.
 247 .PP
 248 For some key types and parameters the random number generator must be seeded.
 249 If the automatic seeding or reseeding of the OpenSSL \s-1CSPRNG\s0 fails due to
 250 external circumstances (see \s-1\fBRAND\s0\fR\|(7)), the operation will fail.
 251 .PP
 252 The call to \fBEVP_DigestSignFinal()\fR internally finalizes a copy of the digest
 253 context. This means that calls to \fBEVP_DigestSignUpdate()\fR and
 254 \&\fBEVP_DigestSignFinal()\fR can be called later to digest and sign additional data.
 255 .PP
 256 Since only a copy of the digest context is ever finalized, the context must
 257 be cleaned up after use by calling \fBEVP_MD_CTX_free()\fR or a memory leak
 258 will occur.
 259 .PP
 260 The use of \fBEVP_PKEY_size()\fR with these functions is discouraged because some
 261 signature operations may have a signature length which depends on the
 262 parameters set. As a result \fBEVP_PKEY_size()\fR would have to return a value
 263 which indicates the maximum possible signature for any set of parameters.
 264 .SH "SEE ALSO"
 265 .IX Header "SEE ALSO"
 266 \&\fBEVP_DigestVerifyInit\fR\|(3),
 267 \&\fBEVP_DigestInit\fR\|(3),
 268 \&\fBevp\fR\|(7), \s-1\fBHMAC\s0\fR\|(3), \s-1\fBMD2\s0\fR\|(3),
 269 \&\s-1\fBMD5\s0\fR\|(3), \s-1\fBMDC2\s0\fR\|(3), \s-1\fBRIPEMD160\s0\fR\|(3),
 270 \&\s-1\fBSHA1\s0\fR\|(3), \fBdgst\fR\|(1),
 271 \&\s-1\fBRAND\s0\fR\|(7)
 272 .SH "HISTORY"
 273 .IX Header "HISTORY"
 274 \&\fBEVP_DigestSignInit()\fR, \fBEVP_DigestSignUpdate()\fR and \fBEVP_DigestSignFinal()\fR
 275 were added in OpenSSL 1.0.0.
 276 .SH "COPYRIGHT"
 277 .IX Header "COPYRIGHT"
 278 Copyright 2006\-2020 The OpenSSL Project Authors. All Rights Reserved.
 279 .PP
 280 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 281 this file except in compliance with the License.  You can obtain a copy
 282 in the file \s-1LICENSE\s0 in the source distribution or at
 283 <https://www.openssl.org/source/license.html>.