Sortix nightly manual
This manual documents Sortix nightly, a development build that has not
been officially released. You can instead view
this document in the latest official manual
.
ECDSA_SIG_new
,
ECDSA_SIG_free
,
ECDSA_SIG_get0
,
ECDSA_SIG_get0_r
,
ECDSA_SIG_get0_s
,
ECDSA_SIG_set0
,
i2d_ECDSA_SIG
,
d2i_ECDSA_SIG
,
ECDSA_size
,
ECDSA_sign
,
ECDSA_verify
,
ECDSA_do_sign
,
ECDSA_do_verify
—
Elliptic Curve Digital Signature Algorithm
#include <
openssl/ec.h
>
ECDSA_SIG*
ECDSA_SIG_new
(
void
);
ECDSA_SIG_free
(
ECDSA_SIG *sig
);
ECDSA_SIG_get0
(
const ECDSA_SIG *sig
,
const BIGNUM **r
,
const BIGNUM **s
);
const BIGNUM *
ECDSA_SIG_get0_r
(
const ECDSA_SIG *sig
);
const BIGNUM *
ECDSA_SIG_get0_s
(
const ECDSA_SIG *sig
);
ECDSA_SIG_set0
(
ECDSA_SIG *sig
,
BIGNUM *r
,
BIGNUM *s
);
i2d_ECDSA_SIG
(
const ECDSA_SIG *sig_in
,
unsigned char **der_out
);
ECDSA_SIG*
d2i_ECDSA_SIG
(
ECDSA_SIG **sig_out
,
const unsigned char **der_in
,
long len
);
ECDSA_size
(
const EC_KEY *eckey
);
ECDSA_sign
(
int type
,
const unsigned char *dgst
,
int dgstlen
,
unsigned char *sig
,
unsigned int *siglen
,
EC_KEY *eckey
);
ECDSA_verify
(
int type
,
const unsigned char *dgst
,
int dgstlen
,
const unsigned char *sig
,
int siglen
,
EC_KEY *eckey
);
ECDSA_SIG*
ECDSA_do_sign
(
const unsigned char *dgst
,
int dgst_len
,
EC_KEY *eckey
);
ECDSA_do_verify
(
const unsigned char *dgst
,
int dgst_len
,
const ECDSA_SIG *sig
,
EC_KEY* eckey
);
These functions provide a low level interface to ECDSA. Most applications should use the higher level EVP interface such as
EVP_DigestSignInit(3)
or
EVP_DigestVerifyInit(3)
instead. Creation of the required
EC_KEY
objects is described in
EC_KEY_new(3)
.
The
ECDSA_SIG
structure consists of two
BIGNUM
s for the
r
and
s
value of an ECDSA signature (see X9.62 or FIPS 186-2).
struct {
BIGNUM *r;
BIGNUM *s;
} ECDSA_SIG;
ECDSA_SIG_new
() allocates a new
ECDSA_SIG
structure (note: this function also allocates the
BIGNUM
s) and initializes it.
ECDSA_SIG_free
() frees the
ECDSA_SIG
structure
sig
.
ECDSA_SIG_get0
() retrieves internal pointers the
r
and
s
values contained in
sig
. The values
r
and
s
can also be retrieved separately by the corresponding function
ECDSA_SIG_get0_r
() and
ECDSA_SIG_get0_s
(), respectively.
ECDSA_SIG_set0
() sets the
r
and
s
values in
sig
. Calling this function transfers the memory management of the values to
sig
. Therefore, the values that have been passed in should not be freed by the caller.
i2d_ECDSA_SIG
() creates the DER encoding of the ECDSA signature
sig_in
and writes the encoded signature to *
der_out
.
d2i_ECDSA_SIG
() decodes the DER-encoded signature stored in the buffer *
der_in
which is
len
bytes long into *
sig_out
. For details about the semantics, examples, caveats, and bugs, see
ASN1_item_d2i(3)
.
ECDSA_size
() returns the maximum length of a DER-encoded ECDSA signature created with the private EC key
eckey
.
ECDSA_sign
() computes a digital signature of the
dgstlen
bytes hash value
dgst
using the private EC key
eckey
. The DER-encoded signature is stored in
sig
and its length is returned in
siglen
. Note:
sig
must point to
ECDSA_size
() bytes of memory. The parameter
type
is ignored.
ECDSA_verify
() verifies that the signature in
sig
of size
siglen
is a valid ECDSA signature of the hash value
dgst
of size
dgstlen
using the public key
eckey
. The parameter
type
is ignored.
ECDSA_do_sign
() computes a digital signature of the
dgst_len
bytes hash value
dgst
using the private key
eckey
. The signature is returned in a newly allocated
ECDSA_SIG
structure (or
NULL
on error).
ECDSA_do_verify
() verifies that the signature
sig
is a valid ECDSA signature of the hash value
dgst
of size
dgst_len
using the public key
eckey
.
ECDSA_SIG_new
() returns the new
ECDSA_SIG
object or
NULL
if an error occurs.
i2d_ECDSA_SIG
() returns the number of bytes successfully encoded or a negative value if an error occurs.
d2i_ECDSA_SIG
() returns a pointer to the decoded
ECDSA_SIG
structure or
NULL
if an error occurs.
ECDSA_size
() returns the maximum length signature or 0 on error.
ECDSA_SIG_get0_r
() and
ECDSA_SIG_get0_s
() return a pointer owned by the
ECDSA_SIG
object if it has been set or
NULL
otherwise.
ECDSA_SIG_set0
() and
ECDSA_sign
() return 1 if successful or 0 on error.
ECDSA_do_sign
() returns a pointer to an allocated
ECDSA_SIG
structure or
NULL
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)
.
Creating an ECDSA signature of given SHA-1 hash value using the named curve secp192k1.
First step: create an
EC_KEY
object. This part is
not
ECDSA specific.
int ret;
ECDSA_SIG *sig;
EC_KEY *eckey;
eckey = EC_KEY_new_by_curve_name(NID_secp192k1);
if (eckey == NULL) {
/* error */
if (!EC_KEY_generate_key(eckey)) {
/* error */
Second step: compute the ECDSA signature of a SHA-1 hash value using
ECDSA_do_sign
()
sig = ECDSA_do_sign(digest, 20, eckey);
if (sig == NULL) {
/* error */
or using
ECDSA_sign
()
unsigned char *buffer, *pp;
int buf_len;
buf_len = ECDSA_size(eckey);
buffer = malloc(buf_len);
pp = buffer;
if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) {
/* error */
Third step: verify the created ECDSA signature using
ECDSA_do_verify
()
ret = ECDSA_do_verify(digest, 20, sig, eckey);
or using
ECDSA_verify
()
ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey);
and finally evaluate the return value:
ANSI X9.62, US Federal Information Processing Standard FIPS 186-5 (Digital Signature Standard, DSS)
(),
ECDSA_SIG_free
(),
i2d_ECDSA_SIG
(),
d2i_ECDSA_SIG
(),
ECDSA_size
(),
ECDSA_sign
(),
ECDSA_verify
(),
ECDSA_do_sign
(), and
ECDSA_do_verify
() first appeared in OpenSSL 0.9.8 and have been available since
OpenBSD 4.5
.
ECDSA_SIG_get0
() and
ECDSA_SIG_set0
() first appeared in OpenSSL 1.1.0 and have been available since
OpenBSD 6.3
.
ECDSA_SIG_get0_r
() and
ECDSA_SIG_get0_s
() first appeared in OpenSSL 1.1.1 and have been available since
OpenBSD 7.1
.
Nils Larsch
for the OpenSSL project.
Termansen and contributors.
Sortix is free software under the
ISC license
.
#sortix
on irc.sortix.org
