Clarify documentation of tweak functions.
In particular, mention that the functions return 0 if seckey or tweak are invalid (as opposed to saying "should" or "must" be valid).
This commit is contained in:
parent
89853a0f2e
commit
7e3952ae82
@ -587,10 +587,11 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_create(
|
|||||||
* Returns: 0 if the given secret key is invalid according to
|
* Returns: 0 if the given secret key is invalid according to
|
||||||
* secp256k1_ec_seckey_verify. 1 otherwise
|
* secp256k1_ec_seckey_verify. 1 otherwise
|
||||||
* Args: ctx: pointer to a context object
|
* Args: ctx: pointer to a context object
|
||||||
* In/Out: seckey: pointer to the 32-byte secret key to be negated. The secret
|
* In/Out: seckey: pointer to the 32-byte secret key to be negated. If the
|
||||||
* key should be valid according to secp256k1_ec_seckey_verify.
|
* secret key is invalid according to
|
||||||
* If this function returns 0, seckey will be some
|
* secp256k1_ec_seckey_verify, this function returns 0 and
|
||||||
* unspecified value. (cannot be NULL)
|
* seckey will be set to some unspecified value. (cannot be
|
||||||
|
* 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,
|
||||||
@ -617,17 +618,18 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_negate(
|
|||||||
|
|
||||||
/** Tweak a secret key by adding tweak to it.
|
/** Tweak a secret key by adding tweak to it.
|
||||||
*
|
*
|
||||||
* Returns: 0 if the resulting secret key would be invalid (only when the tweak
|
* Returns: 0 if the arguments are invalid or the resulting secret key would be
|
||||||
* is the negation of the secret key). 1 otherwise.
|
* 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 (cannot be NULL).
|
||||||
* In/Out: seckey: pointer to a 32-byte secret key. The secret key should be
|
* In/Out: seckey: pointer to a 32-byte secret key. If the secret key is
|
||||||
* valid according to secp256k1_ec_seckey_verify. If this
|
* invalid according to secp256k1_ec_seckey_verify, this
|
||||||
* function returns 0, seckey will be some unspecified
|
* function returns 0. seckey will be set to some unspecified
|
||||||
* value. (cannot be NULL)
|
* value if this function returns 0. (cannot be NULL)
|
||||||
* In: tweak: pointer to a 32-byte tweak. Must be in the same range as secret
|
* In: tweak: pointer to a 32-byte tweak. If the tweak is invalid according to
|
||||||
* keys (see secp256k1_ec_seckey_verify). For uniformly random
|
* secp256k1_ec_seckey_verify, this function returns 0. For
|
||||||
* 32-byte arrays the chance of being out of range is
|
* uniformly random 32-byte arrays the chance of being invalid
|
||||||
* negligible (around 1 in 2^128). (cannot be NULL)
|
* is negligible (around 1 in 2^128) (cannot be NULL).
|
||||||
*/
|
*/
|
||||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_add(
|
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_add(
|
||||||
const secp256k1_context* ctx,
|
const secp256k1_context* ctx,
|
||||||
@ -645,16 +647,17 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_add(
|
|||||||
|
|
||||||
/** Tweak a public key by adding tweak times the generator to it.
|
/** Tweak a public key by adding tweak times the generator to it.
|
||||||
*
|
*
|
||||||
* Returns: 0 if the resulting public key would be invalid (only when the tweak
|
* Returns: 0 if the arguments are invalid or the resulting public key would be
|
||||||
* is the negation of the corresponding secret key). 1 otherwise.
|
* 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
|
* Args: ctx: pointer to a context object initialized for validation
|
||||||
* (cannot be NULL).
|
* (cannot be NULL).
|
||||||
* In/Out: pubkey: pointer to a public key object. If this function returns 0,
|
* In/Out: pubkey: pointer to a public key object. pubkey will be set to an
|
||||||
* pubkey will be invalid. (cannot be NULL).
|
* invalid value if this function returns 0 (cannot be NULL).
|
||||||
* In: tweak: pointer to a 32-byte tweak. Must be in the same range as secret
|
* In: tweak: pointer to a 32-byte tweak. If the tweak is invalid according to
|
||||||
* keys (see secp256k1_ec_seckey_verify). For uniformly random
|
* secp256k1_ec_seckey_verify, this function returns 0. For
|
||||||
* 32-byte arrays the chance of being out of range is
|
* uniformly random 32-byte arrays the chance of being invalid
|
||||||
* negligible (around 1 in 2^128). (cannot be NULL)
|
* is negligible (around 1 in 2^128) (cannot be NULL).
|
||||||
*/
|
*/
|
||||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_add(
|
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_add(
|
||||||
const secp256k1_context* ctx,
|
const secp256k1_context* ctx,
|
||||||
@ -664,14 +667,16 @@ 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 (cannot be NULL).
|
||||||
* In/Out: seckey: pointer to a 32-byte secret key. If this function returns 0,
|
* In/Out: seckey: pointer to a 32-byte secret key. If the secret key is
|
||||||
* seckey will be some unspecified value. (cannot be NULL).
|
* invalid according to secp256k1_ec_seckey_verify, this
|
||||||
* In: tweak: pointer to a 32-byte tweak. Must be in the same range as secret
|
* function returns 0. seckey will be set to some unspecified
|
||||||
* keys (see secp256k1_ec_seckey_verify). For uniformly random
|
* value if this function returns 0. (cannot be NULL)
|
||||||
* 32-byte arrays the chance of being out of range is
|
* In: tweak: pointer to a 32-byte tweak. If the tweak is invalid according to
|
||||||
* negligible (around 1 in 2^128). (cannot be NULL)
|
* 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).
|
||||||
*/
|
*/
|
||||||
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,
|
||||||
@ -692,12 +697,12 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_mul(
|
|||||||
* Returns: 0 if the arguments are invalid. 1 otherwise.
|
* Returns: 0 if the arguments are invalid. 1 otherwise.
|
||||||
* Args: ctx: pointer to a context object initialized for validation
|
* Args: ctx: pointer to a context object initialized for validation
|
||||||
* (cannot be NULL).
|
* (cannot be NULL).
|
||||||
* In/Out: pubkey: pointer to a public key object. If this function returns 0,
|
* In/Out: pubkey: pointer to a public key object. pubkey will be set to an
|
||||||
* pubkey will be invalid. (cannot be NULL).
|
* invalid value if this function returns 0 (cannot be NULL).
|
||||||
* In: tweak: pointer to a 32-byte tweak. Must be in the same range as secret
|
* In: tweak: pointer to a 32-byte tweak. If the tweak is invalid according to
|
||||||
* keys (see secp256k1_ec_seckey_verify). For uniformly random
|
* secp256k1_ec_seckey_verify, this function returns 0. For
|
||||||
* 32-byte arrays the chance of being out of range is
|
* uniformly random 32-byte arrays the chance of being invalid
|
||||||
* negligible (around 1 in 2^128). (cannot be NULL)
|
* is negligible (around 1 in 2^128) (cannot be NULL).
|
||||||
*/
|
*/
|
||||||
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_mul(
|
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_mul(
|
||||||
const secp256k1_context* ctx,
|
const secp256k1_context* ctx,
|
||||||
|
Loading…
x
Reference in New Issue
Block a user