secp256k1.c File Reference

#include "include/secp256k1.h"
#include "util.h"
#include "num_impl.h"
#include "field_impl.h"
#include "scalar_impl.h"
#include "group_impl.h"
#include "ecmult_impl.h"
#include "ecmult_const_impl.h"
#include "ecmult_gen_impl.h"
#include "ecdsa_impl.h"
#include "eckey_impl.h"
#include "hash_impl.h"
#include "scratch_impl.h"

Include dependency graph for secp256k1.c:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	secp256k1_context_struct

Macros
#define	ARG_CHECK(cond)

Functions
static void	default_illegal_callback_fn (const char *str, void *data)
static void	default_error_callback_fn (const char *str, void *data)
secp256k1_context *	secp256k1_context_create (unsigned int flags)
	Create a secp256k1 context object. More...
secp256k1_context *	secp256k1_context_clone (const secp256k1_context *ctx)
	Copies a secp256k1 context object. More...
void	secp256k1_context_destroy (secp256k1_context *ctx)
	Destroy a secp256k1 context object. More...
void	secp256k1_context_set_illegal_callback (secp256k1_context *ctx, void(*fun)(const char *message, void *data), const void *data)
	Set a callback function to be called when an illegal argument is passed to an API call. More...
void	secp256k1_context_set_error_callback (secp256k1_context *ctx, void(*fun)(const char *message, void *data), const void *data)
	Set a callback function to be called when an internal consistency check fails. More...
secp256k1_scratch_space *	secp256k1_scratch_space_create (const secp256k1_context *ctx, size_t max_size)
	Create a secp256k1 scratch space object. More...
void	secp256k1_scratch_space_destroy (secp256k1_scratch_space *scratch)
	Destroy a secp256k1 scratch space. More...
static int	secp256k1_pubkey_load (const secp256k1_context *ctx, secp256k1_ge *ge, const secp256k1_pubkey *pubkey)
static void	secp256k1_pubkey_save (secp256k1_pubkey *pubkey, secp256k1_ge *ge)
int	secp256k1_ec_pubkey_parse (const secp256k1_context *ctx, secp256k1_pubkey *pubkey, const unsigned char *input, size_t inputlen)
	Parse a variable-length public key into the pubkey object. More...
int	secp256k1_ec_pubkey_serialize (const secp256k1_context *ctx, unsigned char *output, size_t *outputlen, const secp256k1_pubkey *pubkey, unsigned int flags)
	Serialize a pubkey object into a serialized byte sequence. More...
static void	secp256k1_ecdsa_signature_load (const secp256k1_context *ctx, secp256k1_scalar *r, secp256k1_scalar *s, const secp256k1_ecdsa_signature *sig)
static void	secp256k1_ecdsa_signature_save (secp256k1_ecdsa_signature *sig, const secp256k1_scalar *r, const secp256k1_scalar *s)
int	secp256k1_ecdsa_signature_parse_der (const secp256k1_context *ctx, secp256k1_ecdsa_signature *sig, const unsigned char *input, size_t inputlen)
	Parse a DER ECDSA signature. More...
int	secp256k1_ecdsa_signature_parse_compact (const secp256k1_context *ctx, secp256k1_ecdsa_signature *sig, const unsigned char *input64)
	Parse an ECDSA signature in compact (64 bytes) format. More...
int	secp256k1_ecdsa_signature_serialize_der (const secp256k1_context *ctx, unsigned char *output, size_t *outputlen, const secp256k1_ecdsa_signature *sig)
	Serialize an ECDSA signature in DER format. More...
int	secp256k1_ecdsa_signature_serialize_compact (const secp256k1_context *ctx, unsigned char *output64, const secp256k1_ecdsa_signature *sig)
	Serialize an ECDSA signature in compact (64 byte) format. More...
int	secp256k1_ecdsa_signature_normalize (const secp256k1_context *ctx, secp256k1_ecdsa_signature *sigout, const secp256k1_ecdsa_signature *sigin)
	Convert a signature to a normalized lower-S form. More...
int	secp256k1_ecdsa_verify (const secp256k1_context *ctx, const secp256k1_ecdsa_signature *sig, const unsigned char *msg32, const secp256k1_pubkey *pubkey)
	Verify an ECDSA signature. More...
static SECP256K1_INLINE void	buffer_append (unsigned char *buf, unsigned int *offset, const void *data, unsigned int len)
static int	nonce_function_rfc6979 (unsigned char *nonce32, const unsigned char *msg32, const unsigned char *key32, const unsigned char *algo16, void *data, unsigned int counter)
int	secp256k1_ecdsa_sign (const secp256k1_context *ctx, secp256k1_ecdsa_signature *signature, const unsigned char *msg32, const unsigned char *seckey, secp256k1_nonce_function noncefp, const void *noncedata)
	Create an ECDSA signature. More...
int	secp256k1_ec_seckey_verify (const secp256k1_context *ctx, const unsigned char *seckey)
	Verify an ECDSA secret key. More...
int	secp256k1_ec_pubkey_create (const secp256k1_context *ctx, secp256k1_pubkey *pubkey, const unsigned char *seckey)
	Compute the public key for a secret key. More...
int	secp256k1_ec_privkey_negate (const secp256k1_context *ctx, unsigned char *seckey)
	Negates a private key in place. More...
int	secp256k1_ec_pubkey_negate (const secp256k1_context *ctx, secp256k1_pubkey *pubkey)
	Negates a public key in place. More...
int	secp256k1_ec_privkey_tweak_add (const secp256k1_context *ctx, unsigned char *seckey, const unsigned char *tweak)
	Tweak a private key by adding tweak to it. More...
