Skip to content

Commit

Permalink
f rephrase ec arithmetic doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@jonasnick
jonasnick committed Dec 19, 2019
1 parent cdbc1fa commit 302fd06
Showing 1 changed file with 35 additions and 29 deletions.
64 changes: 35 additions & 29 deletions include/secp256k1.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -585,8 +585,8 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_create(
* Args: ctx: pointer to a context object
* In/Out: seckey: pointer to the 32-byte secret key to be negated. The secret
* key should be valid according to secp256k1_ec_seckey_verify.
* Value becomes undefined if this function returns 0.
* (cannot be NULL)
* If this function returns 0, seckey will be some
* unspecified value. (cannot be NULL)
*/
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_negate(
const secp256k1_context* ctx,
Expand All @@ -605,15 +605,17 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_negate(
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);

/** Tweak a secret key by adding tweak to it.
* Returns: 0 if the tweak was out of range (chance of around 1 in 2^128 for
* uniformly random 32-byte arrays, or if the given secret key is
* invalid according to secp256k1_ec_seckey_verify, or if the resulting
* secret key would be invalid (only when the tweak is the complement
* of the secret key). 1 otherwise.
* Returns: 0 if 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).
* In/Out: seckey: pointer to a 32-byte secret key. Value becomes undefined if this
* function returns 0. (cannot be NULL)
* In: tweak: pointer to a 32-byte tweak.
* In/Out: seckey: pointer to a 32-byte secret key. The secret key should be
* valid according to secp256k1_ec_seckey_verify. If this
* function returns 0, seckey will be some unspecified
* value. (cannot be NULL)
* In: tweak: pointer to a 32-byte tweak. Must be in the same range as secret
* keys (see secp256k1_ec_seckey_verify). For uniformly random
* 32-byte arrays the chance of being out of range is
* negligible (around 1 in 2^128). (cannot be NULL)
*/
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_add(
const secp256k1_context* ctx,
Expand All @@ -622,16 +624,16 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_add(
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);

/** Tweak a public key by adding tweak times the generator to it.
* Returns: 0 if the tweak was out of range (chance of around 1 in 2^128 for
* uniformly random 32-byte arrays, or if the given secret key is
* invalid according to secp256k1_ec_seckey_verify, or if the resulting
* public key would be invalid (only when the tweak is the complement
* of the corresponding secret key). 1 otherwise.
* Returns: 0 if 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).
* In/Out: pubkey: pointer to a public key object. Value becomes undefined if this
* function returns 0. (cannot be NULL).
* In: tweak: pointer to a 32-byte tweak.
* In/Out: pubkey: pointer to a public key object. If this function returns 0,
* pubkey will be invalid. (cannot be NULL).
* In: tweak: pointer to a 32-byte tweak. Must be in the same range as secret
* keys (see secp256k1_ec_seckey_verify). For uniformly random
* 32-byte arrays the chance of being out of range is
* negligible (around 1 in 2^128). (cannot be NULL)
*/
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_add(
const secp256k1_context* ctx,
Expand All @@ -640,12 +642,14 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_add(
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);

/** Tweak a secret key by multiplying it by a tweak.
* Returns: 0 if the tweak was out of range (chance of around 1 in 2^128 for
* uniformly random 32-byte arrays, or equal to zero. 1 otherwise.
* Returns: 0 if the arguments are invalid.. 1 otherwise.
* Args: ctx: pointer to a context object (cannot be NULL).
* In/Out: seckey: pointer to a 32-byte secret key. Value becomes undefined if this
* function returns 0. (cannot be NULL).
* In: tweak: pointer to a 32-byte tweak.
* In/Out: seckey: pointer to a 32-byte secret key. If this function returns 0,
* seckey will be some unspecified value. (cannot be NULL).
* In: tweak: pointer to a 32-byte tweak. Must be in the same range as secret
* keys (see secp256k1_ec_seckey_verify). For uniformly random
* 32-byte arrays the chance of being out of range is
* negligible (around 1 in 2^128). (cannot be NULL)
*/
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_mul(
const secp256k1_context* ctx,
Expand All @@ -654,13 +658,15 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_mul(
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);

/** Tweak a public key by multiplying it by a tweak value.
* Returns: 0 if the tweak was out of range (chance of around 1 in 2^128 for
* uniformly random 32-byte arrays, or equal to zero. 1 otherwise.
* 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. Value becomes undefined if this
* function returns 0. (cannot be NULL).
* In: tweak: pointer to a 32-byte tweak.
* (cannot be NULL).
* In/Out: pubkey: pointer to a public key object. If this function returns 0,
* pubkey will be invalid. (cannot be NULL).
* In: tweak: pointer to a 32-byte tweak. Must be in the same range as secret
* keys (see secp256k1_ec_seckey_verify). For uniformly random
* 32-byte arrays the chance of being out of range is
* negligible (around 1 in 2^128). (cannot be NULL)
*/
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_mul(
const secp256k1_context* ctx,
Expand Down

0 comments on commit 302fd06

Please sign in to comment.