secure/lib/libcrypto/man/EVP_SignInit.3

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  34 '''
  35 '''
  36 '''     Set up \*(-- to give an unbreakable dash;
  37 '''     string Tr holds user defined translation string.
  38 '''     Bell System Logo is used as a dummy character.
  39 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  42 .ds -- \(*W-
  43 .ds PI pi
  44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
  46 .ds L" ""
  47 .ds R" ""
  48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
  49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
  50 '''   such as .IP and .SH, which do another additional levels of
  51 '''   double-quote interpretation
  52 .ds M" """
  53 .ds S" """
  54 .ds N" """""
  55 .ds T" """""
  56 .ds L' '
  57 .ds R' '
  58 .ds M' '
  59 .ds S' '
  60 .ds N' '
  61 .ds T' '
  62 'br\}
  63 .el\{\
  64 .ds -- \(em\|
  65 .tr \*(Tr
  66 .ds L" ``
  67 .ds R" ''
  68 .ds M" ``
  69 .ds S" ''
  70 .ds N" ``
  71 .ds T" ''
  72 .ds L' `
  73 .ds R' '
  74 .ds M' `
  75 .ds S' '
  76 .ds N' `
  77 .ds T' '
  78 .ds PI \(*p
  79 'br\}
  80 .\"     If the F register is turned on, we'll generate
  81 .\"     index entries out stderr for the following things:
  82 .\"             TH      Title
  83 .\"             SH      Header
  84 .\"             Sh      Subsection
  85 .\"             Ip      Item
  86 .\"             X<>     Xref  (embedded
  87 .\"     Of course, you have to process the output yourself
  88 .\"     in some meaninful fashion.
  89 .if \nF \{
  90 .de IX
  91 .tm Index:\\$1\t\\n%\t"\\$2"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH EVP_SignInit 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 101 .de CQ          \" put $1 in typewriter font
 102 .ft CW
 103 'if n "\c
 104 'if t \\&\\$1\c
 105 'if n \\&\\$1\c
 106 'if n \&"
 107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
 108 '.ft R
 109 ..
 110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
 111 .       \" AM - accent mark definitions
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
 147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
 148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
 150 .\}
 151 .       \" troff and (daisy-wheel) nroff accents
 152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
 155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
 156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
 157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
 158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 163 .ds ae a\h'-(\w'a'u*4/10)'e
 164 .ds Ae A\h'-(\w'A'u*4/10)'E
 165 .ds oe o\h'-(\w'o'u*4/10)'e
 166 .ds Oe O\h'-(\w'O'u*4/10)'E
 167 .       \" corrections for vroff
 168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 170 .       \" for low resolution devices (crt and lpr)
 171 .if \n(.H>23 .if \n(.V>19 \
 172 \{\
 173 .       ds : e
 174 .       ds 8 ss
 175 .       ds v \h'-1'\o'\(aa\(ga'
 176 .       ds _ \h'-1'^
 177 .       ds . \h'-1'.
 178 .       ds 3 3
 179 .       ds o a
 180 .       ds d- d\h'-1'\(ga
 181 .       ds D- D\h'-1'\(hy
 182 .       ds th \o'bp'
 183 .       ds Th \o'LP'
 184 .       ds ae ae
 185 .       ds Ae AE
 186 .       ds oe oe
 187 .       ds Oe OE
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 191 EVP_SignInit, EVP_SignUpdate, EVP_SignFinal \- EVP signing functions
 192 .SH "SYNOPSIS"
 193 .PP
 194 .Vb 1
 195 \& #include <openssl/evp.h>
 196 .Ve
 197 .Vb 3
 198 \& int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
 199 \& int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
 200 \& int EVP_SignFinal(EVP_MD_CTX *ctx,unsigned char *sig,unsigned int *s, EVP_PKEY *pkey);
 201 .Ve
 202 .Vb 1
 203 \& void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);
 204 .Ve
 205 .Vb 1
 206 \& int EVP_PKEY_size(EVP_PKEY *pkey);
 207 .Ve
 208 .SH "DESCRIPTION"
 209 The EVP signature routines are a high level interface to digital
 210 signatures.
 211 .PP
 212 \fIEVP_SignInit_ex()\fR sets up signing context \fBctx\fR to use digest
 213 \fBtype\fR from ENGINE \fBimpl\fR. \fBctx\fR must be initialized with
 214 \fIEVP_MD_CTX_init()\fR before calling this function.
 215 .PP
 216 \fIEVP_SignUpdate()\fR hashes \fBcnt\fR bytes of data at \fBd\fR into the
 217 signature context \fBctx\fR. This function can be called several times on the
 218 same \fBctx\fR to include additional data.
 219 .PP
 220 \fIEVP_SignFinal()\fR signs the data in \fBctx\fR using the private key \fBpkey\fR
 221 and places the signature in \fBsig\fR. If the \fBs\fR parameter is not NULL
 222 then the number of bytes of data written (i.e. the length of the signature)
 223 will be written to the integer at \fBs\fR, at most \fIEVP_PKEY_size\fR\|(pkey) bytes
 224 will be written.
 225 .PP
 226 \fIEVP_SignInit()\fR initializes a signing context \fBctx\fR to use the default
 227 implementation of digest \fBtype\fR.
 228 .PP
 229 \fIEVP_PKEY_size()\fR returns the maximum size of a signature in bytes. The actual
 230 signature returned by \fIEVP_SignFinal()\fR may be smaller.
 231 .SH "RETURN VALUES"
 232 \fIEVP_SignInit_ex()\fR, \fIEVP_SignUpdate()\fR and \fIEVP_SignFinal()\fR return 1
 233 for success and 0 for failure.
 234 .PP
 235 \fIEVP_PKEY_size()\fR returns the maximum size of a signature in bytes.
 236 .PP
 237 The error codes can be obtained by ERR_get_error(3).
 238 .SH "NOTES"
 239 The \fBEVP\fR interface to digital signatures should almost always be used in
 240 preference to the low level interfaces. This is because the code then becomes
 241 transparent to the algorithm used and much more flexible.
 242 .PP
 243 Due to the link between message digests and public key algorithms the correct
 244 digest algorithm must be used with the correct public key type. A list of
 245 algorithms and associated public key algorithms appears in
 246 EVP_DigestInit(3).
 247 .PP
 248 When signing with DSA private keys the random number generator must be seeded
 249 or the operation will fail. The random number generator does not need to be
 250 seeded for RSA signatures.
 251 .PP
 252 The call to \fIEVP_SignFinal()\fR internally finalizes a copy of the digest context.
 253 This means that calls to \fIEVP_SignUpdate()\fR and \fIEVP_SignFinal()\fR can be called
 254 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 \fIEVP_MD_CTX_cleanup()\fR or a memory leak
 258 will occur.
 259 .SH "BUGS"
 260 Older versions of this documentation wrongly stated that calls to
 261 \fIEVP_SignUpdate()\fR could not be made after calling \fIEVP_SignFinal()\fR.
 262 .SH "SEE ALSO"
 263 EVP_VerifyInit(3),
 264 EVP_DigestInit(3), err(3),
 265 evp(3), hmac(3), md2(3),
 266 md5(3), mdc2(3), ripemd(3),
 267 sha(3), dgst(1)
 268 .SH "HISTORY"
 269 \fIEVP_SignInit()\fR, \fIEVP_SignUpdate()\fR and \fIEVP_SignFinal()\fR are
 270 available in all versions of SSLeay and OpenSSL.
 271 .PP
 272 \fIEVP_SignInit_ex()\fR was added in OpenSSL 0.9.7.
 273
 274 .rn }` ''
 275 .IX Title "EVP_SignInit 3"
 276 .IX Name "EVP_SignInit, EVP_SignUpdate, EVP_SignFinal - EVP signing functions"
 277
 278 .IX Header "NAME"
 279
 280 .IX Header "SYNOPSIS"
 281
 282 .IX Header "DESCRIPTION"
 283
 284 .IX Header "RETURN VALUES"
 285
 286 .IX Header "NOTES"
 287
 288 .IX Header "BUGS"
 289
 290 .IX Header "SEE ALSO"
 291
 292 .IX Header "HISTORY"
 293