X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FECDSA_SIG_new.pod;h=4364297e6fde4535014c3db613b269e4a41cdcf9;hp=f6aaed192be67ea8cb5240fd9e299017708899b7;hb=70d80ef9898ddbe03841efd2df2f526b71829d7f;hpb=99d63d4662e16afbeff49f29b48f1c87d5558ed0 diff --git a/doc/man3/ECDSA_SIG_new.pod b/doc/man3/ECDSA_SIG_new.pod index f6aaed192b..4364297e6f 100644 --- a/doc/man3/ECDSA_SIG_new.pod +++ b/doc/man3/ECDSA_SIG_new.pod @@ -2,11 +2,11 @@ =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 @@ -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); + 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); + +Deprecated since OpenSSL 3.0, can be hidden entirely by defining +B with a suitable version value, see +L: + 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 -Note: these functions provide a low level interface to ECDSA. Most -applications should use the higher level B interface such as -L or L instead. - B is an opaque structure consisting of two BIGNUMs for the B and B value of an ECDSA signature (see X9.62 or FIPS 186-2). @@ -53,7 +54,12 @@ OpenSSL 1.1.0 the: the B and B components were initialised. ECDSA_SIG_free() frees the B structure B. ECDSA_SIG_get0() returns internal pointers the B and B values contained -in B. +in B and stores them in B<*pr> and B<*ps>, respectively. +The pointer B or B can be NULL, in which case the corresponding value +is not returned. + +The values B, B can also be retrieved separately by the corresponding +function ECDSA_SIG_get0_r() and ECDSA_SIG_get0_s(), respectively. The B and B values can be set by calling ECDSA_SIG_set0() and passing the new values for B and B 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. -i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature B and -writes the encoded signature to B<*pp> (note: if B 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 and L 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 structure. B<*sig> points to the -buffer containing the DER encoded signature of size B. +All of the functions described below are deprecated. Applications should +use the higher level B interface such as L +or L instead. ECDSA_size() returns the maximum length of a DER encoded ECDSA signature -created with the private EC key B. +created with the private EC key B. To obtain the actual signature +size use L with a NULL B parameter. ECDSA_sign() computes a digital signature of the B bytes hash value B using the private EC key B. The DER encoded signatures is -stored in B and it's length is returned in B. Note: B must +stored in B and its length is returned in B. Note: B must point to ECDSA_size(eckey) bytes of memory. The parameter B is currently ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with B and B 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 bytes hash value B using the private EC key B and the optional pre-computed values -B and B. The DER encoded signatures is stored in B and it's +B and B. The DER encoded signature is stored in B and its length is returned in B. Note: B must point to ECDSA_size(eckey) bytes of memory. The parameter B is ignored. @@ -114,8 +118,13 @@ returned as a newly allocated B 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 +145,33 @@ named curve prime256v1 (aka P-256). First step: create an EC_KEY object (note: this part is B 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 +183,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 +197,24 @@ ANSI X9.62, US Federal Information Processing Standard FIPS 186-2 =head1 SEE ALSO -L, +L, L, -L +L, +L +L, +L + +=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 -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.