Changeset View
Changeset View
Standalone View
Standalone View
src/secp256k1/include/secp256k1.h
Show First 20 Lines • Show All 446 Lines • ▼ Show 20 Lines | |||||
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | ||||
/** Verify an ECDSA signature. | /** Verify an ECDSA signature. | ||||
* | * | ||||
* Returns: 1: correct signature | * Returns: 1: correct signature | ||||
* 0: incorrect or unparseable signature | * 0: incorrect or unparseable signature | ||||
* Args: ctx: a secp256k1 context object, initialized for verification. | * Args: ctx: a secp256k1 context object, initialized for verification. | ||||
* In: sig: the signature being verified (cannot be NULL) | * In: sig: the signature being verified (cannot be NULL) | ||||
* msg32: the 32-byte message hash being verified (cannot be NULL) | * msghash32: the 32-byte message hash being verified (cannot be NULL). | ||||
* The verifier must make sure to apply a cryptographic | |||||
* hash function to the message by itself and not accept an | |||||
* msghash32 value directly. Otherwise, it would be easy to | |||||
* create a "valid" signature without knowledge of the | |||||
* secret key. See also | |||||
* https://bitcoin.stackexchange.com/a/81116/35586 for more | |||||
* background on this topic. | |||||
* pubkey: pointer to an initialized public key to verify with (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 | * To avoid accepting malleable signatures, only ECDSA signatures in lower-S | ||||
* form are accepted. | * form are accepted. | ||||
* | * | ||||
* If you need to accept ECDSA signatures from sources that do not obey this | * 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 | * rule, apply secp256k1_ecdsa_signature_normalize to the signature prior to | ||||
* validation, but be aware that doing so results in malleable signatures. | * validation, but be aware that doing so results in malleable signatures. | ||||
* | * | ||||
* For details, see the comments for that function. | * For details, see the comments for that function. | ||||
*/ | */ | ||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_verify( | SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_verify( | ||||
const secp256k1_context* ctx, | const secp256k1_context* ctx, | ||||
const secp256k1_ecdsa_signature *sig, | const secp256k1_ecdsa_signature *sig, | ||||
const unsigned char *msg32, | const unsigned char *msghash32, | ||||
const secp256k1_pubkey *pubkey | const secp256k1_pubkey *pubkey | ||||
) 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); | ||||
/** Convert a signature to a normalized lower-S form. | /** Convert a signature to a normalized lower-S form. | ||||
* | * | ||||
* Returns: 1 if sigin was not normalized, 0 if it already was. | * Returns: 1 if sigin was not normalized, 0 if it already was. | ||||
* Args: ctx: a secp256k1 context object | * Args: ctx: a secp256k1 context object | ||||
* Out: sigout: a pointer to a signature to fill with the normalized form, | * Out: sigout: a pointer to a signature to fill with the normalized form, | ||||
▲ Show 20 Lines • Show All 48 Lines • ▼ Show 20 Lines | |||||
/** 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 secret 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: msghash32: 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 *msghash32, | ||||
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 | * A secret key is valid if it is not 0 and less than the secp256k1 curve order | ||||
▲ Show 20 Lines • Show All 64 Lines • ▼ Show 20 Lines | |||||
* Returns: 0 if the arguments are invalid or the resulting secret key would be | * Returns: 0 if the arguments are invalid or the resulting secret key would be | ||||
* invalid (only when the tweak is the negation of the secret key). 1 | * invalid (only when the tweak is the negation of the secret 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 secret key. If the secret key is | * In/Out: seckey: pointer to a 32-byte secret key. If the secret key is | ||||
* invalid according to secp256k1_ec_seckey_verify, this | * invalid according to secp256k1_ec_seckey_verify, this | ||||
* function returns 0. seckey will be set to some unspecified | * function returns 0. seckey will be set to some unspecified | ||||
* value if this function returns 0. (cannot be NULL) | * value if this function returns 0. (cannot be NULL) | ||||
* In: tweak: pointer to a 32-byte tweak. If the tweak is invalid according to | * In: tweak32: pointer to a 32-byte tweak. If the tweak is invalid according to | ||||
* secp256k1_ec_seckey_verify, this function returns 0. For | * secp256k1_ec_seckey_verify, this function returns 0. For | ||||
* uniformly random 32-byte arrays the chance of being invalid | * uniformly random 32-byte arrays the chance of being invalid | ||||
* is negligible (around 1 in 2^128) (cannot be NULL). | * is negligible (around 1 in 2^128) (cannot be NULL). | ||||
*/ | */ | ||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_add( | SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_add( | ||||
const secp256k1_context* ctx, | const secp256k1_context* ctx, | ||||
unsigned char *seckey, | unsigned char *seckey, | ||||
const unsigned char *tweak | const unsigned char *tweak32 | ||||
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | ) 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 | /** Same as secp256k1_ec_seckey_tweak_add, but DEPRECATED. Will be removed in | ||||
* future versions. */ | * 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 *tweak32 | ||||
) 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 arguments are invalid or the resulting public key would be | * Returns: 0 if the arguments are invalid or the resulting public key would be | ||||
* invalid (only when the tweak is the negation of the corresponding | * invalid (only when the tweak is the negation of the corresponding | ||||
* secret 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. pubkey will be set to an | * In/Out: pubkey: pointer to a public key object. pubkey will be set to an | ||||
* invalid value if this function returns 0 (cannot be NULL). | * 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 | * In: tweak32: pointer to a 32-byte tweak. If the tweak is invalid according to | ||||
* secp256k1_ec_seckey_verify, this function returns 0. For | * secp256k1_ec_seckey_verify, this function returns 0. For | ||||
* uniformly random 32-byte arrays the chance of being invalid | * uniformly random 32-byte arrays the chance of being invalid | ||||
* is negligible (around 1 in 2^128) (cannot be NULL). | * 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 *tweak32 | ||||
) 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 secret key by multiplying it by a tweak. | /** Tweak a secret key by multiplying it by a tweak. | ||||
* | * | ||||
* Returns: 0 if the arguments are invalid. 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 secret key. If the secret key is | * In/Out: seckey: pointer to a 32-byte secret key. If the secret key is | ||||
* invalid according to secp256k1_ec_seckey_verify, this | * invalid according to secp256k1_ec_seckey_verify, this | ||||
* function returns 0. seckey will be set to some unspecified | * function returns 0. seckey will be set to some unspecified | ||||
* value if this function returns 0. (cannot be NULL) | * value if this function returns 0. (cannot be NULL) | ||||
* In: tweak: pointer to a 32-byte tweak. If the tweak is invalid according to | * In: tweak32: pointer to a 32-byte tweak. If the tweak is invalid according to | ||||
* secp256k1_ec_seckey_verify, this function returns 0. For | * secp256k1_ec_seckey_verify, this function returns 0. For | ||||
* uniformly random 32-byte arrays the chance of being invalid | * uniformly random 32-byte arrays the chance of being invalid | ||||
* is negligible (around 1 in 2^128) (cannot be NULL). | * is negligible (around 1 in 2^128) (cannot be NULL). | ||||
*/ | */ | ||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_mul( | SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_mul( | ||||
const secp256k1_context* ctx, | const secp256k1_context* ctx, | ||||
unsigned char *seckey, | unsigned char *seckey, | ||||
const unsigned char *tweak | const unsigned char *tweak32 | ||||
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); | ) 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 | /** Same as secp256k1_ec_seckey_tweak_mul, but DEPRECATED. Will be removed in | ||||
* future versions. */ | * 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 *tweak32 | ||||
) 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 arguments are invalid. 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. pubkey will be set to an | * In/Out: pubkey: pointer to a public key object. pubkey will be set to an | ||||
* invalid value if this function returns 0 (cannot be NULL). | * 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 | * In: tweak32: pointer to a 32-byte tweak. If the tweak is invalid according to | ||||
* secp256k1_ec_seckey_verify, this function returns 0. For | * secp256k1_ec_seckey_verify, this function returns 0. For | ||||
* uniformly random 32-byte arrays the chance of being invalid | * uniformly random 32-byte arrays the chance of being invalid | ||||
* is negligible (around 1 in 2^128) (cannot be NULL). | * 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 *tweak32 | ||||
) 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. | ||||
* Returns: 1: randomization successfully updated or nothing to randomize | * Returns: 1: randomization successfully updated or nothing to randomize | ||||
* 0: error | * 0: error | ||||
* Args: ctx: pointer to a context object (cannot be NULL) | * Args: ctx: pointer to a context object (cannot be NULL) | ||||
* In: seed32: pointer to a 32-byte random seed (NULL resets to initial state) | * In: seed32: pointer to a 32-byte random seed (NULL resets to initial state) | ||||
* | * | ||||
▲ Show 20 Lines • Show All 46 Lines • Show Last 20 Lines |