Following the license change, modify the boilerplates in doc/man3/

[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..f37005d84108885a5fbb4611be0a9598017a961c 100644 (file)
--- a/doc/man3/ECDSA_SIG_new.pod
+++ b/doc/man3/ECDSA_SIG_new.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-ECDSA_SIG_get0, ECDSA_SIG_set0,
+ECDSA_SIG_get0, ECDSA_SIG_get0_r, ECDSA_SIG_get0_s, 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
@@ -15,6 +15,8 @@ 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);
+ 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 i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp);
  ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, long len);
@@ -53,7 +55,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
-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
@@ -76,7 +83,7 @@ created with the private EC key B<eckey>.
 
 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.
@@ -105,7 +112,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
-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.
 
@@ -114,8 +121,13 @@ returned as a newly allocated B<ECDSA_SIG> structure (or NULL on error).
 
 =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_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
@@ -136,35 +148,33 @@ named curve prime256v1 (aka P-256).
 First step: create an EC_KEY object (note: this part is B<not> ECDSA
 specific)
 
- int        ret;
+ int ret;
  ECDSA_SIG *sig;
- EC_KEY    *eckey;
+ EC_KEY *eckey;
+
  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);
- if (sig == NULL) {
-    /* error */
- }
+ if (sig == NULL)
+     /* error */
 
 or using ECDSA_sign():
 
  unsigned char *buffer, *pp;
- int            buf_len;
+ int buf_len;
+
  buf_len = ECDSA_size(eckey);
- buffer  = OPENSSL_malloc(buf_len);
+ buffer = OPENSSL_malloc(buf_len);
  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():
 
@@ -176,13 +186,12 @@ or using ECDSA_verify():
 
 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
 
@@ -191,15 +200,15 @@ ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
 
 =head1 SEE ALSO
 
-L<dsa(3)>,
+L<DSA_new(3)>,
 L<EVP_DigestSignInit(3)>,
 L<EVP_DigestVerifyInit(3)>
 
 =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>.