doc/crypto/ecdsa.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 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
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/ecdsa.h>
  10
  11  ECDSA_SIG*     ECDSA_SIG_new(void);
  12  void           ECDSA_SIG_free(ECDSA_SIG *sig);
  13  int            i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp);
  14  ECDSA_SIG*     d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp,
  15                 long len);
  16
  17  ECDSA_SIG*     ECDSA_do_sign(const unsigned char *dgst, int dgst_len,
  18                         EC_KEY *eckey);
  19  ECDSA_SIG*     ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,
  20                         const BIGNUM *kinv, const BIGNUM *rp,
  21                         EC_KEY *eckey);
  22  int            ECDSA_do_verify(const unsigned char *dgst, int dgst_len,
  23                         const ECDSA_SIG *sig, EC_KEY* eckey);
  24  int            ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx,
  25                         BIGNUM **kinv, BIGNUM **rp);
  26  int            ECDSA_sign(int type, const unsigned char *dgst,
  27                         int dgstlen, unsigned char *sig,
  28                         unsigned int *siglen, EC_KEY *eckey);
  29  int            ECDSA_sign_ex(int type, const unsigned char *dgst,
  30                         int dgstlen, unsigned char *sig,
  31                         unsigned int *siglen, const BIGNUM *kinv,
  32                         const BIGNUM *rp, EC_KEY *eckey);
  33  int            ECDSA_verify(int type, const unsigned char *dgst,
  34                         int dgstlen, const unsigned char *sig,
  35                         int siglen, EC_KEY *eckey);
  36  int            ECDSA_size(const EC_KEY *eckey);
  37
  38  const ECDSA_METHOD*    ECDSA_OpenSSL(void);
  39  void           ECDSA_set_default_method(const ECDSA_METHOD *meth);
  40  const ECDSA_METHOD*    ECDSA_get_default_method(void);
  41  int            ECDSA_set_method(EC_KEY *eckey,const ECDSA_METHOD *meth);
  42
  43 =head1 DESCRIPTION
  44
  45 The B<ECDSA_SIG> structure consists of two BIGNUMs for the
  46 r and s value of a ECDSA signature (see X9.62 or FIPS 186-2).
  47
  48  struct
  49         {
  50         BIGNUM *r;
  51         BIGNUM *s;
  52  } ECDSA_SIG;
  53
  54 ECDSA_SIG_new() allocates a new B<ECDSA_SIG> structure (note: this
  55 function also allocates the BIGNUMs) and initialize it.
  56
  57 ECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>.
  58
  59 i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature
  60 B<sig> and writes the encoded signature to B<*pp> (note: if B<pp>
  61 is NULL B<i2d_ECDSA_SIG> returns the expected length in bytes of
  62 the DER encoded signature). B<i2d_ECDSA_SIG> returns the length
  63 of the DER encoded signature (or 0 on error).
  64
  65 d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns
  66 the decoded signature in a newly allocated B<ECDSA_SIG> structure.
  67 B<*sig> points to the buffer containing the DER encoded signature
  68 of size B<len>.
  69
  70 ECDSA_size() returns the maximum length of a DER encoded
  71 ECDSA signature created with the private EC key B<eckey>.
  72
  73 ECDSA_sign_setup() may be used to precompute parts of the
  74 signing operation. B<eckey> is the private EC key and B<ctx>
  75 is a pointer to B<BN_CTX> structure (or NULL). The precomputed
  76 values or returned in B<kinv> and B<rp> and can be used in a
  77 later call to B<ECDSA_sign_ex> or B<ECDSA_do_sign_ex>.
  78
  79 ECDSA_sign() is wrapper function for ECDSA_sign_ex with B<kinv>
  80 and B<rp> set to NULL.
  81
  82 ECDSA_sign_ex() computes a digital signature of the B<dgstlen> bytes
  83 hash value B<dgst> using the private EC key B<eckey> and the optional
  84 pre-computed values B<kinv> and B<rp>. The DER encoded signatures is
  85 stored in B<sig> and it's length is returned in B<sig_len>. Note: B<sig>
  86 must point to B<ECDSA_size> bytes of memory. The parameter B<type>
  87 is ignored.
  88
  89 ECDSA_verify() verifies that the signature in B<sig> of size
  90 B<siglen> is a valid ECDSA signature of the hash value
  91 B<dgst> of size B<dgstlen> using the public key B<eckey>.
  92 The parameter B<type> is ignored.
  93
  94 ECDSA_do_sign() is wrapper function for ECDSA_do_sign_ex with B<kinv>
  95 and B<rp> set to NULL.
  96
  97 ECDSA_do_sign_ex() computes a digital signature of the B<dgst_len>
  98 bytes hash value B<dgst> using the private key B<eckey> and the
  99 optional pre-computed values B<kinv> and B<rp>. The signature is
 100 returned in a newly allocated B<ECDSA_SIG> structure (or NULL on error).
 101
 102 ECDSA_do_verify() verifies that the signature B<sig> is a valid
 103 ECDSA signature of the hash value B<dgst> of size B<dgst_len>
 104 using the public key B<eckey>.
 105
 106 =head1 RETURN VALUES
 107
 108 ECDSA_size() returns the maximum length signature or 0 on error.
 109
 110 ECDSA_sign_setup() and ECDSA_sign() return 1 if successful or 0
 111 on error.
 112
 113 ECDSA_verify() and ECDSA_do_verify() return 1 for a valid
 114 signature, 0 for an invalid signature and -1 on error.
 115 The error codes can be obtained by L<ERR_get_error(3)>.
 116
 117 =head1 EXAMPLES
 118
 119 Creating a ECDSA signature of given SHA-1 hash value using the
 120 named curve secp192k1.
 121
 122 First step: create a EC_KEY object (note: this part is B<not> ECDSA
 123 specific)
 124
 125  int        ret;
 126  ECDSA_SIG *sig;
 127  EC_KEY    *eckey;
 128  eckey = EC_KEY_new_by_curve_name(NID_secp192k1);
 129  if (eckey == NULL)
 130         {
 131         /* error */
 132         }
 133  if (!EC_KEY_generate_key(eckey))
 134         {
 135         /* error */
 136         }
 137
 138 Second step: compute the ECDSA signature of a SHA-1 hash value
 139 using B<ECDSA_do_sign>
 140
 141  sig = ECDSA_do_sign(digest, 20, eckey);
 142  if (sig == NULL)
 143         {
 144         /* error */
 145         }
 146
 147 or using B<ECDSA_sign>
 148
 149  unsigned char *buffer, *pp;
 150  int            buf_len;
 151  buf_len = ECDSA_size(eckey);
 152  buffer  = OPENSSL_malloc(buf_len);
 153  pp = buffer;
 154  if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey);
 155         {
 156         /* error */
 157         }
 158
 159 Third step: verify the created ECDSA signature using B<ECDSA_do_verify>
 160
 161  ret = ECDSA_do_verify(digest, 20, sig, eckey);
 162
 163 or using B<ECDSA_verify>
 164
 165  ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey);
 166
 167 and finally evaluate the return value:
 168
 169  if (ret == -1)
 170         {
 171         /* error */
 172         }
 173  else if (ret == 0)
 174         {
 175         /* incorrect signature */
 176         }
 177  else   /* ret == 1 */
 178         {
 179         /* signature ok */
 180         }
 181
 182 =head1 CONFORMING TO
 183
 184 ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
 185 (Digital Signature Standard, DSS)
 186
 187 =head1 SEE ALSO
 188
 189 L<dsa(3)>, L<rsa(3)>
 190
 191 =cut