int	secp256k1_ec_pubkey_tweak_add (const secp256k1_context *ctx, secp256k1_pubkey *pubkey, const unsigned char *tweak)
	Tweak a public key by adding tweak times the generator to it. More...
int	secp256k1_ec_privkey_tweak_mul (const secp256k1_context *ctx, unsigned char *seckey, const unsigned char *tweak)
	Tweak a private key by multiplying it by a tweak. More...
int	secp256k1_ec_pubkey_tweak_mul (const secp256k1_context *ctx, secp256k1_pubkey *pubkey, const unsigned char *tweak)
	Tweak a public key by multiplying it by a tweak value. More...
int	secp256k1_context_randomize (secp256k1_context *ctx, const unsigned char *seed32)
	Updates the context randomization to protect against side-channel leakage. More...
int	secp256k1_ec_pubkey_combine (const secp256k1_context *ctx, secp256k1_pubkey *pubnonce, const secp256k1_pubkey *const *pubnonces, size_t n)
	Add a number of public keys together. More...

Variables
static const secp256k1_callback	default_illegal_callback
static const secp256k1_callback	default_error_callback
static const secp256k1_context	secp256k1_context_no_precomp_
const secp256k1_context *	secp256k1_context_no_precomp = &secp256k1_context_no_precomp_
	A simple secp256k1 context object with no precomputed tables. More...
const secp256k1_nonce_function	secp256k1_nonce_function_rfc6979 = nonce_function_rfc6979
	An implementation of RFC6979 (using HMAC-SHA256) as nonce generation function. More...
const secp256k1_nonce_function	secp256k1_nonce_function_default = nonce_function_rfc6979
	A default safe nonce generation function (currently equal to secp256k1_nonce_function_rfc6979). More...

Macro Definition Documentation

ARG_CHECK

#define ARG_CHECK

(

cond

)

Value:

do { \
    if (EXPECT(!(cond), 0)) { \
        secp256k1_callback_call(&ctx->illegal_callback, #cond); \
        return 0; \
    } \
} while(0)

Definition at line 22 of file secp256k1.c.

Referenced by secp256k1_ec_privkey_negate(), secp256k1_ec_privkey_tweak_add(), secp256k1_ec_privkey_tweak_mul(), secp256k1_ec_pubkey_combine(), secp256k1_ec_pubkey_create(), secp256k1_ec_pubkey_negate(), secp256k1_ec_pubkey_parse(), secp256k1_ec_pubkey_serialize(), secp256k1_ec_pubkey_tweak_add(), secp256k1_ec_pubkey_tweak_mul(), secp256k1_ec_seckey_verify(), secp256k1_ecdh(), secp256k1_ecdsa_recover(), secp256k1_ecdsa_recoverable_signature_convert(), secp256k1_ecdsa_recoverable_signature_parse_compact(), secp256k1_ecdsa_recoverable_signature_serialize_compact(), secp256k1_ecdsa_sign(), secp256k1_ecdsa_sign_recoverable(), secp256k1_ecdsa_signature_normalize(), secp256k1_ecdsa_signature_parse_compact(), secp256k1_ecdsa_signature_parse_der(), secp256k1_ecdsa_signature_serialize_compact(), secp256k1_ecdsa_signature_serialize_der(), secp256k1_ecdsa_verify(), and secp256k1_pubkey_load().

Function Documentation

buffer_append()

static SECP256K1_INLINE void buffer_append ( unsigned char *  buf, unsigned int *  offset, const void *  data, unsigned int  len  )

static

Definition at line 331 of file secp256k1.c.

References memcpy().

Referenced by nonce_function_rfc6979().

default_error_callback_fn()

static void default_error_callback_fn ( const char *  str, void *  data  )

static

Definition at line 40 of file secp256k1.c.

Referenced by secp256k1_context_set_error_callback().

default_illegal_callback_fn()

static void default_illegal_callback_fn ( const char *  str, void *  data  )

static

Definition at line 29 of file secp256k1.c.

Referenced by secp256k1_context_set_illegal_callback().

nonce_function_rfc6979()

static int nonce_function_rfc6979 ( unsigned char *  nonce32, const unsigned char *  msg32, const unsigned char *  key32, const unsigned char *  algo16, void *  data, unsigned int  counter  )

static

Definition at line 336 of file secp256k1.c.

References buffer_append(), secp256k1_rfc6979_hmac_sha256_finalize(), secp256k1_rfc6979_hmac_sha256_generate(), and secp256k1_rfc6979_hmac_sha256_initialize().

Referenced by nonce_function_test_fail(), nonce_function_test_retry(), and test_ecdsa_edge_cases().

secp256k1_context_clone()

secp256k1_context* secp256k1_context_clone

(

const secp256k1_context *

ctx

)

Copies a secp256k1 context object.

Returns: a newly created context object. Args: ctx: an existing context to copy (cannot be NULL)

Definition at line 92 of file secp256k1.c.

References checked_malloc(), ctx, secp256k1_context_struct::ecmult_ctx, secp256k1_context_struct::ecmult_gen_ctx, secp256k1_context_struct::error_callback, secp256k1_context_struct::illegal_callback, secp256k1_ecmult_context_clone(), and secp256k1_ecmult_gen_context_clone().

Referenced by Java_org_bitcoin_NativeSecp256k1_secp256k1_1ctx_1clone(), and run_context_tests().

secp256k1_context_create()

secp256k1_context* secp256k1_context_create

(

unsigned int

flags

)

Create a secp256k1 context object.

Returns: a newly created context object. In: flags: which parts of the context to initialize.

See also secp256k1_context_randomize.

Definition at line 67 of file secp256k1.c.

References checked_malloc(), default_error_callback, default_illegal_callback, secp256k1_context_struct::ecmult_ctx, secp256k1_context_struct::ecmult_gen_ctx, secp256k1_context_struct::error_callback, EXPECT, flags, secp256k1_context_struct::illegal_callback, secp256k1_callback_call(), secp256k1_ecmult_context_build(), secp256k1_ecmult_context_init(), secp256k1_ecmult_gen_context_build(), secp256k1_ecmult_gen_context_init(), SECP256K1_FLAGS_BIT_CONTEXT_SIGN, SECP256K1_FLAGS_BIT_CONTEXT_VERIFY, SECP256K1_FLAGS_TYPE_CONTEXT, and SECP256K1_FLAGS_TYPE_MASK.

Referenced by bench_context_sign(), bench_context_verify(), bench_ecdh_setup(), ECC_Start(), ECCVerifyHandle::ECCVerifyHandle(), Java_org_bitcoin_Secp256k1Context_secp256k1_1init_1context(), main(), run_context_tests(), run_scratch_tests(), test_ecdh_api(), and test_ecdsa_recovery_api().

secp256k1_context_destroy()

void secp256k1_context_destroy

(

secp256k1_context *

ctx

)

Destroy a secp256k1 context object.

The context pointer may not be used afterwards. Args: ctx: an existing context to destroy (cannot be NULL)

Definition at line 101 of file secp256k1.c.

References CHECK, ctx, secp256k1_context_struct::ecmult_ctx, secp256k1_context_struct::ecmult_gen_ctx, secp256k1_context_no_precomp, secp256k1_ecmult_context_clear(), and secp256k1_ecmult_gen_context_clear().

Referenced by bench_context_sign(), bench_context_verify(), ECC_Stop(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1destroy_1context(), main(), run_context_tests(), run_scratch_tests(), test_ecdh_api(), test_ecdsa_recovery_api(), and ECCVerifyHandle::~ECCVerifyHandle().

secp256k1_context_randomize()

int secp256k1_context_randomize	(	secp256k1_context *	ctx,
		const unsigned char *	seed32
	)

Updates the context randomization to protect against side-channel leakage.

Returns: 1: randomization successfully updated or nothing to randomize 0: error Args: ctx: pointer to a context object (cannot be NULL) In: seed32: pointer to a 32-byte random seed (NULL resets to initial state)

While secp256k1 code is written to be constant-time no matter what secret values are, it's possible that a future compiler may output code which isn't, and also that the CPU may not emit the same radio frequencies or draw the same amount power for all values.

This function provides a seed which is combined into the blinding value: that blinding value is added before each multiplication (and removed afterwards) so that it does not affect function results, but shields against attacks which rely on any input-dependent behaviour.

This function has currently an effect only on contexts initialized for signing because randomization is currently used only for signing. However, this is not guaranteed and may change in the future. It is safe to call this function on contexts not initialized for signing; then it will have no effect and return 1.

You should call this after secp256k1_context_create or secp256k1_context_clone, and may call this repeatedly afterwards.

Definition at line 571 of file secp256k1.c.

References ctx, secp256k1_context_struct::ecmult_gen_ctx, secp256k1_ecmult_gen_blind(), secp256k1_ecmult_gen_context_is_built(), and VERIFY_CHECK.

Referenced by ECC_Start(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1context_1randomize(), main(), and run_context_tests().

secp256k1_context_set_error_callback()

void secp256k1_context_set_error_callback	(	secp256k1_context *	ctx,
		void(*)(const char *message, void *data)	fun,
		const void *	data
	)

Set a callback function to be called when an internal consistency check fails.

The default is crashing.

This can only trigger in case of a hardware failure, miscompilation, memory corruption, serious bug in the library, or other error would can otherwise result in undefined behaviour. It will not trigger due to mere incorrect usage of the API (see secp256k1_context_set_illegal_callback for that). After this callback returns, anything may happen, including crashing.

Args: ctx: an existing context object (cannot be NULL) In: fun: a pointer to a function to call when an internal error occurs, taking a message and an opaque pointer (NULL restores a default handler that calls abort). data: the opaque pointer to pass to fun above.

Definition at line 120 of file secp256k1.c.

References CHECK, ctx, secp256k1_callback::data, default_error_callback_fn(), secp256k1_context_struct::error_callback, secp256k1_callback::fn, and secp256k1_context_no_precomp.

Referenced by run_context_tests(), test_ecdh_api(), and test_ecdsa_recovery_api().

secp256k1_context_set_illegal_callback()

void secp256k1_context_set_illegal_callback	(	secp256k1_context *	ctx,
		void(*)(const char *message, void *data)	fun,
		const void *	data
	)

Set a callback function to be called when an illegal argument is passed to an API call.

It will only trigger for violations that are mentioned explicitly in the header.

The philosophy is that these shouldn't be dealt with through a specific return value, as calling code should not have branches to deal with the case that this code itself is broken.

On the other hand, during debug stage, one would want to be informed about such mistakes, and the default (crashing) may be inadvisable. When this callback is triggered, the API function called is guaranteed not to cause a crash, though its return value and output arguments are undefined.

Args: ctx: an existing context object (cannot be NULL) In: fun: a pointer to a function to call when an illegal argument is passed to the API, taking a message and an opaque pointer (NULL restores a default handler that calls abort). data: the opaque pointer to pass to fun above.

Definition at line 111 of file secp256k1.c.

References CHECK, ctx, secp256k1_callback::data, default_illegal_callback_fn(), secp256k1_callback::fn, secp256k1_context_struct::illegal_callback, and secp256k1_context_no_precomp.

Referenced by ec_pubkey_parse_pointtest(), run_context_tests(), run_ec_pubkey_parse_test(), run_eckey_edge_case_test(), run_scratch_tests(), test_ecdh_api(), test_ecdsa_edge_cases(), and test_ecdsa_recovery_api().

secp256k1_ec_privkey_negate()

int secp256k1_ec_privkey_negate	(	const secp256k1_context *	ctx,
		unsigned char *	seckey
	)

Negates a private key in place.

Returns: 1 always Args: ctx: pointer to a context object In/Out: seckey: pointer to the 32-byte private key to be negated (cannot be NULL)

Definition at line 451 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_scalar_get_b32(), secp256k1_scalar_negate(), secp256k1_scalar_set_b32(), and VERIFY_CHECK.

secp256k1_ec_privkey_tweak_add()

int secp256k1_ec_privkey_tweak_add	(	const secp256k1_context *	ctx,
		unsigned char *	seckey,
		const unsigned char *	tweak
	)

Tweak a private key by adding tweak to it.

Returns: 0 if the tweak was out of range (chance of around 1 in 2^128 for uniformly random 32-byte arrays, or if the resulting private key would be invalid (only when the tweak is the complement of the private key). 1 otherwise. Args: ctx: pointer to a context object (cannot be NULL). In/Out: seckey: pointer to a 32-byte private key. In: tweak: pointer to a 32-byte tweak.

Definition at line 478 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_eckey_privkey_tweak_add(), secp256k1_scalar_clear(), secp256k1_scalar_get_b32(), secp256k1_scalar_set_b32(), and VERIFY_CHECK.

Referenced by CKey::Derive(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1privkey_1tweak_1add(), run_eckey_edge_case_test(), and test_ecdsa_end_to_end().

secp256k1_ec_privkey_tweak_mul()

int secp256k1_ec_privkey_tweak_mul	(	const secp256k1_context *	ctx,
		unsigned char *	seckey,
		const unsigned char *	tweak
	)

Tweak a private key by multiplying it by a tweak.

Returns: 0 if the tweak was out of range (chance of around 1 in 2^128 for uniformly random 32-byte arrays, or equal to zero. 1 otherwise. Args: ctx: pointer to a context object (cannot be NULL). In/Out: seckey: pointer to a 32-byte private key. In: tweak: pointer to a 32-byte tweak.

Definition at line 525 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_eckey_privkey_tweak_mul(), secp256k1_scalar_clear(), secp256k1_scalar_get_b32(), secp256k1_scalar_set_b32(), and VERIFY_CHECK.

Referenced by Java_org_bitcoin_NativeSecp256k1_secp256k1_1privkey_1tweak_1mul(), run_eckey_edge_case_test(), and test_ecdsa_end_to_end().

secp256k1_ec_pubkey_combine()

int secp256k1_ec_pubkey_combine	(	const secp256k1_context *	ctx,
		secp256k1_pubkey *	out,
		const secp256k1_pubkey *const *	ins,
		size_t	n
	)

Add a number of public keys together.

Returns: 1: the sum of the public keys is valid. 0: the sum of the public keys is not valid. Args: ctx: pointer to a context object Out: out: pointer to a public key object for placing the resulting public key (cannot be NULL) In: ins: pointer to array of pointers to public keys (cannot be NULL) n: the number of public keys to add together (must be at least 1)

Definition at line 579 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_ge_set_gej(), secp256k1_gej_add_ge(), secp256k1_gej_is_infinity(), secp256k1_gej_set_infinity(), secp256k1_pubkey_load(), and secp256k1_pubkey_save().

Referenced by run_eckey_edge_case_test(), and test_ec_combine().

secp256k1_ec_pubkey_create()

int secp256k1_ec_pubkey_create	(	const secp256k1_context *	ctx,
		secp256k1_pubkey *	pubkey,
		const unsigned char *	seckey
	)

Compute the public key for a secret key.

Returns: 1: secret was valid, public key stores 0: secret was invalid, try again Args: ctx: pointer to a context object, initialized for signing (cannot be NULL) Out: pubkey: pointer to the created public key (cannot be NULL) In: seckey: pointer to a 32-byte private key (cannot be NULL)

Definition at line 428 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_context_struct::ecmult_gen_ctx, secp256k1_ecmult_gen(), secp256k1_ecmult_gen_context_is_built(), secp256k1_ge_set_gej(), secp256k1_pubkey_save(), secp256k1_scalar_clear(), secp256k1_scalar_is_zero(), secp256k1_scalar_set_b32(), and VERIFY_CHECK.

Referenced by ec_privkey_export_der(), CKey::GetPubKey(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1ec_1pubkey_1create(), main(), run_context_tests(), run_eckey_edge_case_test(), test_bad_scalar(), test_ecdh_api(), test_ecdh_generator_basepoint(), test_ecdsa_edge_cases(), test_ecdsa_end_to_end(), test_ecdsa_recovery_api(), and test_ecdsa_recovery_end_to_end().

secp256k1_ec_pubkey_negate()

int secp256k1_ec_pubkey_negate	(	const secp256k1_context *	ctx,
		secp256k1_pubkey *	pubkey
	)

Negates a public key in place.

Returns: 1 always Args: ctx: pointer to a context object In/Out: pubkey: pointer to the public key to be negated (cannot be NULL)

Definition at line 463 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_ge_neg(), secp256k1_pubkey_load(), secp256k1_pubkey_save(), and VERIFY_CHECK.

Referenced by run_context_tests(), and test_ecdsa_end_to_end().

secp256k1_ec_pubkey_parse()

int secp256k1_ec_pubkey_parse	(	const secp256k1_context *	ctx,
		secp256k1_pubkey *	pubkey,
		const unsigned char *	input,
		size_t	inputlen
	)

Parse a variable-length public key into the pubkey object.

Returns: 1 if the public key was fully valid. 0 if the public key could not be parsed or is invalid. Args: ctx: a secp256k1 context object. Out: pubkey: pointer to a pubkey object. If 1 is returned, it is set to a parsed version of input. If not, its value is undefined. In: input: pointer to a serialized public key inputlen: length of the array pointed to by input

This function supports parsing compressed (33 bytes, header byte 0x02 or 0x03), uncompressed (65 bytes, header byte 0x04), or hybrid (65 bytes, header byte 0x06 or 0x07) format public keys.

Definition at line 171 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_eckey_pubkey_parse(), secp256k1_ge_clear(), secp256k1_pubkey_save(), and VERIFY_CHECK.

Referenced by bench_ecdh_setup(), benchmark_verify(), CPubKey::Decompress(), CPubKey::Derive(), ec_pubkey_parse_pointtest(), CPubKey::IsFullyValid(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1ecdh(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1ecdsa_1verify(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1pubkey_1tweak_1add(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1pubkey_1tweak_1mul(), run_ec_pubkey_parse_test(), test_ecdsa_end_to_end(), and CPubKey::Verify().

secp256k1_ec_pubkey_serialize()

int secp256k1_ec_pubkey_serialize	(	const secp256k1_context *	ctx,
		unsigned char *	output,
		size_t *	outputlen,
		const secp256k1_pubkey *	pubkey,
		unsigned int	flags
	)

Serialize a pubkey object into a serialized byte sequence.

Returns: 1 always. Args: ctx: a secp256k1 context object. Out: output: a pointer to a 65-byte (if compressed==0) or 33-byte (if compressed==1) byte array to place the serialized key in. In/Out: outputlen: a pointer to an integer which is initially set to the size of output, and is overwritten with the written size. In: pubkey: a pointer to a secp256k1_pubkey containing an initialized public key. flags: SECP256K1_EC_COMPRESSED if serialization should be in compressed format, otherwise SECP256K1_EC_UNCOMPRESSED.

Definition at line 186 of file secp256k1.c.

References ARG_CHECK, ctx, flags, secp256k1_eckey_pubkey_serialize(), SECP256K1_FLAGS_BIT_COMPRESSION, SECP256K1_FLAGS_TYPE_COMPRESSION, SECP256K1_FLAGS_TYPE_MASK, secp256k1_pubkey_load(), and VERIFY_CHECK.

Referenced by bench_recover(), CPubKey::Decompress(), CPubKey::Derive(), ec_privkey_export_der(), ec_pubkey_parse_pointtest(), CKey::GetPubKey(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1ec_1pubkey_1create(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1pubkey_1tweak_1add(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1pubkey_1tweak_1mul(), main(), CPubKey::RecoverCompact(), run_ec_pubkey_parse_test(), run_eckey_edge_case_test(), test_ecdh_generator_basepoint(), and test_ecdsa_end_to_end().

secp256k1_ec_pubkey_tweak_add()

int secp256k1_ec_pubkey_tweak_add	(	const secp256k1_context *	ctx,
		secp256k1_pubkey *	pubkey,
		const unsigned char *	tweak
	)

Tweak a public key by adding tweak times the generator to it.

Returns: 0 if the tweak was out of range (chance of around 1 in 2^128 for uniformly random 32-byte arrays, or if the resulting public key would be invalid (only when the tweak is the complement of the corresponding private key). 1 otherwise. Args: ctx: pointer to a context object initialized for validation (cannot be NULL). In/Out: pubkey: pointer to a public key object. In: tweak: pointer to a 32-byte tweak.

Definition at line 501 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_context_struct::ecmult_ctx, secp256k1_eckey_pubkey_tweak_add(), secp256k1_ecmult_context_is_built(), secp256k1_pubkey_load(), secp256k1_pubkey_save(), secp256k1_scalar_set_b32(), and VERIFY_CHECK.

Referenced by CPubKey::Derive(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1pubkey_1tweak_1add(), run_context_tests(), run_eckey_edge_case_test(), and test_ecdsa_end_to_end().

secp256k1_ec_pubkey_tweak_mul()

int secp256k1_ec_pubkey_tweak_mul	(	const secp256k1_context *	ctx,
		secp256k1_pubkey *	pubkey,
		const unsigned char *	tweak
	)

Tweak a public key by multiplying it by a tweak value.

Returns: 0 if the tweak was out of range (chance of around 1 in 2^128 for uniformly random 32-byte arrays, or equal to zero. 1 otherwise. Args: ctx: pointer to a context object initialized for validation (cannot be NULL). In/Out: pubkey: pointer to a public key obkect. In: tweak: pointer to a 32-byte tweak.

Definition at line 547 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_context_struct::ecmult_ctx, secp256k1_eckey_pubkey_tweak_mul(), secp256k1_ecmult_context_is_built(), secp256k1_pubkey_load(), secp256k1_pubkey_save(), secp256k1_scalar_set_b32(), and VERIFY_CHECK.

Referenced by Java_org_bitcoin_NativeSecp256k1_secp256k1_1pubkey_1tweak_1mul(), run_context_tests(), run_eckey_edge_case_test(), and test_ecdsa_end_to_end().

secp256k1_ec_seckey_verify()

int secp256k1_ec_seckey_verify	(	const secp256k1_context *	ctx,
		const unsigned char *	seckey
	)

Verify an ECDSA secret key.

Returns: 1: secret key is valid 0: secret key is invalid Args: ctx: pointer to a context object (cannot be NULL) In: seckey: pointer to a 32-byte secret key (cannot be NULL)

Definition at line 415 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_scalar_clear(), secp256k1_scalar_is_zero(), secp256k1_scalar_set_b32(), and VERIFY_CHECK.

Referenced by CKey::Check(), ec_privkey_import_der(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1ec_1seckey_1verify(), run_eckey_edge_case_test(), test_ecdsa_end_to_end(), test_ecdsa_recovery_api(), and test_ecdsa_recovery_end_to_end().

secp256k1_ecdsa_sign()

int secp256k1_ecdsa_sign	(	const secp256k1_context *	ctx,
		secp256k1_ecdsa_signature *	sig,
		const unsigned char *	msg32,
		const unsigned char *	seckey,
		secp256k1_nonce_function	noncefp,
		const void *	ndata
	)

Create an ECDSA signature.

Returns: 1: signature created 0: the nonce generation function failed, or the private key was invalid. Args: ctx: pointer to a context object, initialized for signing (cannot be NULL) Out: sig: pointer to an array where the signature will be placed (cannot be NULL) In: msg32: the 32-byte message hash being signed (cannot be NULL) seckey: pointer to a 32-byte secret key (cannot be NULL) noncefp:pointer to a nonce generation function. If NULL, secp256k1_nonce_function_default is used ndata: pointer to arbitrary data used by the nonce generation function (can be NULL)

The created signature is always in lower-S form. See secp256k1_ecdsa_signature_normalize for more details.

Definition at line 369 of file secp256k1.c.

References ARG_CHECK, count, ctx, secp256k1_context_struct::ecmult_gen_ctx, secp256k1_ecdsa_sig_sign(), secp256k1_ecdsa_signature_save(), secp256k1_ecmult_gen_context_is_built(), secp256k1_nonce_function_default, secp256k1_scalar_clear(), secp256k1_scalar_is_zero(), secp256k1_scalar_set_b32(), and VERIFY_CHECK.

Referenced by bench_sign_run(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1ecdsa_1sign(), main(), run_context_tests(), CKey::Sign(), test_ecdsa_edge_cases(), test_ecdsa_end_to_end(), test_ecdsa_recovery_api(), test_ecdsa_recovery_end_to_end(), and test_exhaustive_sign().

secp256k1_ecdsa_signature_load()

static void secp256k1_ecdsa_signature_load ( const secp256k1_context *  ctx, secp256k1_scalar *  r, secp256k1_scalar *  s, const secp256k1_ecdsa_signature *  sig  )

static

Definition at line 209 of file secp256k1.c.

References ctx, secp256k1_ecdsa_signature::data, memcpy(), and secp256k1_scalar_set_b32().

Referenced by secp256k1_ecdsa_signature_normalize(), secp256k1_ecdsa_signature_serialize_compact(), secp256k1_ecdsa_signature_serialize_der(), secp256k1_ecdsa_verify(), test_ecdsa_edge_cases(), test_ecdsa_end_to_end(), and test_exhaustive_sign().

secp256k1_ecdsa_signature_normalize()

int secp256k1_ecdsa_signature_normalize	(	const secp256k1_context *	ctx,
		secp256k1_ecdsa_signature *	sigout,
		const secp256k1_ecdsa_signature *	sigin
	)

Convert a signature to a normalized lower-S form.

Returns: 1 if sigin was not normalized, 0 if it already was. Args: ctx: a secp256k1 context object Out: sigout: a pointer to a signature to fill with the normalized form, or copy if the input was already normalized. (can be NULL if you're only interested in whether the input was already normalized). In: sigin: a pointer to a signature to check/normalize (cannot be NULL, can be identical to sigout)

With ECDSA a third-party can forge a second distinct signature of the same message, given a single initial signature, but without knowing the key. This is done by negating the S value modulo the order of the curve, 'flipping' the sign of the random point R which is not included in the signature.

Forgery of the same message isn't universally problematic, but in systems where message malleability or uniqueness of signatures is important this can cause issues. This forgery can be blocked by all verifiers forcing signers to use a normalized form.

The lower-S form reduces the size of signatures slightly on average when variable length encodings (such as DER) are used and is cheap to verify, making it a good choice. Security of always using lower-S is assured because anyone can trivially modify a signature after the fact to enforce this property anyway.

The lower S value is always between 0x1 and 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0, inclusive.

No other forms of ECDSA malleability are known and none seem likely, but there is no formal proof that ECDSA, even with this additional restriction, is free of other malleability. Commonly used serialization schemes will also accept various non-unique encodings, so care should be taken when this property is required for an application.

The secp256k1_ecdsa_sign function will by default create signatures in the lower-S form, and secp256k1_ecdsa_verify will not accept others. In case signatures come from a system that cannot enforce this property, secp256k1_ecdsa_signature_normalize must be called before verification.

Definition at line 295 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_ecdsa_signature_load(), secp256k1_ecdsa_signature_save(), secp256k1_scalar_is_high(), secp256k1_scalar_negate(), and VERIFY_CHECK.

Referenced by CPubKey::CheckLowS(), test_ecdsa_edge_cases(), test_ecdsa_end_to_end(), and CPubKey::Verify().

secp256k1_ecdsa_signature_parse_compact()

int secp256k1_ecdsa_signature_parse_compact	(	const secp256k1_context *	ctx,
		secp256k1_ecdsa_signature *	sig,
		const unsigned char *	input64
	)

Parse an ECDSA signature in compact (64 bytes) format.

Returns: 1 when the signature could be parsed, 0 otherwise. Args: ctx: a secp256k1 context object Out: sig: a pointer to a signature object In: input64: a pointer to the 64-byte array to parse

The signature must consist of a 32-byte big endian R value, followed by a 32-byte big endian S value. If R or S fall outside of [0..order-1], the encoding is invalid. R and S with value 0 are allowed in the encoding.

After the call, sig will always be initialized. If parsing failed or R or S are zero, the resulting sig value is guaranteed to fail validation for any message and public key.

Definition at line 249 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_ecdsa_signature_save(), secp256k1_scalar_set_b32(), and VERIFY_CHECK.

Referenced by ecdsa_signature_parse_der_lax(), and test_ecdsa_edge_cases().

secp256k1_ecdsa_signature_parse_der()

int secp256k1_ecdsa_signature_parse_der	(	const secp256k1_context *	ctx,
		secp256k1_ecdsa_signature *	sig,
		const unsigned char *	input,
		size_t	inputlen
	)

Parse a DER ECDSA signature.

Returns: 1 when the signature could be parsed, 0 otherwise. Args: ctx: a secp256k1 context object Out: sig: a pointer to a signature object In: input: a pointer to the signature to be parsed inputlen: the length of the array pointed to be input

This function will accept any valid DER encoded signature, even if the encoded numbers are out of range.

After the call, sig will always be initialized. If parsing failed or the encoded numbers are out of range, signature validation with it is guaranteed to fail for every message and public key.

Definition at line 233 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_ecdsa_sig_parse(), secp256k1_ecdsa_signature_save(), and VERIFY_CHECK.

Referenced by benchmark_verify(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1ecdsa_1verify(), test_ecdsa_der_parse(), test_ecdsa_edge_cases(), test_ecdsa_end_to_end(), and test_ecdsa_recovery_edge_cases().

secp256k1_ecdsa_signature_save()

static void secp256k1_ecdsa_signature_save ( secp256k1_ecdsa_signature *  sig, const secp256k1_scalar *  r, const secp256k1_scalar *  s  )

static

Definition at line 223 of file secp256k1.c.

References secp256k1_ecdsa_signature::data, memcpy(), and secp256k1_scalar_get_b32().

Referenced by secp256k1_ecdsa_recoverable_signature_convert(), secp256k1_ecdsa_sign(), secp256k1_ecdsa_signature_normalize(), secp256k1_ecdsa_signature_parse_compact(), secp256k1_ecdsa_signature_parse_der(), test_ecdsa_end_to_end(), and test_exhaustive_verify().

secp256k1_ecdsa_signature_serialize_compact()

int secp256k1_ecdsa_signature_serialize_compact	(	const secp256k1_context *	ctx,
		unsigned char *	output64,
		const secp256k1_ecdsa_signature *	sig
	)

Serialize an ECDSA signature in compact (64 byte) format.

Returns: 1 Args: ctx: a secp256k1 context object Out: output64: a pointer to a 64-byte array to store the compact serialization In: sig: a pointer to an initialized signature object

See secp256k1_ecdsa_signature_parse_compact for details about the encoding.

Definition at line 282 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_ecdsa_signature_load(), secp256k1_scalar_get_b32(), and VERIFY_CHECK.

Referenced by test_ecdsa_der_parse(), and test_ecdsa_edge_cases().

secp256k1_ecdsa_signature_serialize_der()

int secp256k1_ecdsa_signature_serialize_der	(	const secp256k1_context *	ctx,
		unsigned char *	output,
		size_t *	outputlen,
		const secp256k1_ecdsa_signature *	sig
	)

Serialize an ECDSA signature in DER format.

Returns: 1 if enough space was available to serialize, 0 otherwise Args: ctx: a secp256k1 context object Out: output: a pointer to an array to store the DER serialization In/Out: outputlen: a pointer to a length integer. Initially, this integer should be set to the length of output. After the call it will be set to the length of the serialization (even if 0 was returned). In: sig: a pointer to an initialized signature object

Definition at line 270 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_ecdsa_sig_serialize(), secp256k1_ecdsa_signature_load(), and VERIFY_CHECK.

Referenced by bench_sign_run(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1ecdsa_1sign(), main(), CKey::Sign(), test_ecdsa_der_parse(), test_ecdsa_edge_cases(), and test_ecdsa_end_to_end().

secp256k1_ecdsa_verify()

int secp256k1_ecdsa_verify	(	const secp256k1_context *	ctx,
		const secp256k1_ecdsa_signature *	sig,
		const unsigned char *	msg32,
		const secp256k1_pubkey *	pubkey
	)

Verify an ECDSA signature.

Returns: 1: correct signature 0: incorrect or unparseable signature Args: ctx: a secp256k1 context object, initialized for verification. In: sig: the signature being verified (cannot be NULL) msg32: the 32-byte message hash being verified (cannot be NULL) pubkey: pointer to an initialized public key to verify with (cannot be NULL)

To avoid accepting malleable signatures, only ECDSA signatures in lower-S form are accepted.

If you need to accept ECDSA signatures from sources that do not obey this rule, apply secp256k1_ecdsa_signature_normalize to the signature prior to validation, but be aware that doing so results in malleable signatures.

For details, see the comments for that function.

Definition at line 314 of file secp256k1.c.

References ARG_CHECK, ctx, secp256k1_context_struct::ecmult_ctx, secp256k1_ecdsa_sig_verify(), secp256k1_ecdsa_signature_load(), secp256k1_ecmult_context_is_built(), secp256k1_pubkey_load(), secp256k1_scalar_is_high(), secp256k1_scalar_set_b32(), and VERIFY_CHECK.

Referenced by benchmark_verify(), Java_org_bitcoin_NativeSecp256k1_secp256k1_1ecdsa_1verify(), run_context_tests(), test_ecdsa_edge_cases(), test_ecdsa_end_to_end(), test_ecdsa_recovery_edge_cases(), test_ecdsa_recovery_end_to_end(), test_exhaustive_verify(), and CPubKey::Verify().

secp256k1_pubkey_load()

static int secp256k1_pubkey_load ( const secp256k1_context *  ctx, secp256k1_ge *  ge, const secp256k1_pubkey *  pubkey  )

static

Definition at line 138 of file secp256k1.c.

References ARG_CHECK, secp256k1_pubkey::data, memcpy(), secp256k1_fe_is_zero(), secp256k1_fe_set_b32(), secp256k1_ge_from_storage(), secp256k1_ge_set_xy(), and secp256k1_ge::x.

Referenced by ec_pubkey_parse_pointtest(), run_ec_pubkey_parse_test(), secp256k1_ec_pubkey_combine(), secp256k1_ec_pubkey_negate(), secp256k1_ec_pubkey_serialize(), secp256k1_ec_pubkey_tweak_add(), secp256k1_ec_pubkey_tweak_mul(), secp256k1_ecdh(), and secp256k1_ecdsa_verify().

secp256k1_pubkey_save()

static void secp256k1_pubkey_save ( secp256k1_pubkey *  pubkey, secp256k1_ge *  ge  )

static

Definition at line 157 of file secp256k1.c.

References secp256k1_pubkey::data, memcpy(), secp256k1_fe_get_b32(), secp256k1_fe_normalize_var(), secp256k1_ge_is_infinity(), secp256k1_ge_to_storage(), VERIFY_CHECK, secp256k1_ge::x, and secp256k1_ge::y.

Referenced by ec_pubkey_parse_pointtest(), secp256k1_ec_pubkey_combine(), secp256k1_ec_pubkey_create(), secp256k1_ec_pubkey_negate(), secp256k1_ec_pubkey_parse(), secp256k1_ec_pubkey_tweak_add(), secp256k1_ec_pubkey_tweak_mul(), secp256k1_ecdsa_recover(), test_ec_combine(), and test_exhaustive_verify().

secp256k1_scratch_space_create()

secp256k1_scratch_space* secp256k1_scratch_space_create	(	const secp256k1_context *	ctx,
		size_t	max_size
	)

Create a secp256k1 scratch space object.

Returns: a newly created scratch space. Args: ctx: an existing context object (cannot be NULL) In: max_size: maximum amount of memory to allocate

Definition at line 129 of file secp256k1.c.

References ctx, secp256k1_context_struct::error_callback, secp256k1_scratch_create(), and VERIFY_CHECK.

Referenced by main(), and run_scratch_tests().

secp256k1_scratch_space_destroy()

void secp256k1_scratch_space_destroy

(

secp256k1_scratch_space *

scratch

)

Destroy a secp256k1 scratch space.

The pointer may not be used afterwards. Args: scratch: space to destroy

Definition at line 134 of file secp256k1.c.

References secp256k1_scratch_destroy().

Referenced by main(), and run_scratch_tests().

Variable Documentation

default_error_callback

const secp256k1_callback default_error_callback

static

Initial value:

= {
    default_error_callback_fn,
    NULL
}

Definition at line 46 of file secp256k1.c.

Referenced by secp256k1_context_create().

default_illegal_callback

const secp256k1_callback default_illegal_callback

static

Initial value:

= {
    default_illegal_callback_fn,
    NULL
}

Definition at line 35 of file secp256k1.c.

Referenced by secp256k1_context_create().

secp256k1_context_no_precomp

const secp256k1_context* secp256k1_context_no_precomp = &secp256k1_context_no_precomp_

A simple secp256k1 context object with no precomputed tables.

These are useful for type serialization/parsing functions which require a context object to maintain API consistency, but currently do not require expensive precomputations or dynamic allocations.

Definition at line 65 of file secp256k1.c.

Referenced by run_ec_pubkey_parse_test(), secp256k1_context_destroy(), secp256k1_context_set_error_callback(), and secp256k1_context_set_illegal_callback().

secp256k1_context_no_precomp_

const secp256k1_context secp256k1_context_no_precomp_

static

Initial value:

= {
    { 0 },
    { 0 },
    { default_illegal_callback_fn, 0 },
    { default_error_callback_fn, 0 }
}

Definition at line 59 of file secp256k1.c.

secp256k1_nonce_function_default

const secp256k1_nonce_function secp256k1_nonce_function_default = nonce_function_rfc6979

A default safe nonce generation function (currently equal to secp256k1_nonce_function_rfc6979).

Definition at line 367 of file secp256k1.c.

Referenced by secp256k1_ecdsa_sign(), and secp256k1_ecdsa_sign_recoverable().

secp256k1_nonce_function_rfc6979

const secp256k1_nonce_function secp256k1_nonce_function_rfc6979 = nonce_function_rfc6979

An implementation of RFC6979 (using HMAC-SHA256) as nonce generation function.

If a data pointer is passed, it is assumed to be a pointer to 32 bytes of extra entropy.

Definition at line 366 of file secp256k1.c.

Referenced by CKey::Sign(), and CKey::SignCompact().