frost/secp256k1-zkp
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge bitcoin-core/secp256k1#783: Make the public API docs more consistent and explicit

Browse Source 
adec5a16383f1704d80d7c767b2a65d9221cee08 Add missing null check for ctx and input keys in the public API (Elichai Turkel)
f4edfc758142d6e100ca5d086126bf532b8a7020 Improve consistency for NULL arguments in the public interface (Elichai Turkel)

Pull request description:

  I went over the public API and added missing explanations on when a pointer can be null and when it cannot,
  and added some missing checks for null ctx and null pubkey pointers.

  Open questions IMHO:
  1. Can `secp256k1_context_create` return NULL? right now it could return null if you replaced the callbacks at compile time to ones that do return(unlike the default ones which never return).
  2. Related to the first, should we document that the callbacks should never return? (in the tests we use returning callbacks but we can violate our own API) right now we say the following:

  > After this callback returns, anything may happen, including crashing.

  Is this enough to document answer `no` for the first question and just saying that if the callback returned then you violated the API so `secp256k1_context_create` can return NULL even though it is promised not to?
  Right now we AFAICT we never check if it returns null

  Another nit I'm not sure about is wording `(does nothing if NULL)`/`(ignored if NULL)`/`(can be NULL)`

  More missing docs:
  1. Documenting the `data` argument to the default nonce functions

ACKs for top commit:
  ariard:
    ACK adec5a16
  jonasnick:
    ACK adec5a16383f1704d80d7c767b2a65d9221cee08

Tree-SHA512: 6fe785776b7e451e9e8cae944987f927b1eb2e2d404dfcb1b0ceb0a30bda4ce16469708920269417e5ada09739723a430e270dea1868fe7d12ccd5699dde5976
This commit is contained in:
Tim Ruffing 2021-09-15 16:23:55 +02:00
commit aa5d34a8fe
No known key found for this signature in database
GPG Key ID: 8C461CCD293F6011
8 changed files with 125 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
include/secp256k1.h
View File

