ecdsa.pod 5.9 KB

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