diff options
Diffstat (limited to 'src/secp256k1/include/secp256k1.h')
| -rw-r--r-- | src/secp256k1/include/secp256k1.h | 99 |
1 files changed, 49 insertions, 50 deletions
diff --git a/src/secp256k1/include/secp256k1.h b/src/secp256k1/include/secp256k1.h index 7be7fd5723..57114b8f26 100644 --- a/src/secp256k1/include/secp256k1.h +++ b/src/secp256k1/include/secp256k1.h @@ -226,7 +226,7 @@ SECP256K1_API secp256k1_context* secp256k1_context_create( * memory allocation entirely, see the functions in secp256k1_preallocated.h. * * 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( const secp256k1_context* ctx @@ -247,7 +247,7 @@ SECP256K1_API secp256k1_context* secp256k1_context_clone( */ SECP256K1_API void secp256k1_context_destroy( secp256k1_context* ctx -); +) SECP256K1_ARG_NONNULL(1); /** 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 @@ -264,7 +264,7 @@ SECP256K1_API void secp256k1_context_destroy( * undefined. * * When this function has not been called (or called with fn==NULL), then the - * default handler will be used. The library provides a default handler which + * default handler will be used. The library provides a default handler which * writes the message to stderr and calls abort. This default handler can be * replaced at link time if the preprocessor macro * USE_EXTERNAL_DEFAULT_CALLBACKS is defined, which is the case if the build @@ -278,11 +278,11 @@ SECP256K1_API void secp256k1_context_destroy( * fails. In this case, the corresponding default handler will be called with * 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 * passed to the API, taking a message and an opaque pointer. * (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. */ @@ -302,12 +302,12 @@ SECP256K1_API void secp256k1_context_set_illegal_callback( * for that). After this callback returns, anything may happen, including * crashing. * - * Args: ctx: an existing context object (cannot be NULL) + * Args: ctx: an existing context object. * In: fun: a pointer to a function to call when an internal error occurs, * taking a message and an opaque pointer (NULL restores the * default handler, see secp256k1_context_set_illegal_callback * 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. */ @@ -320,7 +320,7 @@ SECP256K1_API void secp256k1_context_set_error_callback( /** Create a secp256k1 scratch space object. * * 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 * (<100 bytes) will be allocated for extra accounting. */ @@ -480,8 +480,8 @@ SECP256K1_API int secp256k1_ecdsa_signature_serialize_compact( * Returns: 1: correct signature * 0: incorrect or unparseable signature * Args: ctx: a secp256k1 context object, initialized for verification. - * In: sig: the signature being verified (cannot be NULL) - * msghash32: the 32-byte message hash being verified (cannot be NULL). + * In: sig: the signature being verified. + * msghash32: the 32-byte message hash being verified. * 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 @@ -489,7 +489,7 @@ SECP256K1_API int secp256k1_ecdsa_signature_serialize_compact( * 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. * * To avoid accepting malleable signatures, only ECDSA signatures in lower-S * 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 * you're only interested in whether the input was already * normalized). - * In: sigin: a pointer to a signature to check/normalize (cannot be NULL, - * can be identical to sigout) + * In: sigin: a pointer to a signature to check/normalize (can be identical to sigout) * * With ECDSA a third-party can forge a second distinct signature of the same * message, given a single initial signature, but without knowing the key. This @@ -568,12 +567,16 @@ SECP256K1_API extern const secp256k1_nonce_function secp256k1_nonce_function_def * * Returns: 1: signature created * 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) - * Out: sig: pointer to an array where the signature will be placed (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) - * 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) + * Args: ctx: pointer to a context object, initialized for signing. + * Out: sig: pointer to an array where the signature will be placed. + * In: msghash32: the 32-byte message hash being signed. + * seckey: pointer to a 32-byte secret key. + * 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). 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 * secp256k1_ecdsa_signature_normalize for more details. @@ -596,8 +599,8 @@ SECP256K1_API int secp256k1_ecdsa_sign( * * Returns: 1: secret key is valid * 0: secret key is invalid - * Args: ctx: pointer to a context object (cannot be NULL) - * In: seckey: pointer to a 32-byte secret key (cannot be NULL) + * Args: ctx: pointer to a context object. + * In: seckey: pointer to a 32-byte secret key. */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_verify( 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. * - * Returns: 1: secret was valid, public key stores - * 0: secret was invalid, try again - * Args: ctx: pointer to a context object, initialized for signing (cannot be NULL) - * Out: pubkey: pointer to the created public key (cannot be NULL) - * In: seckey: pointer to a 32-byte secret key (cannot be NULL) + * Returns: 1: secret was valid, public key stores. + * 0: secret was invalid, try again. + * Args: ctx: pointer to a context object, initialized for signing. + * Out: pubkey: pointer to the created public key. + * In: seckey: pointer to a 32-byte secret key. */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_create( 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 * 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) + * seckey will be set to some unspecified value. */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_negate( const secp256k1_context* ctx, @@ -645,7 +647,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_negate( * * Returns: 1 always * 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( 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 * invalid (only when the tweak is the negation of the secret key). 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 * 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) + * value if this function returns 0. * In: tweak32: 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). + * is negligible (around 1 in 2^128). */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_add( 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 * invalid (only when the tweak is the negation of the corresponding * secret key). 1 otherwise. - * Args: ctx: pointer to a context object initialized for validation - * (cannot be NULL). + * Args: ctx: pointer to a context object initialized for validation. * 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 * 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). + * is negligible (around 1 in 2^128). */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_add( 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. * * 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 * 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) + * value if this function returns 0. * In: tweak32: 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). + * is negligible (around 1 in 2^128). */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_mul( 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. * * Returns: 0 if the arguments are invalid. 1 otherwise. - * Args: ctx: pointer to a context object initialized for validation - * (cannot be NULL). + * Args: ctx: pointer to a context object initialized for validation. * 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 * 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). + * is negligible (around 1 in 2^128). */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_mul( 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. * Returns: 1: randomization successfully updated or nothing to randomize * 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) * * 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. * 0: the sum of the public keys is not valid. - * Args: ctx: pointer to a context object - * Out: out: pointer to a public key object for placing the resulting public key - * (cannot be NULL) - * In: ins: pointer to array of pointers to public keys (cannot be NULL) - * n: the number of public keys to add together (must be at least 1) + * Args: ctx: pointer to a context object. + * Out: out: pointer to a public key object for placing the resulting public key. + * In: ins: pointer to array of pointers to public keys. + * 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( const secp256k1_context* ctx, secp256k1_pubkey *out, const secp256k1_pubkey * const * ins, 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. * |