Page MenuHomePhabricator
Differential D9376 Diff 28091 src/secp256k1/include/secp256k1.h

Changeset View

Standalone View

View Options

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