secure/lib/libcrypto/man/EVP_SignInit.3

   1 .\" Automatically generated by Pod::Man version 1.15
   2 .\" Thu May  9 13:17:57 2002
   3 .\"
   4 .\" Standard preamble:
   5 .\" ======================================================================
   6 .de Sh \" Subsection heading
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp \" Vertical space (when we can't use .PP)
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip \" List item
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb \" Begin verbatim text
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve \" End verbatim text
  30 .ft R
  31
  32 .fi
  33 ..
  34 .\" Set up some character translations and predefined strings.  \*(-- will
  35 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  36 .\" double quote, and \*(R" will give a right double quote.  | will give a
  37 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
  38 .\" to do unbreakable dashes and therefore won't be available.  \*(C` and
  39 .\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
  40 .tr \(*W-|\(bv\*(Tr
  41 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  42 .ie n \{\
  43 .    ds -- \(*W-
  44 .    ds PI pi
  45 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  46 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  47 .    ds L" ""
  48 .    ds R" ""
  49 .    ds C` ""
  50 .    ds C' ""
  51 'br\}
  52 .el\{\
  53 .    ds -- \|\(em\|
  54 .    ds PI \(*p
  55 .    ds L" ``
  56 .    ds R" ''
  57 'br\}
  58 .\"
  59 .\" If the F register is turned on, we'll generate index entries on stderr
  60 .\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
  61 .\" index entries marked with X<> in POD.  Of course, you'll have to process
  62 .\" the output yourself in some meaningful fashion.
  63 .if \nF \{\
  64 .    de IX
  65 .    tm Index:\\$1\t\\n%\t"\\$2"
  66 ..
  67 .    nr % 0
  68 .    rr F
  69 .\}
  70 .\"
  71 .\" For nroff, turn off justification.  Always turn off hyphenation; it
  72 .\" makes way too many mistakes in technical documents.
  73 .hy 0
  74 .if n .na
  75 .\"
  76 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  77 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  78 .bd B 3
  79 .    \" fudge factors for nroff and troff
  80 .if n \{\
  81 .    ds #H 0
  82 .    ds #V .8m
  83 .    ds #F .3m
  84 .    ds #[ \f1
  85 .    ds #] \fP
  86 .\}
  87 .if t \{\
  88 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  89 .    ds #V .6m
  90 .    ds #F 0
  91 .    ds #[ \&
  92 .    ds #] \&
  93 .\}
  94 .    \" simple accents for nroff and troff
  95 .if n \{\
  96 .    ds ' \&
  97 .    ds ` \&
  98 .    ds ^ \&
  99 .    ds , \&
 100 .    ds ~ ~
 101 .    ds /
 102 .\}
 103 .if t \{\
 104 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 105 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 106 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 107 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 108 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 109 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 110 .\}
 111 .    \" troff and (daisy-wheel) nroff accents
 112 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 113 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 114 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 115 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 116 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 117 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 118 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 119 .ds ae a\h'-(\w'a'u*4/10)'e
 120 .ds Ae A\h'-(\w'A'u*4/10)'E
 121 .    \" corrections for vroff
 122 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 123 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 124 .    \" for low resolution devices (crt and lpr)
 125 .if \n(.H>23 .if \n(.V>19 \
 126 \{\
 127 .    ds : e
 128 .    ds 8 ss
 129 .    ds o a
 130 .    ds d- d\h'-1'\(ga
 131 .    ds D- D\h'-1'\(hy
 132 .    ds th \o'bp'
 133 .    ds Th \o'LP'
 134 .    ds ae ae
 135 .    ds Ae AE
 136 .\}
 137 .rm #[ #] #H #V #F C
 138 .\" ======================================================================
 139 .\"
 140 .IX Title "EVP_SIGNINIT 1"
 141 .TH EVP_SIGNINIT 1 "perl v5.6.1" "2000-11-13" "User Contributed Perl Documentation"
 142 .UC
 143 .SH "NAME"
 144 EVP_SignInit, EVP_SignUpdate, EVP_SignFinal \- \s-1EVP\s0 signing functions
 145 .SH "SYNOPSIS"
 146 .IX Header "SYNOPSIS"
 147 .Vb 1
 148 \& #include <openssl/evp.h>
 149 .Ve
 150 .Vb 3
 151 \& void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);
 152 \& void EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
 153 \& int EVP_SignFinal(EVP_MD_CTX *ctx,unsigned char *sig,unsigned int *s, EVP_PKEY *pkey);
 154 .Ve
 155 .Vb 1
 156 \& int EVP_PKEY_size(EVP_PKEY *pkey);
 157 .Ve
 158 .SH "DESCRIPTION"
 159 .IX Header "DESCRIPTION"
 160 The \s-1EVP\s0 signature routines are a high level interface to digital
 161 signatures.
 162 .PP
 163 \&\fIEVP_SignInit()\fR initializes a signing context \fBctx\fR to using digest
 164 \&\fBtype\fR: this will typically be supplied by a function such as
 165 \&\fIEVP_sha1()\fR.
 166 .PP
 167 \&\fIEVP_SignUpdate()\fR hashes \fBcnt\fR bytes of data at \fBd\fR into the
 168 signature context \fBctx\fR. This function can be called several times on the
 169 same \fBctx\fR to include additional data.
 170 .PP
 171 \&\fIEVP_SignFinal()\fR signs the data in \fBctx\fR using the private key \fBpkey\fR
 172 and places the signature in \fBsig\fR. If the \fBs\fR parameter is not \s-1NULL\s0
 173 then the number of bytes of data written (i.e. the length of the signature)
 174 will be written to the integer at \fBs\fR, at most EVP_PKEY_size(pkey) bytes
 175 will be written.  After calling \fIEVP_SignFinal()\fR no additional calls to
 176 \&\fIEVP_SignUpdate()\fR can be made, but \fIEVP_SignInit()\fR can be called to initialize
 177 a new signature operation.
 178 .PP
 179 \&\fIEVP_PKEY_size()\fR returns the maximum size of a signature in bytes. The actual
 180 signature returned by \fIEVP_SignFinal()\fR may be smaller.
 181 .SH "RETURN VALUES"
 182 .IX Header "RETURN VALUES"
 183 \&\fIEVP_SignInit()\fR and \fIEVP_SignUpdate()\fR do not return values.
 184 .PP
 185 \&\fIEVP_SignFinal()\fR returns 1 for success and 0 for failure.
 186 .PP
 187 \&\fIEVP_PKEY_size()\fR returns the maximum size of a signature in bytes.
 188 .PP
 189 The error codes can be obtained by ERR_get_error(3).
 190 .SH "NOTES"
 191 .IX Header "NOTES"
 192 The \fB\s-1EVP\s0\fR interface to digital signatures should almost always be used in
 193 preference to the low level interfaces. This is because the code then becomes
 194 transparent to the algorithm used and much more flexible.
 195 .PP
 196 Due to the link between message digests and public key algorithms the correct
 197 digest algorithm must be used with the correct public key type. A list of
 198 algorithms and associated public key algorithms appears in
 199 EVP_DigestInit(3).
 200 .PP
 201 When signing with \s-1DSA\s0 private keys the random number generator must be seeded
 202 or the operation will fail. The random number generator does not need to be
 203 seeded for \s-1RSA\s0 signatures.
 204 .SH "BUGS"
 205 .IX Header "BUGS"
 206 Several of the functions do not return values: maybe they should. Although the
 207 internal digest operations will never fail some future hardware based operations
 208 might.
 209 .SH "SEE ALSO"
 210 .IX Header "SEE ALSO"
 211 EVP_VerifyInit(3),
 212 EVP_DigestInit(3), err(3),
 213 evp(3), hmac(3), md2(3),
 214 md5(3), mdc2(3), ripemd(3),
 215 sha(3), digest(1)
 216 .SH "HISTORY"
 217 .IX Header "HISTORY"
 218 \&\fIEVP_SignInit()\fR, \fIEVP_SignUpdate()\fR and \fIEVP_SignFinal()\fR are
 219 available in all versions of SSLeay and OpenSSL.