secure/lib/libcrypto/man/ecdsa.3

   1 .\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.35)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "ecdsa 3"
 132 .TH ecdsa 3 "2017-01-26" "1.0.2k" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, ECDSA_size, ECDSA_sign_setup, ECDSA_sign, ECDSA_sign_ex, ECDSA_verify, ECDSA_do_sign, ECDSA_do_sign_ex, ECDSA_do_verify \- Elliptic Curve Digital Signature Algorithm
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ecdsa.h>
 143 \&
 144 \& ECDSA_SIG*     ECDSA_SIG_new(void);
 145 \& void           ECDSA_SIG_free(ECDSA_SIG *sig);
 146 \& int            i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp);
 147 \& ECDSA_SIG*     d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp,
 148 \&                long len);
 149 \&
 150 \& ECDSA_SIG*     ECDSA_do_sign(const unsigned char *dgst, int dgst_len,
 151 \&                        EC_KEY *eckey);
 152 \& ECDSA_SIG*     ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,
 153 \&                        const BIGNUM *kinv, const BIGNUM *rp,
 154 \&                        EC_KEY *eckey);
 155 \& int            ECDSA_do_verify(const unsigned char *dgst, int dgst_len,
 156 \&                        const ECDSA_SIG *sig, EC_KEY* eckey);
 157 \& int            ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx,
 158 \&                        BIGNUM **kinv, BIGNUM **rp);
 159 \& int            ECDSA_sign(int type, const unsigned char *dgst,
 160 \&                        int dgstlen, unsigned char *sig,
 161 \&                        unsigned int *siglen, EC_KEY *eckey);
 162 \& int            ECDSA_sign_ex(int type, const unsigned char *dgst,
 163 \&                        int dgstlen, unsigned char *sig,
 164 \&                        unsigned int *siglen, const BIGNUM *kinv,
 165 \&                        const BIGNUM *rp, EC_KEY *eckey);
 166 \& int            ECDSA_verify(int type, const unsigned char *dgst,
 167 \&                        int dgstlen, const unsigned char *sig,
 168 \&                        int siglen, EC_KEY *eckey);
 169 \& int            ECDSA_size(const EC_KEY *eckey);
 170 \&
 171 \& const ECDSA_METHOD*    ECDSA_OpenSSL(void);
 172 \& void           ECDSA_set_default_method(const ECDSA_METHOD *meth);
 173 \& const ECDSA_METHOD*    ECDSA_get_default_method(void);
 174 \& int            ECDSA_set_method(EC_KEY *eckey,const ECDSA_METHOD *meth);
 175 \&
 176 \& int            ECDSA_get_ex_new_index(long argl, void *argp,
 177 \&                        CRYPTO_EX_new *new_func,
 178 \&                        CRYPTO_EX_dup *dup_func,
 179 \&                        CRYPTO_EX_free *free_func);
 180 \& int            ECDSA_set_ex_data(EC_KEY *d, int idx, void *arg);
 181 \& void*          ECDSA_get_ex_data(EC_KEY *d, int idx);
 182 .Ve
 183 .SH "DESCRIPTION"
 184 .IX Header "DESCRIPTION"
 185 The \fB\s-1ECDSA_SIG\s0\fR structure consists of two BIGNUMs for the
 186 r and s value of a \s-1ECDSA\s0 signature (see X9.62 or \s-1FIPS 186\-2\s0).
 187 .PP
 188 .Vb 5
 189 \& struct
 190 \&        {
 191 \&        BIGNUM *r;
 192 \&        BIGNUM *s;
 193 \& } ECDSA_SIG;
 194 .Ve
 195 .PP
 196 \&\fIECDSA_SIG_new()\fR allocates a new \fB\s-1ECDSA_SIG\s0\fR structure (note: this
 197 function also allocates the BIGNUMs) and initialize it.
 198 .PP
 199 \&\fIECDSA_SIG_free()\fR frees the \fB\s-1ECDSA_SIG\s0\fR structure \fBsig\fR.
 200 .PP
 201 \&\fIi2d_ECDSA_SIG()\fR creates the \s-1DER\s0 encoding of the \s-1ECDSA\s0 signature
 202 \&\fBsig\fR and writes the encoded signature to \fB*pp\fR (note: if \fBpp\fR
 203 is \s-1NULL \s0\fBi2d_ECDSA_SIG\fR returns the expected length in bytes of
 204 the \s-1DER\s0 encoded signature). \fBi2d_ECDSA_SIG\fR returns the length
 205 of the \s-1DER\s0 encoded signature (or 0 on error).
 206 .PP
 207 \&\fId2i_ECDSA_SIG()\fR decodes a \s-1DER\s0 encoded \s-1ECDSA\s0 signature and returns
 208 the decoded signature in a newly allocated \fB\s-1ECDSA_SIG\s0\fR structure.
 209 \&\fB*sig\fR points to the buffer containing the \s-1DER\s0 encoded signature
 210 of size \fBlen\fR.
 211 .PP
 212 \&\fIECDSA_size()\fR returns the maximum length of a \s-1DER\s0 encoded
 213 \&\s-1ECDSA\s0 signature created with the private \s-1EC\s0 key \fBeckey\fR.
 214 .PP
 215 \&\fIECDSA_sign_setup()\fR may be used to precompute parts of the
 216 signing operation. \fBeckey\fR is the private \s-1EC\s0 key and \fBctx\fR
 217 is a pointer to \fB\s-1BN_CTX\s0\fR structure (or \s-1NULL\s0). The precomputed
 218 values or returned in \fBkinv\fR and \fBrp\fR and can be used in a
 219 later call to \fBECDSA_sign_ex\fR or \fBECDSA_do_sign_ex\fR.
 220 .PP
 221 \&\fIECDSA_sign()\fR is wrapper function for ECDSA_sign_ex with \fBkinv\fR
 222 and \fBrp\fR set to \s-1NULL.\s0
 223 .PP
 224 \&\fIECDSA_sign_ex()\fR computes a digital signature of the \fBdgstlen\fR bytes
 225 hash value \fBdgst\fR using the private \s-1EC\s0 key \fBeckey\fR and the optional
 226 pre-computed values \fBkinv\fR and \fBrp\fR. The \s-1DER\s0 encoded signatures is
 227 stored in \fBsig\fR and it's length is returned in \fBsig_len\fR. Note: \fBsig\fR
 228 must point to \fBECDSA_size\fR bytes of memory. The parameter \fBtype\fR
 229 is ignored.
 230 .PP
 231 \&\fIECDSA_verify()\fR verifies that the signature in \fBsig\fR of size
 232 \&\fBsiglen\fR is a valid \s-1ECDSA\s0 signature of the hash value
 233 \&\fBdgst\fR of size \fBdgstlen\fR using the public key \fBeckey\fR.
 234 The parameter \fBtype\fR is ignored.
 235 .PP
 236 \&\fIECDSA_do_sign()\fR is wrapper function for ECDSA_do_sign_ex with \fBkinv\fR
 237 and \fBrp\fR set to \s-1NULL.\s0
 238 .PP
 239 \&\fIECDSA_do_sign_ex()\fR computes a digital signature of the \fBdgst_len\fR
 240 bytes hash value \fBdgst\fR using the private key \fBeckey\fR and the
 241 optional pre-computed values \fBkinv\fR and \fBrp\fR. The signature is
 242 returned in a newly allocated \fB\s-1ECDSA_SIG\s0\fR structure (or \s-1NULL\s0 on error).
 243 .PP
 244 \&\fIECDSA_do_verify()\fR verifies that the signature \fBsig\fR is a valid
 245 \&\s-1ECDSA\s0 signature of the hash value \fBdgst\fR of size \fBdgst_len\fR
 246 using the public key \fBeckey\fR.
 247 .SH "RETURN VALUES"
 248 .IX Header "RETURN VALUES"
 249 \&\fIECDSA_size()\fR returns the maximum length signature or 0 on error.
 250 .PP
 251 \&\fIECDSA_sign_setup()\fR and \fIECDSA_sign()\fR return 1 if successful or 0
 252 on error.
 253 .PP
 254 \&\fIECDSA_verify()\fR and \fIECDSA_do_verify()\fR return 1 for a valid
 255 signature, 0 for an invalid signature and \-1 on error.
 256 The error codes can be obtained by \fIERR_get_error\fR\|(3).
 257 .SH "EXAMPLES"
 258 .IX Header "EXAMPLES"
 259 Creating a \s-1ECDSA\s0 signature of given \s-1SHA\-1\s0 hash value using the
 260 named curve secp192k1.
 261 .PP
 262 First step: create a \s-1EC_KEY\s0 object (note: this part is \fBnot\fR \s-1ECDSA\s0
 263 specific)
 264 .PP
 265 .Vb 12
 266 \& int        ret;
 267 \& ECDSA_SIG *sig;
 268 \& EC_KEY    *eckey;
 269 \& eckey = EC_KEY_new_by_curve_name(NID_secp192k1);
 270 \& if (eckey == NULL)
 271 \&        {
 272 \&        /* error */
 273 \&        }
 274 \& if (!EC_KEY_generate_key(eckey))
 275 \&        {
 276 \&        /* error */
 277 \&        }
 278 .Ve
 279 .PP
 280 Second step: compute the \s-1ECDSA\s0 signature of a \s-1SHA\-1\s0 hash value
 281 using \fBECDSA_do_sign\fR
 282 .PP
 283 .Vb 5
 284 \& sig = ECDSA_do_sign(digest, 20, eckey);
 285 \& if (sig == NULL)
 286 \&        {
 287 \&        /* error */
 288 \&        }
 289 .Ve
 290 .PP
 291 or using \fBECDSA_sign\fR
 292 .PP
 293 .Vb 9
 294 \& unsigned char *buffer, *pp;
 295 \& int            buf_len;
 296 \& buf_len = ECDSA_size(eckey);
 297 \& buffer  = OPENSSL_malloc(buf_len);
 298 \& pp = buffer;
 299 \& if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey);
 300 \&        {
 301 \&        /* error */
 302 \&        }
 303 .Ve
 304 .PP
 305 Third step: verify the created \s-1ECDSA\s0 signature using \fBECDSA_do_verify\fR
 306 .PP
 307 .Vb 1
 308 \& ret = ECDSA_do_verify(digest, 20, sig, eckey);
 309 .Ve
 310 .PP
 311 or using \fBECDSA_verify\fR
 312 .PP
 313 .Vb 1
 314 \& ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey);
 315 .Ve
 316 .PP
 317 and finally evaluate the return value:
 318 .PP
 319 .Vb 12
 320 \& if (ret == \-1)
 321 \&        {
 322 \&        /* error */
 323 \&        }
 324 \& else if (ret == 0)
 325 \&        {
 326 \&        /* incorrect signature */
 327 \&        }
 328 \& else   /* ret == 1 */
 329 \&        {
 330 \&        /* signature ok */
 331 \&        }
 332 .Ve
 333 .SH "CONFORMING TO"
 334 .IX Header "CONFORMING TO"
 335 \&\s-1ANSI X9.62, US\s0 Federal Information Processing Standard \s-1FIPS 186\-2
 336 \&\s0(Digital Signature Standard, \s-1DSS\s0)
 337 .SH "SEE ALSO"
 338 .IX Header "SEE ALSO"
 339 \&\fIdsa\fR\|(3), \fIrsa\fR\|(3)
 340 .SH "HISTORY"
 341 .IX Header "HISTORY"
 342 The ecdsa implementation was first introduced in OpenSSL 0.9.8
 343 .SH "AUTHOR"
 344 .IX Header "AUTHOR"
 345 Nils Larsch for the OpenSSL project (http://www.openssl.org).