diff --git a/include/secp256k1.h b/include/secp256k1.h index 7be7fd5723..19062b33e2 100644 --- a/include/secp256k1.h +++ b/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 @@ -243,7 +243,7 @@ SECP256K1_API secp256k1_context* secp256k1_context_clone( * be used instead. * * Args: ctx: an existing context to destroy, constructed using - * secp256k1_context_create or secp256k1_context_clone + * secp256k1_context_create or secp256k1_context_clone. */ SECP256K1_API void secp256k1_context_destroy( secp256k1_context* ctx @@ -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. */ @@ -333,7 +333,7 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT secp256k1_scratch_space* secp256k1_sc * * The pointer may not be used afterwards. * Args: ctx: a secp256k1 context object. - * scratch: space to destroy + * scratch: space to destroy. */ SECP256K1_API void secp256k1_scratch_space_destroy( const secp256k1_context* ctx, @@ -347,8 +347,8 @@ SECP256K1_API void secp256k1_scratch_space_destroy( * Args: ctx: a secp256k1 context object. * Out: pubkey: pointer to a pubkey object. If 1 is returned, it is set to a * parsed version of input. If not, its value is undefined. - * In: input: pointer to a serialized public key - * inputlen: length of the array pointed to by input + * In: input: pointer to a serialized public key. + * inputlen: length of the array pointed to by input. * * This function supports parsing compressed (33 bytes, header byte 0x02 or * 0x03), uncompressed (65 bytes, header byte 0x04), or hybrid (65 bytes, header @@ -402,9 +402,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_cmp( /** Parse an ECDSA signature in compact (64 bytes) format. * * Returns: 1 when the signature could be parsed, 0 otherwise. - * Args: ctx: a secp256k1 context object - * Out: sig: a pointer to a signature object - * In: input64: a pointer to the 64-byte array to parse + * Args: ctx: a secp256k1 context object. + * Out: sig: a pointer to a signature object. + * In: input64: a pointer to the 64-byte array to parse. * * The signature must consist of a 32-byte big endian R value, followed by a * 32-byte big endian S value. If R or S fall outside of [0..order-1], the @@ -423,10 +423,10 @@ SECP256K1_API int secp256k1_ecdsa_signature_parse_compact( /** Parse a DER ECDSA signature. * * Returns: 1 when the signature could be parsed, 0 otherwise. - * Args: ctx: a secp256k1 context object - * Out: sig: a pointer to a signature object - * In: input: a pointer to the signature to be parsed - * inputlen: the length of the array pointed to be input + * Args: ctx: a secp256k1 context object. + * Out: sig: a pointer to a signature object. + * In: input: a pointer to the signature to be parsed. + * inputlen: the length of the array pointed to be input. * * This function will accept any valid DER encoded signature, even if the * encoded numbers are out of range. @@ -444,14 +444,14 @@ SECP256K1_API int secp256k1_ecdsa_signature_parse_der( /** Serialize an ECDSA signature in DER format. * - * Returns: 1 if enough space was available to serialize, 0 otherwise - * Args: ctx: a secp256k1 context object - * Out: output: a pointer to an array to store the DER serialization + * Returns: 1 if enough space was available to serialize, 0 otherwise. + * Args: ctx: a secp256k1 context object. + * Out: output: a pointer to an array to store the DER serialization. * In/Out: outputlen: a pointer to a length integer. Initially, this integer * should be set to the length of output. After the call * it will be set to the length of the serialization (even * if 0 was returned). - * In: sig: a pointer to an initialized signature object + * In: sig: a pointer to an initialized signature object. */ SECP256K1_API int secp256k1_ecdsa_signature_serialize_der( const secp256k1_context* ctx, @@ -463,9 +463,9 @@ SECP256K1_API int secp256k1_ecdsa_signature_serialize_der( /** Serialize an ECDSA signature in compact (64 byte) format. * * Returns: 1 - * Args: ctx: a secp256k1 context object - * Out: output64: a pointer to a 64-byte array to store the compact serialization - * In: sig: a pointer to an initialized signature object + * Args: ctx: a secp256k1 context object. + * Out: output64: a pointer to a 64-byte array to store the compact serialization. + * In: sig: a pointer to an initialized signature object. * * See secp256k1_ecdsa_signature_parse_compact for details about the encoding. */ @@ -477,11 +477,11 @@ SECP256K1_API int secp256k1_ecdsa_signature_serialize_compact( /** Verify an ECDSA signature. * - * Returns: 1: correct signature - * 0: incorrect or unparseable signature + * 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. @@ -510,13 +510,12 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_verify( /** Convert a signature to a normalized lower-S form. * * 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, * 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,12 @@ 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 for secp256k1_nonce_function_default). * * The created signature is always in lower-S form. See * secp256k1_ecdsa_signature_normalize for more details. @@ -594,10 +593,10 @@ SECP256K1_API int secp256k1_ecdsa_sign( * probability of choosing a 32-byte string uniformly at random which is an * invalid secret key is negligible. * - * 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) + * Returns: 1: secret key is valid. + * 0: secret key is invalid. + * 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 +605,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, @@ -621,13 +620,12 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_create( /** Negates a secret key in place. * * Returns: 0 if the given secret key is invalid according to - * secp256k1_ec_seckey_verify. 1 otherwise - * Args: ctx: pointer to a context object + * secp256k1_ec_seckey_verify. 1 otherwise. + * Args: ctx: pointer to a context object. * 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, @@ -644,8 +642,8 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_negate( /** Negates a public key in place. * * Returns: 1 always - * Args: ctx: pointer to a context object - * In/Out: pubkey: pointer to the public key to be negated (cannot be NULL) + * Args: ctx: pointer to a context object. + * 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 +655,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, @@ -687,13 +685,12 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_add( * 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). * 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 +701,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, @@ -732,13 +729,12 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_mul( * * Returns: 0 if the arguments are invalid. 1 otherwise. * 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 - * 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,8 +745,8 @@ 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) - * In: seed32: pointer to a 32-byte random seed (NULL resets to initial state) + * 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 * values are, it's possible that a future compiler may output code which isn't, @@ -780,18 +776,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. * diff --git a/include/secp256k1_ecdh.h b/include/secp256k1_ecdh.h index 4058e9c043..a28a63f1ad 100644 --- a/include/secp256k1_ecdh.h +++ b/include/secp256k1_ecdh.h @@ -13,10 +13,10 @@ extern "C" { * 0 will cause secp256k1_ecdh to fail and return 0. * Other return values are not allowed, and the behaviour of * secp256k1_ecdh is undefined for other return values. - * Out: output: pointer to an array to be filled by the function - * In: x32: pointer to a 32-byte x coordinate - * y32: pointer to a 32-byte y coordinate - * data: arbitrary data pointer that is passed through + * Out: output: pointer to an array to be filled by the function. + * In: x32: pointer to a 32-byte x coordinate. + * y32: pointer to a 32-byte y coordinate. + * data: arbitrary data pointer that is passed through. */ typedef int (*secp256k1_ecdh_hash_function)( unsigned char *output, @@ -37,14 +37,14 @@ SECP256K1_API extern const secp256k1_ecdh_hash_function secp256k1_ecdh_hash_func * * Returns: 1: exponentiation was successful * 0: scalar was invalid (zero or overflow) or hashfp returned 0 - * Args: ctx: pointer to a context object (cannot be NULL) - * Out: output: pointer to an array to be filled by hashfp + * Args: ctx: pointer to a context object. + * Out: output: pointer to an array to be filled by hashfp. * In: pubkey: a pointer to a secp256k1_pubkey containing an - * initialized public key - * seckey: a 32-byte scalar with which to multiply the point + * initialized public key. + * seckey: a 32-byte scalar with which to multiply the point. * hashfp: pointer to a hash function. If NULL, secp256k1_ecdh_hash_function_sha256 is used - * (in which case, 32 bytes will be written to output) - * data: arbitrary data pointer that is passed through to hashfp + * (in which case, 32 bytes will be written to output). + * 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( const secp256k1_context* ctx, diff --git a/include/secp256k1_extrakeys.h b/include/secp256k1_extrakeys.h index 0a37fb6b9d..1af5388500 100644 --- a/include/secp256k1_extrakeys.h +++ b/include/secp256k1_extrakeys.h @@ -39,11 +39,10 @@ typedef struct { * Returns: 1 if the public key was fully valid. * 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 * parsed version of input. If not, it's set to an invalid value. - * (cannot be NULL). - * In: input32: pointer to a serialized xonly_pubkey (cannot be NULL) + * In: input32: pointer to a serialized xonly_pubkey. */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_parse( const secp256k1_context* ctx, @@ -55,11 +54,10 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_parse( * * 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 - * (cannot be NULL). * In: pubkey: a pointer to a secp256k1_xonly_pubkey containing an - * initialized public key (cannot be NULL). + * initialized public key. */ SECP256K1_API int secp256k1_xonly_pubkey_serialize( const secp256k1_context* ctx, @@ -87,13 +85,13 @@ SECP256K1_API int secp256k1_xonly_pubkey_cmp( * Returns: 1 if the public key was successfully converted * 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 - * converted public key (cannot be NULL) - * pk_parity: pointer to an integer that will be set to 1 if the point - * encoded by xonly_pubkey is the negation of the pubkey and - * set to 0 otherwise. (can be NULL) - * In: pubkey: pointer to a public key that is converted (cannot be NULL) + * converted public key. + * pk_parity: Ignored if NULL. Otherwise, pointer to an integer that + * will be set to 1 if the point encoded by xonly_pubkey is + * the negation of the pubkey and set to 0 otherwise. + * In: pubkey: pointer to a public key that is converted. */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_from_pubkey( const secp256k1_context* ctx, @@ -113,18 +111,15 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_from_pubke * invalid (only when the tweak is the negation of the corresponding * secret key). 1 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: output_pubkey: pointer to a public key to store the result. Will be set - * to an invalid value if this function returns 0 (cannot - * be NULL) + * to an invalid value if this function returns 0. * 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 * 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). + * 2^128). */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_tweak_add( const secp256k1_context* ctx, @@ -146,17 +141,16 @@ 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 * result of tweaking the internal_pubkey with tweak32. 1 otherwise. - * Args: ctx: pointer to a context object initialized for verification - * (cannot be NULL) - * In: tweaked_pubkey32: pointer to a serialized xonly_pubkey (cannot be NULL) + * Args: ctx: pointer to a context object initialized for verification. + * In: tweaked_pubkey32: pointer to a serialized xonly_pubkey. * tweaked_pk_parity: the parity of the tweaked pubkey (whose serialization * is passed in as tweaked_pubkey32). This must match the * pk_parity value that is returned when calling * secp256k1_xonly_pubkey with the tweaked pubkey, or * this function will fail. * internal_pubkey: pointer to an x-only public key object to apply the - * tweak to (cannot be NULL) - * tweak32: pointer to a 32-byte tweak (cannot be NULL) + * tweak to. + * tweak32: pointer to a 32-byte tweak. */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_tweak_add_check( const secp256k1_context* ctx, @@ -170,9 +164,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_tweak_add_ * * Returns: 1: secret was valid, keypair is ready to use * 0: secret was invalid, try again with a different secret - * Args: ctx: pointer to a context object, initialized for signing (cannot be NULL) - * Out: keypair: pointer to the created keypair (cannot be NULL) - * In: seckey: pointer to a 32-byte secret key (cannot be NULL) + * Args: ctx: pointer to a context object, initialized for signing. + * Out: keypair: pointer to the created keypair. + * In: seckey: pointer to a 32-byte secret key. */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_create( const secp256k1_context* ctx, @@ -183,9 +177,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_create( /** Get the secret key from a keypair. * * Returns: 0 if the arguments are invalid. 1 otherwise. - * Args: ctx: pointer to a context object (cannot be NULL) - * Out: seckey: pointer to a 32-byte buffer for the secret key (cannot be NULL) - * In: keypair: pointer to a keypair (cannot be NULL) + * Args: ctx: pointer to a context object. + * Out: seckey: pointer to a 32-byte buffer for the secret key. + * In: keypair: pointer to a keypair. */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_sec( const secp256k1_context* ctx, @@ -196,11 +190,10 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_sec( /** Get the public key from a keypair. * * 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 * the keypair public key. If not, it's set to an invalid value. - * (cannot be NULL) - * In: keypair: pointer to a keypair (cannot be NULL) + * In: keypair: pointer to a keypair. */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_pub( const secp256k1_context* ctx, @@ -214,14 +207,13 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_pub( * secp256k1_xonly_pubkey_from_pubkey. * * 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 * to the keypair public key after converting it to an - * xonly_pubkey. If not, it's set to an invalid value (cannot be - * NULL). - * pk_parity: pointer to an integer that will be set to the pk_parity - * argument of secp256k1_xonly_pubkey_from_pubkey (can be NULL). - * In: keypair: pointer to a keypair (cannot be NULL) + * xonly_pubkey. If not, it's set to an invalid value. + * pk_parity: Ignored if NULL. Otherwise, pointer to an integer that will be set to the + * pk_parity argument of secp256k1_xonly_pubkey_from_pubkey. + * In: keypair: pointer to a keypair. */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_xonly_pub( const secp256k1_context* ctx, @@ -241,15 +233,13 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_xonly_pub( * invalid (only when the tweak is the negation of the keypair's * secret key). 1 otherwise. * - * Args: ctx: pointer to a context object initialized for verification - * (cannot be NULL) + * Args: ctx: pointer to a context object initialized for verification. * 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 - * NULL). + * an 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_keypair_xonly_tweak_add( const secp256k1_context* ctx, diff --git a/include/secp256k1_preallocated.h b/include/secp256k1_preallocated.h index a9ae15d5ae..1ab8b7d6c7 100644 --- a/include/secp256k1_preallocated.h +++ b/include/secp256k1_preallocated.h @@ -55,7 +55,7 @@ SECP256K1_API size_t secp256k1_context_preallocated_size( * Returns: a newly created context object. * In: prealloc: a pointer to a rewritable contiguous block of memory of * 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. * * See also secp256k1_context_randomize (in secp256k1.h) @@ -70,7 +70,7 @@ SECP256K1_API secp256k1_context* secp256k1_context_preallocated_create( * caller-provided memory. * * 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( const secp256k1_context* ctx @@ -87,10 +87,10 @@ SECP256K1_API size_t secp256k1_context_preallocated_clone_size( * secp256k1_context_preallocated_create for details. * * 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 * 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( const secp256k1_context* ctx, @@ -115,7 +115,7 @@ SECP256K1_API secp256k1_context* secp256k1_context_preallocated_clone( * * Args: ctx: an existing context to destroy, constructed using * secp256k1_context_preallocated_create or - * secp256k1_context_preallocated_clone (cannot be NULL) + * secp256k1_context_preallocated_clone. */ SECP256K1_API void secp256k1_context_preallocated_destroy( secp256k1_context* ctx diff --git a/include/secp256k1_recovery.h b/include/secp256k1_recovery.h index aa16532ce8..1414d5a914 100644 --- a/include/secp256k1_recovery.h +++ b/include/secp256k1_recovery.h @@ -28,10 +28,10 @@ typedef struct { /** Parse a compact ECDSA signature (64 bytes + recovery id). * * Returns: 1 when the signature could be parsed, 0 otherwise - * Args: ctx: a secp256k1 context object - * Out: sig: a pointer to a signature object - * In: input64: a pointer to a 64-byte compact signature - * recid: the recovery id (0, 1, 2 or 3) + * Args: ctx: a secp256k1 context object. + * Out: sig: a pointer to a signature object. + * In: input64: a pointer to a 64-byte compact signature. + * recid: the recovery id (0, 1, 2 or 3). */ SECP256K1_API int secp256k1_ecdsa_recoverable_signature_parse_compact( const secp256k1_context* ctx, @@ -43,8 +43,9 @@ SECP256K1_API int secp256k1_ecdsa_recoverable_signature_parse_compact( /** Convert a recoverable signature into a normal signature. * * Returns: 1 - * Out: sig: a pointer to a normal signature (cannot be NULL). - * In: sigin: a pointer to a recoverable signature (cannot be NULL). + * Args: ctx: a secp256k1 context object. + * Out: sig: a pointer to a normal signature. + * In: sigin: a pointer to a recoverable signature. */ SECP256K1_API int secp256k1_ecdsa_recoverable_signature_convert( 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). * * Returns: 1 - * Args: ctx: a secp256k1 context object - * Out: output64: a pointer to a 64-byte array of the compact signature (cannot be NULL) - * recid: a pointer to an integer to hold the recovery id (can be NULL). - * In: sig: a pointer to an initialized signature object (cannot be NULL) + * Args: ctx: a secp256k1 context object. + * Out: output64: a pointer to a 64-byte array of the compact signature. + * recid: a pointer to an integer to hold the recovery id. + * In: sig: a pointer to an initialized signature object. */ SECP256K1_API int secp256k1_ecdsa_recoverable_signature_serialize_compact( const secp256k1_context* ctx, @@ -71,12 +72,12 @@ SECP256K1_API int secp256k1_ecdsa_recoverable_signature_serialize_compact( * * 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 for secp256k1_nonce_function_default). */ SECP256K1_API int secp256k1_ecdsa_sign_recoverable( const secp256k1_context* ctx, @@ -91,10 +92,10 @@ SECP256K1_API int secp256k1_ecdsa_sign_recoverable( * * Returns: 1: public key successfully recovered (which guarantees a correct signature). * 0: otherwise. - * Args: ctx: pointer to a context object, initialized for verification (cannot be NULL) - * Out: pubkey: pointer to the recovered public key (cannot be NULL) - * In: sig: pointer to initialized signature that supports pubkey recovery (cannot be NULL) - * msghash32: the 32-byte message hash assumed to be signed (cannot be NULL) + * Args: ctx: pointer to a context object, initialized for verification. + * Out: pubkey: pointer to the recovered public key. + * In: sig: pointer to initialized signature that supports pubkey recovery. + * msghash32: the 32-byte message hash assumed to be signed. */ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_recover( const secp256k1_context* ctx, diff --git a/include/secp256k1_schnorrsig.h b/include/secp256k1_schnorrsig.h index d68bba62cc..c42cb10f2b 100644 --- a/include/secp256k1_schnorrsig.h +++ b/include/secp256k1_schnorrsig.h @@ -106,10 +106,10 @@ typedef struct { * signatures from being valid in multiple contexts by accident. * * Returns 1 on success, 0 on failure. - * Args: ctx: pointer to a context object, initialized for signing (cannot be NULL) - * Out: sig64: pointer to a 64-byte array to store the serialized signature (cannot be NULL) - * In: msg32: the 32-byte message being signed (cannot be NULL) - * keypair: pointer to an initialized keypair (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. + * In: msg32: the 32-byte message being signed. + * keypair: pointer to an initialized keypair. * aux_rand32: 32 bytes of fresh randomness. While recommended to provide * this, it is only supplemental to security and can be NULL. See * 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 * 0: incorrect signature * 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. * msglen: length of the message * pubkey: pointer to an x-only public key to verify with (cannot be NULL)