projects / openssl.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Expand the XTS documentation
[openssl.git] / doc / man3 / ECDSA_SIG_new.pod
diff --git a/doc/man3/ECDSA_SIG_new.pod b/doc/man3/ECDSA_SIG_new.pod
index f6aaed192be67ea8cb5240fd9e299017708899b7..4364297e6fde4535014c3db613b269e4a41cdcf9 100644 (file)
--- a/doc/man3/ECDSA_SIG_new.pod
+++ b/doc/man3/ECDSA_SIG_new.pod
@@ -2,11 +2,11 @@
 
 =head1 NAME
 
 
 =head1 NAME
 
-ECDSA_SIG_get0, ECDSA_SIG_set0,
-ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, ECDSA_size,
-ECDSA_sign, ECDSA_do_sign, ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup,
-ECDSA_sign_ex, ECDSA_do_sign_ex - low level elliptic curve digital signature
-algorithm (ECDSA) functions
+ECDSA_SIG_get0, ECDSA_SIG_get0_r, ECDSA_SIG_get0_s, ECDSA_SIG_set0,
+ECDSA_SIG_new, ECDSA_SIG_free, ECDSA_size, ECDSA_sign, ECDSA_do_sign,
+ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup, ECDSA_sign_ex,
+ECDSA_do_sign_ex - low level elliptic curve digital signature algorithm (ECDSA)
+functions
 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 
@@ -15,9 +15,14 @@ algorithm (ECDSA) functions
  ECDSA_SIG *ECDSA_SIG_new(void);
  void ECDSA_SIG_free(ECDSA_SIG *sig);
  void ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps);
  ECDSA_SIG *ECDSA_SIG_new(void);
  void ECDSA_SIG_free(ECDSA_SIG *sig);
  void ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps);
+ const BIGNUM *ECDSA_SIG_get0_r(const ECDSA_SIG *sig);
+ const BIGNUM *ECDSA_SIG_get0_s(const ECDSA_SIG *sig);
  int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s);
  int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s);
- int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp);
- ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, long len);
+
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  int ECDSA_size(const EC_KEY *eckey);
 
  int ECDSA_sign(int type, const unsigned char *dgst, int dgstlen,
  int ECDSA_size(const EC_KEY *eckey);
 
  int ECDSA_sign(int type, const unsigned char *dgst, int dgstlen,
@@ -40,10 +45,6 @@ algorithm (ECDSA) functions
 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 
-Note: these functions provide a low level interface to ECDSA. Most
-applications should use the higher level B<EVP> interface such as
-L<EVP_DigestSignInit(3)> or L<EVP_DigestVerifyInit(3)> instead.
-
 B<ECDSA_SIG> is an opaque structure consisting of two BIGNUMs for the
 B<r> and B<s> value of an ECDSA signature (see X9.62 or FIPS 186-2).
 
 B<ECDSA_SIG> is an opaque structure consisting of two BIGNUMs for the
 B<r> and B<s> value of an ECDSA signature (see X9.62 or FIPS 186-2).
 
@@ -53,7 +54,12 @@ OpenSSL 1.1.0 the: the B<r> and B<s> components were initialised.
 ECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>.
 
 ECDSA_SIG_get0() returns internal pointers the B<r> and B<s> values contained
 ECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>.
 
 ECDSA_SIG_get0() returns internal pointers the B<r> and B<s> values contained
-in B<sig>.
+in B<sig> and stores them in B<*pr> and B<*ps>, respectively.
+The pointer B<pr> or B<ps> can be NULL, in which case the corresponding value
+is not returned.
+
+The values B<r>, B<s> can also be retrieved separately by the corresponding
+function ECDSA_SIG_get0_r() and ECDSA_SIG_get0_s(), respectively.
 
 The B<r> and B<s> values can be set by calling ECDSA_SIG_set0() and passing the
 new values for B<r> and B<s> as parameters to the function. Calling this
 
 The B<r> and B<s> values can be set by calling ECDSA_SIG_set0() and passing the
 new values for B<r> and B<s> as parameters to the function. Calling this
@@ -61,22 +67,20 @@ function transfers the memory management of the values to the ECDSA_SIG object,
 and therefore the values that have been passed in should not be freed directly
 after this function has been called.
 
 and therefore the values that have been passed in should not be freed directly
 after this function has been called.
 
-i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature B<sig> and
-writes the encoded signature to B<*pp> (note: if B<pp> is NULL i2d_ECDSA_SIG()
-returns the expected length in bytes of the DER encoded signature).
-i2d_ECDSA_SIG() returns the length of the DER encoded signature (or 0 on
-error).
+See L<i2d_ECDSA_SIG(3)> and L<d2i_ECDSA_SIG(3)> for information about encoding
+and decoding ECDSA signatures to/from DER.
 
 
-d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns the decoded
-signature in a newly allocated B<ECDSA_SIG> structure. B<*sig> points to the
-buffer containing the DER encoded signature of size B<len>.
+All of the functions described below are deprecated. Applications should
+use the higher level B<EVP> interface such as L<EVP_DigestSignInit(3)>
+or L<EVP_DigestVerifyInit(3)> instead.
 
 ECDSA_size() returns the maximum length of a DER encoded ECDSA signature
 
 ECDSA_size() returns the maximum length of a DER encoded ECDSA signature
-created with the private EC key B<eckey>.
+created with the private EC key B<eckey>. To obtain the actual signature
+size use L<EVP_PKEY_sign(3)> with a NULL B<sig> parameter.
 
 ECDSA_sign() computes a digital signature of the B<dgstlen> bytes hash value
 B<dgst> using the private EC key B<eckey>. The DER encoded signatures is
 
 ECDSA_sign() computes a digital signature of the B<dgstlen> bytes hash value
 B<dgst> using the private EC key B<eckey>. The DER encoded signatures is
-stored in B<sig> and it's length is returned in B<sig_len>. Note: B<sig> must
+stored in B<sig> and its length is returned in B<sig_len>. Note: B<sig> must
 point to ECDSA_size(eckey) bytes of memory. The parameter B<type> is currently
 ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with B<kinv>
 and B<rp> set to NULL.
 point to ECDSA_size(eckey) bytes of memory. The parameter B<type> is currently
 ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with B<kinv>
 and B<rp> set to NULL.
@@ -105,7 +109,7 @@ used in a later call to ECDSA_sign_ex() or ECDSA_do_sign_ex().
 
 ECDSA_sign_ex() computes a digital signature of the B<dgstlen> bytes hash value
 B<dgst> using the private EC key B<eckey> and the optional pre-computed values
 
 ECDSA_sign_ex() computes a digital signature of the B<dgstlen> bytes hash value
 B<dgst> using the private EC key B<eckey> and the optional pre-computed values
-B<kinv> and B<rp>. The DER encoded signatures is stored in B<sig> and it's
+B<kinv> and B<rp>. The DER encoded signature is stored in B<sig> and its
 length is returned in B<sig_len>. Note: B<sig> must point to ECDSA_size(eckey)
 bytes of memory. The parameter B<type> is ignored.
 
 length is returned in B<sig_len>. Note: B<sig> must point to ECDSA_size(eckey)
 bytes of memory. The parameter B<type> is ignored.
 
@@ -114,8 +118,13 @@ returned as a newly allocated B<ECDSA_SIG> structure (or NULL on error).
 
 =head1 RETURN VALUES
 
 
 =head1 RETURN VALUES
 
+ECDSA_SIG_new() returns NULL if the allocation fails.
+
 ECDSA_SIG_set0() returns 1 on success or 0 on failure.
 
 ECDSA_SIG_set0() returns 1 on success or 0 on failure.
 
+ECDSA_SIG_get0_r() and ECDSA_SIG_get0_s() return the corresponding value,
+or NULL if it is unset.
+
 ECDSA_size() returns the maximum length signature or 0 on error.
 
 ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if successful
 ECDSA_size() returns the maximum length signature or 0 on error.
 
 ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if successful
@@ -136,35 +145,33 @@ named curve prime256v1 (aka P-256).
 First step: create an EC_KEY object (note: this part is B<not> ECDSA
 specific)
 
 First step: create an EC_KEY object (note: this part is B<not> ECDSA
 specific)
 
- int        ret;
+ int ret;
  ECDSA_SIG *sig;
  ECDSA_SIG *sig;
- EC_KEY    *eckey;
+ EC_KEY *eckey;
+
  eckey = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1);
  eckey = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1);
