ECDSA_SIG_get0 (3)

Leading comments

Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/ECDSA_SIG_get0.3ssl".)

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

SYNOPSIS

 #include <openssl/ecdsa.h>

 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);
 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);
 int ECDSA_size(const EC_KEY *eckey);

 int ECDSA_sign(int type, const unsigned char *dgst, int dgstlen,
                unsigned char *sig, unsigned int *siglen, EC_KEY *eckey);
 ECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst, int dgst_len,
                          EC_KEY *eckey);

 int ECDSA_verify(int type, const unsigned char *dgst, int dgstlen,
                  const unsigned char *sig, int siglen, EC_KEY *eckey);
 int ECDSA_do_verify(const unsigned char *dgst, int dgst_len,
                     const ECDSA_SIG *sig, EC_KEY* eckey);

 ECDSA_SIG *ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,
                             const BIGNUM *kinv, const BIGNUM *rp,
                             EC_KEY *eckey);
 int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, BIGNUM **rp);
 int ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen,
                   unsigned char *sig, unsigned int *siglen,
                   const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey);

DESCRIPTION

Note: these functions provide a low level interface to Most applications should use the higher level interface such as EVP_DigestSignInit(3) or EVP_DigestVerifyInit(3) instead.

is an opaque structure consisting of two BIGNUMs for the r and s value of an signature (see X9.62 or ).

ECDSA_SIG_new() allocates an empty

structure. Note: before OpenSSL 1.1.0 the: the r and s components were initialised.

ECDSA_SIG_free() frees the

structure sig.

ECDSA_SIG_get0() returns internal pointers the r and s values contained in sig.

The r and s values can be set by calling ECDSA_SIG_set0() and passing the new values for r and s as parameters to the function. Calling this function transfers the memory management of the values to the

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

encoding of the signature sig and writes the encoded signature to *pp (note: if pp is i2d_ECDSA_SIG() returns the expected length in bytes of the encoded signature). i2d_ECDSA_SIG() returns the length of the encoded signature (or 0 on error).

d2i_ECDSA_SIG() decodes a

encoded signature and returns the decoded signature in a newly allocated structure. *sig points to the buffer containing the encoded signature of size len.

ECDSA_size() returns the maximum length of a

encoded signature created with the private key eckey.

ECDSA_sign() computes a digital signature of the dgstlen bytes hash value dgst using the private

key eckey. The encoded signatures is stored in sig and its length is returned in sig_len. Note: sig must point to ECDSA_size(eckey) bytes of memory. The parameter type is currently ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with kinv and rp set to

ECDSA_do_sign() is similar to ECDSA_sign() except the signature is returned as a newly allocated

structure (or on error). ECDSA_do_sign() is a wrapper function for ECDSA_do_sign_ex() with kinv and rp set to

ECDSA_verify() verifies that the signature in sig of size siglen is a valid

signature of the hash value dgst of size dgstlen using the public key eckey. The parameter type is ignored.

ECDSA_do_verify() is similar to ECDSA_verify() except the signature is presented in the form of a pointer to an

structure.

The remaining functions utilise the internal kinv and r values used during signature computation. Most applications will never need to call these and some external

implementations may not support them at all if either kinv or r is not .

ECDSA_sign_setup() may be used to precompute parts of the signing operation. eckey is the private

key and ctx is a pointer to structure (or ). The precomputed values or returned in kinv and rp and can be used in a later call to ECDSA_sign_ex() or ECDSA_do_sign_ex().

ECDSA_sign_ex() computes a digital signature of the dgstlen bytes hash value dgst using the private

key eckey and the optional pre-computed values kinv and rp. The encoded signature is stored in sig and its length is returned in sig_len. Note: sig must point to ECDSA_size(eckey) bytes of memory. The parameter type is ignored.

ECDSA_do_sign_ex() is similar to ECDSA_sign_ex() except the signature is returned as a newly allocated

structure (or on error).

RETURN VALUES

ECDSA_SIG_set0() returns 1 on success or 0 on failure.

ECDSA_size() returns the maximum length signature or 0 on error.

ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if successful or 0 on error.

ECDSA_do_sign() and ECDSA_do_sign_ex() return a pointer to an allocated

structure or on error.

ECDSA_verify() and ECDSA_do_verify() return 1 for a valid signature, 0 for an invalid signature and -1 on error. The error codes can be obtained by ERR_get_error(3).

EXAMPLES

Creating an signature of a given hash value using the named curve prime256v1 (aka P-256).

First step: create an

object (note: this part is not specific)

 int        ret;
 ECDSA_SIG *sig;
 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 */
 }

Second step: compute the

signature of a hash value using ECDSA_do_sign():

 sig = ECDSA_do_sign(digest, 32, eckey);
 if (sig == NULL) {
    /* error */
 }

or using ECDSA_sign():

 unsigned char *buffer, *pp;
 int            buf_len;
 buf_len = ECDSA_size(eckey);
 buffer  = OPENSSL_malloc(buf_len);
 pp = buffer;
 if (ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) == 0) {
    /* error */
 }

Third step: verify the created

signature using ECDSA_do_verify():

 ret = ECDSA_do_verify(digest, 32, sig, eckey);

or using ECDSA_verify():

 ret = ECDSA_verify(0, digest, 32, buffer, buf_len, eckey);

and finally evaluate the return value:

 if (ret == 1) {
    /* signature ok */
 } else if (ret == 0) {
    /* incorrect signature */
 } else {
    /* error */
 }

CONFORMING TO

Federal Information Processing Standard (Digital Signature Standard, )

SEE ALSO

DSA_new(3), EVP_DigestSignInit(3), EVP_DigestVerifyInit(3)

COPYRIGHT

Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the ``License''). You may not use this file except in compliance with the License. You can obtain a copy in the file

in the source distribution or at <www.openssl.org/source/license.html>.