@ -226,7 +226,7 @@ SECP256K1_API secp256k1_context* secp256k1_context_create(
* memory allocation entirely, see the functions in secp256k1_preallocated.h. * memory allocation entirely, see the functions in secp256k1_preallocated.h.
* *
* Returns: a newly created context object. * Returns: a newly created context object.
* Args: ctx: an existing context to copy (cannot be NULL) * Args: ctx: an existing context to copy
*/ */
SECP256K1_API secp256k1_context* secp256k1_context_clone( SECP256K1_API secp256k1_context* secp256k1_context_clone(
const secp256k1_context* ctx const secp256k1_context* ctx
@ -247,7 +247,7 @@ SECP256K1_API secp256k1_context* secp256k1_context_clone(
*/ */
SECP256K1_API void secp256k1_context_destroy( SECP256K1_API void secp256k1_context_destroy(
secp256k1_context* ctx secp256k1_context* ctx
); ) SECP256K1_ARG_NONNULL(1);
/** Set a callback function to be called when an illegal argument is passed to /** 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 * an API call. It will only trigger for violations that are mentioned
@ -278,11 +278,11 @@ SECP256K1_API void secp256k1_context_destroy(
* fails. In this case, the corresponding default handler will be called with * fails. In this case, the corresponding default handler will be called with
* the data pointer argument set to NULL. * the data pointer argument set to NULL.
* *
* Args: ctx: an existing context object (cannot be NULL) * Args: ctx: an existing context object.
* In: fun: a pointer to a function to call when an illegal argument is * 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. * passed to the API, taking a message and an opaque pointer.
* (NULL restores the default handler.) * (NULL restores the default handler.)
* data: the opaque pointer to pass to fun above. * data: the opaque pointer to pass to fun above, must be NULL for the default handler.
* *
* See also secp256k1_context_set_error_callback. * See also secp256k1_context_set_error_callback.
*/ */
@ -302,12 +302,12 @@ SECP256K1_API void secp256k1_context_set_illegal_callback(
* for that). After this callback returns, anything may happen, including * for that). After this callback returns, anything may happen, including
* crashing. * crashing.
* *
* Args: ctx: an existing context object (cannot be NULL) * Args: ctx: an existing context object.
* In: fun: a pointer to a function to call when an internal error occurs, * In: fun: a pointer to a function to call when an internal error occurs,
* taking a message and an opaque pointer (NULL restores the * taking a message and an opaque pointer (NULL restores the
* default handler, see secp256k1_context_set_illegal_callback * default handler, see secp256k1_context_set_illegal_callback
* for details). * for details).
* data: the opaque pointer to pass to fun above. * data: the opaque pointer to pass to fun above, must be NULL for the default handler.
* *
* See also secp256k1_context_set_illegal_callback. * See also secp256k1_context_set_illegal_callback.
*/ */
@ -320,7 +320,7 @@ SECP256K1_API void secp256k1_context_set_error_callback(
/** Create a secp256k1 scratch space object. /** Create a secp256k1 scratch space object.
* *
* Returns: a newly created scratch space. * Returns: a newly created scratch space.
* Args: ctx: an existing context object (cannot be NULL) * Args: ctx: an existing context object.
* In: size: amount of memory to be available as scratch space. Some extra * In: size: amount of memory to be available as scratch space. Some extra
* (<100 bytes) will be allocated for extra accounting. * (<100 bytes) will be allocated for extra accounting.
*/ */
@ -480,8 +480,8 @@ SECP256K1_API int secp256k1_ecdsa_signature_serialize_compact(
* 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.
* msghash32: the 32-byte message hash being verified (cannot be NULL). * msghash32: the 32-byte message hash being verified.
* The verifier must make sure to apply a cryptographic * The verifier must make sure to apply a cryptographic
* hash function to the message by itself and not accept an * hash function to the message by itself and not accept an
* msghash32 value directly. Otherwise, it would be easy to * msghash32 value directly. Otherwise, it would be easy to
@ -489,7 +489,7 @@ SECP256K1_API int secp256k1_ecdsa_signature_serialize_compact(
* secret key. See also * secret key. See also
* https://bitcoin.stackexchange.com/a/81116/35586 for more * https://bitcoin.stackexchange.com/a/81116/35586 for more
* background on this topic. * 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.
* *
* 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.
@ -515,8 +515,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_verify(
* or copy if the input was already normalized. (can be NULL if * or copy if the input was already normalized. (can be NULL if
* you're only interested in whether the input was already * you're only interested in whether the input was already
* normalized). * normalized).
* In: sigin: a pointer to a signature to check/normalize (cannot be NULL, * In: sigin: a pointer to a signature to check/normalize (can be identical to sigout)
* can be identical to sigout)
* *
* With ECDSA a third-party can forge a second distinct signature of the same * 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 * message, given a single initial signature, but without knowing the key. This
@ -568,12 +567,16 @@ SECP256K1_API extern const secp256k1_nonce_function secp256k1_nonce_function_def
* *
* 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.
* 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.
* In: msghash32: the 32-byte message hash being signed (cannot be NULL) * In: msghash32: the 32-byte message hash being signed.
* seckey: pointer to a 32-byte secret key (cannot be NULL) * seckey: pointer to a 32-byte secret key.
* noncefp: pointer to a nonce generation function. If NULL, secp256k1_nonce_function_default is used * noncefp: pointer to a nonce generation function. If NULL,
* ndata: pointer to arbitrary data used by the nonce generation function (can be NULL) * secp256k1_nonce_function_default is used.
* ndata: pointer to arbitrary data used by the nonce generation function
* (can be NULL). If it is non-NULL and
* secp256k1_nonce_function_default is used, then ndata must be a
* pointer to 32-bytes of additional data.
* *
* 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.
@ -596,8 +599,8 @@ SECP256K1_API int secp256k1_ecdsa_sign(
* *
* 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.
* In: seckey: pointer to a 32-byte secret key (cannot be NULL) * In: seckey: pointer to a 32-byte secret key.
*/ */
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,
@ -606,11 +609,11 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_verify(
/** 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.
* Out: pubkey: pointer to the created public key (cannot be NULL) * Out: pubkey: pointer to the created public key.
* In: seckey: pointer to a 32-byte secret key (cannot be NULL) * In: seckey: pointer to a 32-byte secret key.
*/ */
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,
@ -626,8 +629,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_create(
* In/Out: seckey: pointer to the 32-byte secret key to be negated. If the * In/Out: seckey: pointer to the 32-byte secret key to be negated. If the
* secret key is invalid according to * secret key is invalid according to
* secp256k1_ec_seckey_verify, this function returns 0 and * secp256k1_ec_seckey_verify, this function returns 0 and
* seckey will be set to some unspecified value. (cannot be * seckey will be set to some unspecified value.
* NULL)
*/ */
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_negate( SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_negate(
const secp256k1_context* ctx, const secp256k1_context* ctx,
@ -645,7 +647,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_negate(
* *
* 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.
*/ */
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,
@ -657,15 +659,15 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_negate(
* 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.
* 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.
* In: tweak32: 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).
*/ */
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,
@ -686,14 +688,13 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_add(
* 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).
* 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.
* In: tweak32: 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).
*/ */
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,
@ -704,15 +705,15 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_add(
/** 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.
* 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.
* In: tweak32: 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).
*/ */
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,
@ -731,14 +732,13 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_mul(
/** 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).
* 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.
* In: tweak32: 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).
*/ */
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,
@ -749,7 +749,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_mul(
/** 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.
* 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)
* *
* While secp256k1 code is written to be constant-time no matter what secret * While secp256k1 code is written to be constant-time no matter what secret
@ -780,18 +780,17 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_context_randomize(
* *
* 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) * In: ins: pointer to array of pointers to public keys.
* 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)
*/ */
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_combine( SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_combine(
const secp256k1_context* ctx, const secp256k1_context* ctx,
secp256k1_pubkey *out, secp256k1_pubkey *out,
const secp256k1_pubkey * const * ins, const secp256k1_pubkey * const * ins,
size_t n size_t n
) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
/** Compute a tagged hash as defined in BIP-340. /** Compute a tagged hash as defined in BIP-340.
* *

15
include/secp256k1_ecdh.h
View File

@ -37,14 +37,15 @@ SECP256K1_API extern const secp256k1_ecdh_hash_function secp256k1_ecdh_hash_func
* *
* Returns: 1: exponentiation was successful * Returns: 1: exponentiation was successful
* 0: scalar was invalid (zero or overflow) or hashfp returned 0 * 0: scalar was invalid (zero or overflow) or hashfp returned 0
* Args: ctx: pointer to a context object (cannot be NULL) * Args: ctx: pointer to a context object.
* Out: output: pointer to an array to be filled by hashfp * Out: output: pointer to an array to be filled by hashfp.
* In: pubkey: a pointer to a secp256k1_pubkey containing an * In: pubkey: a pointer to a secp256k1_pubkey containing an initialized public key.
* initialized public key * seckey: a 32-byte scalar with which to multiply the point.
* seckey: a 32-byte scalar with which to multiply the point * hashfp: pointer to a hash function. If NULL,
* hashfp: pointer to a hash function. If NULL, secp256k1_ecdh_hash_function_sha256 is used * secp256k1_ecdh_hash_function_sha256 is used
* (in which case, 32 bytes will be written to output) * (in which case, 32 bytes will be written to output).
* data: arbitrary data pointer that is passed through to hashfp * data: arbitrary data pointer that is passed through to hashfp
* (can be NULL for secp256k1_ecdh_hash_function_sha256).
*/ */
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdh( SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdh(
const secp256k1_context* ctx, const secp256k1_context* ctx,

82
include/secp256k1_extrakeys.h
View File

@ -39,11 +39,10 @@ typedef struct {
* Returns: 1 if the public key was fully valid. * Returns: 1 if the public key was fully valid.
* 0 if the public key could not be parsed or is invalid. * 0 if the public key could not be parsed or is invalid.
* *
* Args: ctx: a secp256k1 context object (cannot be NULL). * Args: ctx: a secp256k1 context object.
* Out: pubkey: pointer to a pubkey object. If 1 is returned, it is set to a * Out: pubkey: pointer to a pubkey object. If 1 is returned, it is set to a
* parsed version of input. If not, it's set to an invalid value. * parsed version of input. If not, it's set to an invalid value.
* (cannot be NULL). * In: input32: pointer to a serialized xonly_pubkey.
* In: input32: pointer to a serialized xonly_pubkey (cannot be NULL)
*/ */
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_parse( SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_parse(
const secp256k1_context* ctx, const secp256k1_context* ctx,
@ -55,11 +54,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_parse(
* *
* Returns: 1 always. * Returns: 1 always.
* *
* Args: ctx: a secp256k1 context object (cannot be NULL). * Args: ctx: a secp256k1 context object.
* Out: output32: a pointer to a 32-byte array to place the serialized key in * Out: output32: a pointer to a 32-byte array to place the serialized key in.
* (cannot be NULL). * In: pubkey: a pointer to a secp256k1_xonly_pubkey containing an initialized public key.
* In: pubkey: a pointer to a secp256k1_xonly_pubkey containing an
* initialized public key (cannot be NULL).
*/ */
SECP256K1_API int secp256k1_xonly_pubkey_serialize( SECP256K1_API int secp256k1_xonly_pubkey_serialize(
const secp256k1_context* ctx, const secp256k1_context* ctx,
@ -87,13 +84,12 @@ SECP256K1_API int secp256k1_xonly_pubkey_cmp(
* Returns: 1 if the public key was successfully converted * Returns: 1 if the public key was successfully converted
* 0 otherwise * 0 otherwise
* *
* Args: ctx: pointer to a context object (cannot be NULL) * Args: ctx: pointer to a context object.
* Out: xonly_pubkey: pointer to an x-only public key object for placing the * Out: xonly_pubkey: pointer to an x-only public key object for placing the converted public key.
* converted public key (cannot be NULL) * pk_parity: Ignored if NULL. Otherwise, pointer to an integer that
* pk_parity: pointer to an integer that will be set to 1 if the point * will be set to 1 if the point encoded by xonly_pubkey is
* encoded by xonly_pubkey is the negation of the pubkey and * the negation of the pubkey and set to 0 otherwise.
* set to 0 otherwise. (can be NULL) * In: pubkey: pointer to a public key that is converted.
* In: pubkey: pointer to a public key that is converted (cannot be NULL)
*/ */
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_from_pubkey( SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_from_pubkey(
const secp256k1_context* ctx, const secp256k1_context* ctx,
@ -113,18 +109,14 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_from_pubke
* 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 verification * Args: ctx: pointer to a context object initialized for verification.
* (cannot be NULL)
* Out: output_pubkey: pointer to a public key to store the result. Will be set * Out: output_pubkey: pointer to a public key to store the result. Will be set
* to an invalid value if this function returns 0 (cannot * to an invalid value if this function returns 0.
* be NULL)
* In: internal_pubkey: pointer to an x-only pubkey to apply the tweak to. * In: internal_pubkey: pointer to an x-only pubkey to apply the tweak to.
* (cannot be NULL).
* tweak32: pointer to a 32-byte tweak. If the tweak is invalid * tweak32: pointer to a 32-byte tweak. If the tweak is invalid
* according to secp256k1_ec_seckey_verify, this function * according to secp256k1_ec_seckey_verify, this function
* returns 0. For uniformly random 32-byte arrays the * returns 0. For uniformly random 32-byte arrays the
* chance of being invalid is negligible (around 1 in * chance of being invalid is negligible (around 1 in 2^128).
* 2^128) (cannot be NULL).
*/ */
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_tweak_add( SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_tweak_add(
const secp256k1_context* ctx, const secp256k1_context* ctx,
@ -146,17 +138,15 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_tweak_add(
* *
* Returns: 0 if the arguments are invalid or the tweaked pubkey is not the * Returns: 0 if the arguments are invalid or the tweaked pubkey is not the
* result of tweaking the internal_pubkey with tweak32. 1 otherwise. * result of tweaking the internal_pubkey with tweak32. 1 otherwise.
* Args: ctx: pointer to a context object initialized for verification * Args: ctx: pointer to a context object initialized for verification.
* (cannot be NULL) * In: tweaked_pubkey32: pointer to a serialized xonly_pubkey.
* In: tweaked_pubkey32: pointer to a serialized xonly_pubkey (cannot be NULL)
* tweaked_pk_parity: the parity of the tweaked pubkey (whose serialization * tweaked_pk_parity: the parity of the tweaked pubkey (whose serialization
* is passed in as tweaked_pubkey32). This must match the * is passed in as tweaked_pubkey32). This must match the
* pk_parity value that is returned when calling * pk_parity value that is returned when calling
* secp256k1_xonly_pubkey with the tweaked pubkey, or * secp256k1_xonly_pubkey with the tweaked pubkey, or
* this function will fail. * this function will fail.
* internal_pubkey: pointer to an x-only public key object to apply the * internal_pubkey: pointer to an x-only public key object to apply the tweak to.
* tweak to (cannot be NULL) * tweak32: pointer to a 32-byte tweak.
* tweak32: pointer to a 32-byte tweak (cannot be NULL)
*/ */
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_tweak_add_check( SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_tweak_add_check(
const secp256k1_context* ctx, const secp256k1_context* ctx,
@ -170,9 +160,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_tweak_add_
* *
* Returns: 1: secret was valid, keypair is ready to use * Returns: 1: secret was valid, keypair is ready to use
* 0: secret was invalid, try again with a different secret * 0: secret was invalid, try again with a different secret
* Args: ctx: pointer to a context object, initialized for signing (cannot be NULL) * Args: ctx: pointer to a context object, initialized for signing.
* Out: keypair: pointer to the created keypair (cannot be NULL) * Out: keypair: pointer to the created keypair.
* In: seckey: pointer to a 32-byte secret key (cannot be NULL) * In: seckey: pointer to a 32-byte secret key.
*/ */
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_create( SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_create(
const secp256k1_context* ctx, const secp256k1_context* ctx,
@ -183,9 +173,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_create(
/** Get the secret key from a keypair. /** Get the secret key from a keypair.
* *
* 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.
* Out: seckey: pointer to a 32-byte buffer for the secret key (cannot be NULL) * Out: seckey: pointer to a 32-byte buffer for the secret key.
* In: keypair: pointer to a keypair (cannot be NULL) * In: keypair: pointer to a keypair.
*/ */
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_sec( SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_sec(
const secp256k1_context* ctx, const secp256k1_context* ctx,
@ -196,11 +186,10 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_sec(
/** Get the public key from a keypair. /** Get the public key from a keypair.
* *
* 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.
* Out: pubkey: pointer to a pubkey object. If 1 is returned, it is set to * Out: pubkey: pointer to a pubkey object. If 1 is returned, it is set to
* the keypair public key. If not, it's set to an invalid value. * the keypair public key. If not, it's set to an invalid value.
* (cannot be NULL) * In: keypair: pointer to a keypair.
* In: keypair: pointer to a keypair (cannot be NULL)
*/ */
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_pub( SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_pub(
const secp256k1_context* ctx, const secp256k1_context* ctx,
@ -214,14 +203,13 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_pub(
* secp256k1_xonly_pubkey_from_pubkey. * secp256k1_xonly_pubkey_from_pubkey.
* *
* 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.
* Out: pubkey: pointer to an xonly_pubkey object. If 1 is returned, it is set * Out: pubkey: pointer to an xonly_pubkey object. If 1 is returned, it is set
* to the keypair public key after converting it to an * to the keypair public key after converting it to an
* xonly_pubkey. If not, it's set to an invalid value (cannot be * xonly_pubkey. If not, it's set to an invalid value.
* NULL). * pk_parity: Ignored if NULL. Otherwise, pointer to an integer that will be set to the
* pk_parity: pointer to an integer that will be set to the pk_parity * pk_parity argument of secp256k1_xonly_pubkey_from_pubkey.
* argument of secp256k1_xonly_pubkey_from_pubkey (can be NULL). * In: keypair: pointer to a keypair.
* In: keypair: pointer to a keypair (cannot be NULL)
*/ */
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_xonly_pub( SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_xonly_pub(
const secp256k1_context* ctx, const secp256k1_context* ctx,
@ -241,15 +229,13 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_xonly_pub(
* invalid (only when the tweak is the negation of the keypair's * invalid (only when the tweak is the negation of the keypair's
* secret key). 1 otherwise. * secret key). 1 otherwise.
* *
* Args: ctx: pointer to a context object initialized for verification * Args: ctx: pointer to a context object initialized for verification.
* (cannot be NULL)
* In/Out: keypair: pointer to a keypair to apply the tweak to. Will be set to * In/Out: keypair: pointer to a keypair to apply the tweak to. Will be set to
* an invalid value if this function returns 0 (cannot be * an invalid value if this function returns 0.
* NULL).
* In: tweak32: pointer to a 32-byte tweak. If the tweak is invalid according * In: tweak32: pointer to a 32-byte tweak. If the tweak is invalid according
* to secp256k1_ec_seckey_verify, this function returns 0. For * to 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).
*/ */
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_xonly_tweak_add( SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_xonly_tweak_add(
const secp256k1_context* ctx, const secp256k1_context* ctx,

12
include/secp256k1_preallocated.h
View File

@ -55,7 +55,7 @@ SECP256K1_API size_t secp256k1_context_preallocated_size(
* Returns: a newly created context object. * Returns: a newly created context object.
* In: prealloc: a pointer to a rewritable contiguous block of memory of * In: prealloc: a pointer to a rewritable contiguous block of memory of
* size at least secp256k1_context_preallocated_size(flags) * size at least secp256k1_context_preallocated_size(flags)
* bytes, as detailed above (cannot be NULL) * bytes, as detailed above.
* flags: which parts of the context to initialize. * flags: which parts of the context to initialize.
* *
* See also secp256k1_context_randomize (in secp256k1.h) * See also secp256k1_context_randomize (in secp256k1.h)
@ -70,7 +70,7 @@ SECP256K1_API secp256k1_context* secp256k1_context_preallocated_create(
* caller-provided memory. * caller-provided memory.
* *
* Returns: the required size of the caller-provided memory block. * Returns: the required size of the caller-provided memory block.
* In: ctx: an existing context to copy (cannot be NULL) * In: ctx: an existing context to copy.
*/ */
SECP256K1_API size_t secp256k1_context_preallocated_clone_size( SECP256K1_API size_t secp256k1_context_preallocated_clone_size(
const secp256k1_context* ctx const secp256k1_context* ctx
@ -87,10 +87,10 @@ SECP256K1_API size_t secp256k1_context_preallocated_clone_size(
* secp256k1_context_preallocated_create for details. * secp256k1_context_preallocated_create for details.
* *
* Returns: a newly created context object. * Returns: a newly created context object.
* Args: ctx: an existing context to copy (cannot be NULL) * Args: ctx: an existing context to copy.
* In: prealloc: a pointer to a rewritable contiguous block of memory of * In: prealloc: a pointer to a rewritable contiguous block of memory of
* size at least secp256k1_context_preallocated_size(flags) * size at least secp256k1_context_preallocated_size(flags)
* bytes, as detailed above (cannot be NULL) * bytes, as detailed above.
*/ */
SECP256K1_API secp256k1_context* secp256k1_context_preallocated_clone( SECP256K1_API secp256k1_context* secp256k1_context_preallocated_clone(
const secp256k1_context* ctx, const secp256k1_context* ctx,
@ -115,11 +115,11 @@ SECP256K1_API secp256k1_context* secp256k1_context_preallocated_clone(
* *
* Args: ctx: an existing context to destroy, constructed using * Args: ctx: an existing context to destroy, constructed using
* secp256k1_context_preallocated_create or * secp256k1_context_preallocated_create or
* secp256k1_context_preallocated_clone (cannot be NULL) * secp256k1_context_preallocated_clone.
*/ */
SECP256K1_API void secp256k1_context_preallocated_destroy( SECP256K1_API void secp256k1_context_preallocated_destroy(
secp256k1_context* ctx secp256k1_context* ctx
); ) SECP256K1_ARG_NONNULL(1);
#ifdef __cplusplus #ifdef __cplusplus
} }

35
include/secp256k1_recovery.h
View File

@ -43,8 +43,9 @@ SECP256K1_API int secp256k1_ecdsa_recoverable_signature_parse_compact(
/** Convert a recoverable signature into a normal signature. /** Convert a recoverable signature into a normal signature.
* *
* Returns: 1 * Returns: 1
* Out: sig: a pointer to a normal signature (cannot be NULL). * Args: ctx: a secp256k1 context object.
* In: sigin: a pointer to a recoverable signature (cannot be NULL). * Out: sig: a pointer to a normal signature.
* In: sigin: a pointer to a recoverable signature.
*/ */
SECP256K1_API int secp256k1_ecdsa_recoverable_signature_convert( SECP256K1_API int secp256k1_ecdsa_recoverable_signature_convert(
const secp256k1_context* ctx, const secp256k1_context* ctx,
@ -55,10 +56,10 @@ SECP256K1_API int secp256k1_ecdsa_recoverable_signature_convert(
/** Serialize an ECDSA signature in compact format (64 bytes + recovery id). /** Serialize an ECDSA signature in compact format (64 bytes + recovery id).
* *
* Returns: 1 * Returns: 1
* Args: ctx: a secp256k1 context object * Args: ctx: a secp256k1 context object.
* Out: output64: a pointer to a 64-byte array of the compact signature (cannot be NULL) * Out: output64: a pointer to a 64-byte array of the compact signature.
* recid: a pointer to an integer to hold the recovery id (can be NULL). * recid: a pointer to an integer to hold the recovery id.
* In: sig: a pointer to an initialized signature object (cannot be NULL) * In: sig: a pointer to an initialized signature object.
*/ */
SECP256K1_API int secp256k1_ecdsa_recoverable_signature_serialize_compact( SECP256K1_API int secp256k1_ecdsa_recoverable_signature_serialize_compact(
const secp256k1_context* ctx, const secp256k1_context* ctx,
@ -71,12 +72,14 @@ SECP256K1_API int secp256k1_ecdsa_recoverable_signature_serialize_compact(
* *
* 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.
* 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.
* In: msghash32: the 32-byte message hash being signed (cannot be NULL) * In: msghash32: the 32-byte message hash being signed.
* seckey: pointer to a 32-byte secret key (cannot be NULL) * seckey: pointer to a 32-byte secret key.
* noncefp: pointer to a nonce generation function. If NULL, secp256k1_nonce_function_default is used * noncefp: pointer to a nonce generation function. If NULL,
* ndata: pointer to arbitrary data used by the nonce generation function (can be NULL) * secp256k1_nonce_function_default is used.
* ndata: pointer to arbitrary data used by the nonce generation function
* (can be NULL for secp256k1_nonce_function_default).
*/ */
SECP256K1_API int secp256k1_ecdsa_sign_recoverable( SECP256K1_API int secp256k1_ecdsa_sign_recoverable(
const secp256k1_context* ctx, const secp256k1_context* ctx,
@ -91,10 +94,10 @@ SECP256K1_API int secp256k1_ecdsa_sign_recoverable(
* *
* Returns: 1: public key successfully recovered (which guarantees a correct signature). * Returns: 1: public key successfully recovered (which guarantees a correct signature).
* 0: otherwise. * 0: otherwise.
* Args: ctx: pointer to a context object, initialized for verification (cannot be NULL) * Args: ctx: pointer to a context object, initialized for verification.
* Out: pubkey: pointer to the recovered public key (cannot be NULL) * Out: pubkey: pointer to the recovered public key.
* In: sig: pointer to initialized signature that supports pubkey recovery (cannot be NULL) * In: sig: pointer to initialized signature that supports pubkey recovery.
* msghash32: the 32-byte message hash assumed to be signed (cannot be NULL) * msghash32: the 32-byte message hash assumed to be signed.
*/ */
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_recover( SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_recover(
const secp256k1_context* ctx, const secp256k1_context* ctx,

10
include/secp256k1_schnorrsig.h
View File

@ -106,10 +106,10 @@ typedef struct {
* signatures from being valid in multiple contexts by accident. * signatures from being valid in multiple contexts by accident.
* *
* Returns 1 on success, 0 on failure. * Returns 1 on success, 0 on failure.
* Args: ctx: pointer to a context object, initialized for signing (cannot be NULL) * Args: ctx: pointer to a context object, initialized for signing.
* Out: sig64: pointer to a 64-byte array to store the serialized signature (cannot be NULL) * Out: sig64: pointer to a 64-byte array to store the serialized signature.
* In: msg32: the 32-byte message being signed (cannot be NULL) * In: msg32: the 32-byte message being signed.
* keypair: pointer to an initialized keypair (cannot be NULL) * keypair: pointer to an initialized keypair.
* aux_rand32: 32 bytes of fresh randomness. While recommended to provide * aux_rand32: 32 bytes of fresh randomness. While recommended to provide
* this, it is only supplemental to security and can be NULL. See * this, it is only supplemental to security and can be NULL. See
* BIP-340 "Default Signing" for a full explanation of this * BIP-340 "Default Signing" for a full explanation of this
@ -150,7 +150,7 @@ SECP256K1_API int secp256k1_schnorrsig_sign_custom(
* Returns: 1: correct signature * Returns: 1: correct signature
* 0: incorrect signature * 0: incorrect signature
* Args: ctx: a secp256k1 context object, initialized for verification. * Args: ctx: a secp256k1 context object, initialized for verification.
* In: sig64: pointer to the 64-byte signature to verify (cannot be NULL) * In: sig64: pointer to the 64-byte signature to verify.
* msg: the message being verified. Can only be NULL if msglen is 0. * msg: the message being verified. Can only be NULL if msglen is 0.
* msglen: length of the message * msglen: length of the message
* pubkey: pointer to an x-only public key to verify with (cannot be NULL) * pubkey: pointer to an x-only public key to verify with (cannot be NULL)

6
src/modules/recovery/main_impl.h
View File

@ -40,7 +40,7 @@ int secp256k1_ecdsa_recoverable_signature_parse_compact(const secp256k1_context*
int ret = 1; int ret = 1;
int overflow = 0; int overflow = 0;
(void)ctx; VERIFY_CHECK(ctx != NULL);
ARG_CHECK(sig != NULL); ARG_CHECK(sig != NULL);
ARG_CHECK(input64 != NULL); ARG_CHECK(input64 != NULL);
ARG_CHECK(recid >= 0 && recid <= 3); ARG_CHECK(recid >= 0 && recid <= 3);
@ -60,7 +60,7 @@ int secp256k1_ecdsa_recoverable_signature_parse_compact(const secp256k1_context*
int secp256k1_ecdsa_recoverable_signature_serialize_compact(const secp256k1_context* ctx, unsigned char *output64, int *recid, const secp256k1_ecdsa_recoverable_signature* sig) { int secp256k1_ecdsa_recoverable_signature_serialize_compact(const secp256k1_context* ctx, unsigned char *output64, int *recid, const secp256k1_ecdsa_recoverable_signature* sig) {
secp256k1_scalar r, s; secp256k1_scalar r, s;
(void)ctx; VERIFY_CHECK(ctx != NULL);
ARG_CHECK(output64 != NULL); ARG_CHECK(output64 != NULL);
ARG_CHECK(sig != NULL); ARG_CHECK(sig != NULL);
ARG_CHECK(recid != NULL); ARG_CHECK(recid != NULL);
@ -75,7 +75,7 @@ int secp256k1_ecdsa_recoverable_signature_convert(const secp256k1_context* ctx,
secp256k1_scalar r, s; secp256k1_scalar r, s;
int recid; int recid;
(void)ctx; VERIFY_CHECK(ctx != NULL);
ARG_CHECK(sig != NULL); ARG_CHECK(sig != NULL);
ARG_CHECK(sigin != NULL); ARG_CHECK(sigin != NULL);

2
src/secp256k1.c
View File

@ -754,6 +754,7 @@ int secp256k1_ec_pubkey_combine(const secp256k1_context* ctx, secp256k1_pubkey *
secp256k1_gej Qj; secp256k1_gej Qj;
secp256k1_ge Q; secp256k1_ge Q;
VERIFY_CHECK(ctx != NULL);
ARG_CHECK(pubnonce != NULL); ARG_CHECK(pubnonce != NULL);
memset(pubnonce, 0, sizeof(*pubnonce)); memset(pubnonce, 0, sizeof(*pubnonce));
ARG_CHECK(n >= 1); ARG_CHECK(n >= 1);
@ -762,6 +763,7 @@ int secp256k1_ec_pubkey_combine(const secp256k1_context* ctx, secp256k1_pubkey *
secp256k1_gej_set_infinity(&Qj); secp256k1_gej_set_infinity(&Qj);
for (i = 0; i < n; i++) { for (i = 0; i < n; i++) {
ARG_CHECK(pubnonces[i] != NULL);
secp256k1_pubkey_load(ctx, &Q, pubnonces[i]); secp256k1_pubkey_load(ctx, &Q, pubnonces[i]);
secp256k1_gej_add_ge(&Qj, &Qj, &Q); secp256k1_gej_add_ge(&Qj, &Qj, &Q);
} }