- if (eckey == NULL) {
-    /* error */
- }
- if (EC_KEY_generate_key(eckey) == 0) {
-    /* error */
- }
+ if (eckey == NULL)
+     /* error */
+ if (EC_KEY_generate_key(eckey) == 0)
+     /* error */
 
 Second step: compute the ECDSA signature of a SHA-256 hash value
 using ECDSA_do_sign():
 
  sig = ECDSA_do_sign(digest, 32, eckey);
 
 Second step: compute the ECDSA signature of a SHA-256 hash value
 using ECDSA_do_sign():
 
  sig = ECDSA_do_sign(digest, 32, eckey);
- if (sig == NULL) {
-    /* error */
- }
+ if (sig == NULL)
+     /* error */
 
 or using ECDSA_sign():
 
  unsigned char *buffer, *pp;
 
 or using ECDSA_sign():
 
  unsigned char *buffer, *pp;
- int            buf_len;
+ int buf_len;
+
  buf_len = ECDSA_size(eckey);
  buf_len = ECDSA_size(eckey);
- buffer  = OPENSSL_malloc(buf_len);
+ buffer = OPENSSL_malloc(buf_len);
  pp = buffer;
  pp = buffer;
- if (ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) == 0) {
-    /* error */
- }
+ if (ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) == 0)
+     /* error */
 
 Third step: verify the created ECDSA signature using ECDSA_do_verify():
 
 
 Third step: verify the created ECDSA signature using ECDSA_do_verify():
 
@@ -176,13 +183,12 @@ or using ECDSA_verify():
 
 and finally evaluate the return value:
 
 
 and finally evaluate the return value:
 
- if (ret == 1) {
-    /* signature ok */
- } else if (ret == 0) {
-    /* incorrect signature */
- } else {
-    /* error */
- }
+ if (ret == 1)
+     /* signature ok */
+ else if (ret == 0)
+     /* incorrect signature */
+ else
+     /* error */
 
 =head1 CONFORMING TO
 
 
 =head1 CONFORMING TO
 
@@ -191,15 +197,24 @@ ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
 
 =head1 SEE ALSO
 
 
 =head1 SEE ALSO
 
-L<dsa(3)>,
+L<EC_KEY_new(3)>,
 L<EVP_DigestSignInit(3)>,
 L<EVP_DigestSignInit(3)>,
-L<EVP_DigestVerifyInit(3)>
+L<EVP_DigestVerifyInit(3)>,
+L<EVP_PKEY_sign(3)>
+L<i2d_ECDSA_SIG(3)>,
+L<d2i_ECDSA_SIG(3)>
+
+=head1 HISTORY
+
+The ECDSA_size(), ECDSA_sign(), ECDSA_do_sign(), ECDSA_verify(),
+ECDSA_do_verify(), ECDSA_sign_setup(), ECDSA_sign_ex() and ECDSA_do_sign_ex()
+functions were deprecated in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 
-Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2004-2018 The OpenSSL Project Authors. All Rights Reserved.
 
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.
Unnamed repository; edit this file 'description' to name the repository.