Changeset View
Changeset View
Standalone View
Standalone View
src/secp256k1/include/secp256k1.h
#ifndef SECP256K1_H | #ifndef SECP256K1_H | ||||
#define SECP256K1_H | #define SECP256K1_H | ||||
#ifdef __cplusplus | #ifdef __cplusplus | ||||
extern "C" { | extern "C" { | ||||
#endif | #endif | ||||
#include <stddef.h> | #include <stddef.h> | ||||
/* These rules specify the order of arguments in API calls: | /* These rules specify the order of arguments in API calls: | ||||
* | * | ||||
* 1. Context pointers go first, followed by output arguments, combined | * 1. Context pointers go first, followed by output arguments, combined | ||||
* output/input arguments, and finally input-only arguments. | * output/input arguments, and finally input-only arguments. | ||||
* 2. Array lengths always immediately the follow the argument whose length | * 2. Array lengths always immediately the follow the argument whose length | ||||
* they describe, even if this violates rule 1. | * they describe, even if this violates rule 1. | ||||
* 3. Within the OUT/OUTIN/IN groups, pointers to data that is typically generated | * 3. Within the OUT/OUTIN/IN groups, pointers to data that is typically generated | ||||
* later go first. This means: signatures, public nonces, private nonces, | * later go first. This means: signatures, public nonces, secret nonces, | ||||
* messages, public keys, secret keys, tweaks. | * messages, public keys, secret keys, tweaks. | ||||
* 4. Arguments that are not data pointers go last, from more complex to less | * 4. Arguments that are not data pointers go last, from more complex to less | ||||
* complex: function pointers, algorithm names, messages, void pointers, | * complex: function pointers, algorithm names, messages, void pointers, | ||||
* counts, flags, booleans. | * counts, flags, booleans. | ||||
* 5. Opaque data pointers follow the function pointer they are to be passed to. | * 5. Opaque data pointers follow the function pointer they are to be passed to. | ||||
*/ | */ | ||||
/** Opaque data structure that holds context information (precomputed tables etc.). | /** Opaque data structure that holds context information (precomputed tables etc.). | ||||
▲ Show 20 Lines • Show All 500 Lines • ▼ Show 20 Lines | |||||
SECP256K1_API extern const secp256k1_nonce_function secp256k1_nonce_function_rfc6979; | SECP256K1_API extern const secp256k1_nonce_function secp256k1_nonce_function_rfc6979; | ||||
/** A default safe nonce generation function (currently equal to secp256k1_nonce_function_rfc6979). */ | /** A default safe nonce generation function (currently equal to secp256k1_nonce_function_rfc6979). */ | ||||
SECP256K1_API extern const secp256k1_nonce_function secp256k1_nonce_function_default; | SECP256K1_API extern const secp256k1_nonce_function secp256k1_nonce_function_default; | ||||
/** Create an ECDSA signature. | /** Create an ECDSA signature. | ||||
* | * | ||||
* Returns: 1: signature created | * Returns: 1: signature created | ||||
* 0: the nonce generation function failed, or the private key was invalid. | * 0: the nonce generation function failed, or the secret key was invalid. | ||||
* Args: ctx: pointer to a context object, initialized for signing (cannot be NULL) | * 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) | * 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) | * In: msg32: the 32-byte message hash being signed (cannot be NULL) | ||||
* seckey: pointer to a 32-byte secret key (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 | * 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) | * ndata: pointer to arbitrary data used by the nonce generation function (can be NULL) | ||||
* | * | ||||
* The created signature is always in lower-S form. See | * The created signature is always in lower-S form. See | ||||
* secp256k1_ecdsa_signature_normalize for more details. | * secp256k1_ecdsa_signature_normalize for more details. | ||||
*/ | */ | ||||
SECP256K1_API int secp256k1_ecdsa_sign( | SECP256K1_API int secp256k1_ecdsa_sign( | ||||
const secp256k1_context* ctx, | const secp256k1_context* ctx, | ||||
secp256k1_ecdsa_signature *sig, | secp256k1_ecdsa_signature *sig, | ||||
const unsigned char *msg32, | const unsigned char *msg32, | ||||
const unsigned char *seckey, | const unsigned char *seckey, | ||||
secp256k1_nonce_function noncefp, | secp256k1_nonce_function noncefp, | ||||
const void *ndata | const void *ndata | ||||
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4); | ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4); | ||||
/** Verify an ECDSA secret key. | /** Verify an ECDSA secret key. | ||||
* | * | ||||
* A secret key is valid if it is not 0 and less than the secp256k1 curve order | |||||
* when interpreted as an integer (most significant byte first). The | |||||
* probability of choosing a 32-byte string uniformly at random which is an | |||||
* invalid secret key is negligible. | |||||
* | |||||
* Returns: 1: secret key is valid | * Returns: 1: secret key is valid | ||||
* 0: secret key is invalid | * 0: secret key is invalid | ||||
* Args: ctx: pointer to a context object (cannot be NULL) | * Args: ctx: pointer to a context object (cannot be NULL) | ||||
* In: seckey: pointer to a 32-byte secret key (cannot be NULL) | * In: seckey: pointer to a 32-byte secret key (cannot be NULL) | ||||
*/ | */ | ||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_verify( | SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_verify( | ||||
const secp256k1_context* ctx, | const secp256k1_context* ctx, | ||||
const unsigned char *seckey | const unsigned char *seckey | ||||
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2); | ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2); | ||||
/** Compute the public key for a secret key. | /** Compute the public key for a secret key. | ||||
* | * | ||||
* Returns: 1: secret was valid, public key stores | * Returns: 1: secret was valid, public key stores | ||||
* 0: secret was invalid, try again | * 0: secret was invalid, try again | ||||
* Args: ctx: pointer to a context object, initialized for signing (cannot be NULL) | * Args: ctx: pointer to a context object, initialized for signing (cannot be NULL) | ||||
* Out: pubkey: pointer to the created public key (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) | * In: seckey: pointer to a 32-byte secret key (cannot be NULL) | ||||
*/ | */ | ||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_create( | SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_create( | ||||
const secp256k1_context* ctx, | const secp256k1_context* ctx, | ||||
secp256k1_pubkey *pubkey, | secp256k1_pubkey *pubkey, | ||||
const unsigned char *seckey | const unsigned char *seckey | ||||
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | ||||
/** Negates a private key in place. | /** Negates a secret key in place. | ||||
* | * | ||||
* Returns: 1 always | * Returns: 0 if the given secret key is invalid according to | ||||
* secp256k1_ec_seckey_verify. 1 otherwise | |||||
* Args: ctx: pointer to a context object | * Args: ctx: pointer to a context object | ||||
* In/Out: seckey: pointer to the 32-byte private key to be negated (cannot be NULL) | * In/Out: seckey: pointer to the 32-byte secret key to be negated. If the | ||||
* secret key is invalid according to | |||||
* secp256k1_ec_seckey_verify, this function returns 0 and | |||||
* seckey will be set to some unspecified value. (cannot be | |||||
* NULL) | |||||
*/ | */ | ||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_negate( | |||||
const secp256k1_context* ctx, | |||||
unsigned char *seckey | |||||
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2); | |||||
/** Same as secp256k1_ec_seckey_negate, but DEPRECATED. Will be removed in | |||||
* future versions. */ | |||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_negate( | SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_negate( | ||||
const secp256k1_context* ctx, | const secp256k1_context* ctx, | ||||
unsigned char *seckey | unsigned char *seckey | ||||
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2); | ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2); | ||||
/** Negates a public key in place. | /** Negates a public key in place. | ||||
* | * | ||||
* Returns: 1 always | * Returns: 1 always | ||||
* Args: ctx: pointer to a context object | * Args: ctx: pointer to a context object | ||||
* In/Out: pubkey: pointer to the public key to be negated (cannot be NULL) | * In/Out: pubkey: pointer to the public key to be negated (cannot be NULL) | ||||
*/ | */ | ||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_negate( | SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_negate( | ||||
const secp256k1_context* ctx, | const secp256k1_context* ctx, | ||||
secp256k1_pubkey *pubkey | secp256k1_pubkey *pubkey | ||||
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2); | ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2); | ||||
/** Tweak a private key by adding tweak to it. | /** Tweak a secret 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 | * Returns: 0 if the arguments are invalid or the resulting secret key would be | ||||
* would be invalid (only when the tweak is the complement of the | * invalid (only when the tweak is the negation of the secret key). 1 | ||||
* private key). 1 otherwise. | * otherwise. | ||||
* Args: ctx: pointer to a context object (cannot be NULL). | * Args: ctx: pointer to a context object (cannot be NULL). | ||||
* In/Out: seckey: pointer to a 32-byte private key. | * In/Out: seckey: pointer to a 32-byte secret key. If the secret key is | ||||
* In: tweak: pointer to a 32-byte tweak. | * invalid according to secp256k1_ec_seckey_verify, this | ||||
* function returns 0. seckey will be set to some unspecified | |||||
* value if this function returns 0. (cannot be NULL) | |||||
* In: tweak: pointer to a 32-byte tweak. If the tweak is invalid according to | |||||
* secp256k1_ec_seckey_verify, this function returns 0. For | |||||
* uniformly random 32-byte arrays the chance of being invalid | |||||
* is negligible (around 1 in 2^128) (cannot be NULL). | |||||
*/ | */ | ||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_add( | |||||
const secp256k1_context* ctx, | |||||
unsigned char *seckey, | |||||
const unsigned char *tweak | |||||
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | |||||
/** Same as secp256k1_ec_seckey_tweak_add, but DEPRECATED. Will be removed in | |||||
* future versions. */ | |||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_add( | SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_add( | ||||
const secp256k1_context* ctx, | const secp256k1_context* ctx, | ||||
unsigned char *seckey, | unsigned char *seckey, | ||||
const unsigned char *tweak | const unsigned char *tweak | ||||
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | ||||
/** Tweak a public key by adding tweak times the generator to it. | /** 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 | * Returns: 0 if the arguments are invalid or the resulting public key would be | ||||
* would be invalid (only when the tweak is the complement of the | * invalid (only when the tweak is the negation of the corresponding | ||||
* corresponding private key). 1 otherwise. | * secret key). 1 otherwise. | ||||
* Args: ctx: pointer to a context object initialized for validation | * Args: ctx: pointer to a context object initialized for validation | ||||
* (cannot be NULL). | * (cannot be NULL). | ||||
* In/Out: pubkey: pointer to a public key object. | * In/Out: pubkey: pointer to a public key object. pubkey will be set to an | ||||
* In: tweak: pointer to a 32-byte tweak. | * invalid value if this function returns 0 (cannot be NULL). | ||||
* In: tweak: pointer to a 32-byte tweak. If the tweak is invalid according to | |||||
* secp256k1_ec_seckey_verify, this function returns 0. For | |||||
* uniformly random 32-byte arrays the chance of being invalid | |||||
* is negligible (around 1 in 2^128) (cannot be NULL). | |||||
*/ | */ | ||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_add( | SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_add( | ||||
const secp256k1_context* ctx, | const secp256k1_context* ctx, | ||||
secp256k1_pubkey *pubkey, | secp256k1_pubkey *pubkey, | ||||
const unsigned char *tweak | const unsigned char *tweak | ||||
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | ||||
/** Tweak a private key by multiplying it by a tweak. | /** Tweak a secret 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. | * Returns: 0 if the arguments are invalid. 1 otherwise. | ||||
* Args: ctx: pointer to a context object (cannot be NULL). | * Args: ctx: pointer to a context object (cannot be NULL). | ||||
* In/Out: seckey: pointer to a 32-byte private key. | * In/Out: seckey: pointer to a 32-byte secret key. If the secret key is | ||||
* In: tweak: pointer to a 32-byte tweak. | * invalid according to secp256k1_ec_seckey_verify, this | ||||
* function returns 0. seckey will be set to some unspecified | |||||
* value if this function returns 0. (cannot be NULL) | |||||
* In: tweak: pointer to a 32-byte tweak. If the tweak is invalid according to | |||||
* secp256k1_ec_seckey_verify, this function returns 0. For | |||||
* uniformly random 32-byte arrays the chance of being invalid | |||||
* is negligible (around 1 in 2^128) (cannot be NULL). | |||||
*/ | */ | ||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_mul( | |||||
const secp256k1_context* ctx, | |||||
unsigned char *seckey, | |||||
const unsigned char *tweak | |||||
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | |||||
/** Same as secp256k1_ec_seckey_tweak_mul, but DEPRECATED. Will be removed in | |||||
* future versions. */ | |||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_mul( | SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_mul( | ||||
const secp256k1_context* ctx, | const secp256k1_context* ctx, | ||||
unsigned char *seckey, | unsigned char *seckey, | ||||
const unsigned char *tweak | const unsigned char *tweak | ||||
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | ||||
/** Tweak a public key by multiplying it by a tweak value. | /** 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. | * Returns: 0 if the arguments are invalid. 1 otherwise. | ||||
* Args: ctx: pointer to a context object initialized for validation | * Args: ctx: pointer to a context object initialized for validation | ||||
* (cannot be NULL). | * (cannot be NULL). | ||||
* In/Out: pubkey: pointer to a public key object. | * In/Out: pubkey: pointer to a public key object. pubkey will be set to an | ||||
* In: tweak: pointer to a 32-byte tweak. | * invalid value if this function returns 0 (cannot be NULL). | ||||
* In: tweak: pointer to a 32-byte tweak. If the tweak is invalid according to | |||||
* secp256k1_ec_seckey_verify, this function returns 0. For | |||||
* uniformly random 32-byte arrays the chance of being invalid | |||||
* is negligible (around 1 in 2^128) (cannot be NULL). | |||||
*/ | */ | ||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_mul( | SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_mul( | ||||
const secp256k1_context* ctx, | const secp256k1_context* ctx, | ||||
secp256k1_pubkey *pubkey, | secp256k1_pubkey *pubkey, | ||||
const unsigned char *tweak | const unsigned char *tweak | ||||
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | ||||
/** Updates the context randomization to protect against side-channel leakage. | /** Updates the context randomization to protect against side-channel leakage. | ||||
Show All 22 Lines | |||||
* secp256k1_context_clone, resp.), and you may call this repeatedly afterwards. | * secp256k1_context_clone, resp.), and you may call this repeatedly afterwards. | ||||
*/ | */ | ||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_context_randomize( | SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_context_randomize( | ||||
secp256k1_context* ctx, | secp256k1_context* ctx, | ||||
const unsigned char *seed32 | const unsigned char *seed32 | ||||
) SECP256K1_ARG_NONNULL(1); | ) SECP256K1_ARG_NONNULL(1); | ||||
/** Add a number of public keys together. | /** Add a number of public keys together. | ||||
* | |||||
* Returns: 1: the sum of the public keys is valid. | * Returns: 1: the sum of the public keys is valid. | ||||
* 0: the sum of the public keys is not valid. | * 0: the sum of the public keys is not valid. | ||||
* Args: ctx: pointer to a context object | * Args: ctx: pointer to a context object | ||||
* Out: out: pointer to a public key object for placing the resulting public key | * Out: out: pointer to a public key object for placing the resulting public key | ||||
* (cannot be NULL) | * (cannot be NULL) | ||||
* In: ins: pointer to array of pointers to public keys (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) | * n: the number of public keys to add together (must be at least 1) | ||||
*/ | */ | ||||
Show All 12 Lines |