Merge pull request bitcoin#293

dc0ce9f [API BREAK] Change argument order to out/outin/in (Pieter Wuille)

include/secp256k1_ecdh.h

@@ -10,11 +10,11 @@ extern "C" {
 /** Compute an EC Diffie-Hellman secret in constant time
  *  Returns: 1: exponentiation was successful
  *           0: scalar was invalid (zero or overflow)
- *  In:      ctx:      pointer to a context object (cannot be NULL)
- *           point:    pointer to a public point
- *           scalar:   a 32-byte scalar with which to multiply the point
+ *  Args:    ctx:      pointer to a context object (cannot be NULL)
  *  Out:     result:   a 32-byte array which will be populated by an ECDH
  *                     secret computed from the point and scalar
+ *  In:      point:    pointer to a public point
+ *           scalar:   a 32-byte scalar with which to multiply the point
  */
 SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdh(
   const secp256k1_context_t* ctx,

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
- *  In:  ctx:     a secp256k1 context object
- *       input64: a pointer to a 64-byte compact signature
- *       recid:   the recovery id (0, 1, 2 or 3)
- *  Out: sig:     a pointer to a signature object
+ *  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)
  */
 int secp256k1_ecdsa_recoverable_signature_parse_compact(
     const secp256k1_context_t* ctx,
@@ -43,8 +43,8 @@ int secp256k1_ecdsa_recoverable_signature_parse_compact(
 /** Convert a recoverable signature into a normal signature.
  *
  *  Returns: 1
- *  In:  sigin:  a pointer to a recoverable signature (cannot be NULL).
  *  Out: sig:    a pointer to a normal signature (cannot be NULL).
+ *  In:  sigin:  a pointer to a recoverable signature (cannot be NULL).
  */
 int secp256k1_ecdsa_recoverable_signature_convert(
     const secp256k1_context_t* ctx,
@@ -55,10 +55,10 @@ int secp256k1_ecdsa_recoverable_signature_convert(
 /** Serialize an ECDSA signature in compact format (64 bytes + recovery id).
  *
  *  Returns: 1
- *  In: ctx:       a secp256k1 context object
- *      sig:       a pointer to an initialized signature object (cannot be NULL)
- *  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).
+ *  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)
  */
 int secp256k1_ecdsa_recoverable_signature_serialize_compact(
     const secp256k1_context_t* ctx,
@@ -71,17 +71,17 @@ int secp256k1_ecdsa_recoverable_signature_serialize_compact(
  *
  *  Returns: 1: signature created
  *           0: the nonce generation function failed, or the private key was invalid.
- *  In:      ctx:    pointer to a context object, initialized for signing (cannot be NULL)
- *           msg32:  the 32-byte message hash being signed (cannot be NULL)
+ *  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:      msg32:  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)
- *  Out:     sig:    pointer to an array where the signature will be placed (cannot be NULL)
  */
 int secp256k1_ecdsa_sign_recoverable(
     const secp256k1_context_t* ctx,
-    const unsigned char *msg32,
     secp256k1_ecdsa_recoverable_signature_t *sig,
+    const unsigned char *msg32,
     const unsigned char *seckey,
     secp256k1_nonce_function_t noncefp,
     const void *ndata
@@ -91,16 +91,16 @@ int secp256k1_ecdsa_sign_recoverable(
  *
  *  Returns: 1: public key successfully recovered (which guarantees a correct signature).
  *           0: otherwise.
- *  In:      ctx:        pointer to a context object, initialized for verification (cannot be NULL)
- *           msg32:      the 32-byte message hash assumed to be signed (cannot be NULL)
- *           sig:        pointer to initialized signature that supports pubkey recovery (cannot be NULL)
+ *  Args:    ctx:        pointer to a context object, initialized for verification (cannot be NULL)
  *  Out:     pubkey:     pointer to the recoved public key (cannot be NULL)
+ *  In:      sig:        pointer to initialized signature that supports pubkey recovery (cannot be NULL)
+ *           msg32:      the 32-byte message hash assumed to be signed (cannot be NULL)
  */
 SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_recover(
     const secp256k1_context_t* ctx,
-    const unsigned char *msg32,
+    secp256k1_pubkey_t *pubkey,
     const secp256k1_ecdsa_recoverable_signature_t *sig,
-    secp256k1_pubkey_t *pubkey
+    const unsigned char *msg32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 
 # ifdef __cplusplus

include/secp256k1_schnorr.h

@@ -13,21 +13,21 @@ extern "C" {
  *  Returns: 1: signature created
  *           0: the nonce generation function failed, or the private key was
  *              invalid.
- *  In:      ctx:    pointer to a context object, initialized for signing
+ *  Args:    ctx:    pointer to a context object, initialized for signing
  *                   (cannot be NULL)
- *           msg32:  the 32-byte message hash being signed (cannot be NULL)
+ *  Out:     sig64:  pointer to a 64-byte array where the signature will be
+ *                   placed (cannot be NULL)
+ *  In:      msg32:  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)
- *  Out:     sig64:  pointer to a 64-byte array where the signature will be
- *                   placed (cannot be NULL)
  */
 int secp256k1_schnorr_sign(
   const secp256k1_context_t* ctx,
-  const unsigned char *msg32,
   unsigned char *sig64,
+  const unsigned char *msg32,
   const unsigned char *seckey,
   secp256k1_nonce_function_t noncefp,
   const void *ndata
@@ -36,15 +36,15 @@ int secp256k1_schnorr_sign(
 /** Verify a signature created by secp256k1_schnorr_sign.
  *  Returns: 1: correct signature
  *           0: incorrect signature
- *  In:      ctx:       a secp256k1 context object, initialized for verification.
+ *  Args:    ctx:       a secp256k1 context object, initialized for verification.
+ *  In:      sig64:     the 64-byte signature being verified (cannot be NULL)
  *           msg32:     the 32-byte message hash being verified (cannot be NULL)
- *           sig64:     the 64-byte signature being verified (cannot be NULL)
  *           pubkey:    the public key to verify with (cannot be NULL)
  */
 SECP256K1_WARN_UNUSED_RESULT int secp256k1_schnorr_verify(
   const secp256k1_context_t* ctx,
-  const unsigned char *msg32,
   const unsigned char *sig64,
+  const unsigned char *msg32,
   const secp256k1_pubkey_t *pubkey
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 
@@ -53,47 +53,47 @@ SECP256K1_WARN_UNUSED_RESULT int secp256k1_schnorr_verify(
  *  Returns: 1: public key successfully recovered (which guarantees a correct
  *           signature).
  *           0: otherwise.
- *  In:      ctx:        pointer to a context object, initialized for
+ *  Args:    ctx:        pointer to a context object, initialized for
  *                       verification (cannot be NULL)
- *           msg32:      the 32-byte message hash assumed to be signed (cannot
- *                       be NULL)
- *           sig64:      signature as 64 byte array (cannot be NULL)
  *  Out:     pubkey:     pointer to a pubkey to set to the recovered public key
  *                       (cannot be NULL).
+ *  In:      sig64:      signature as 64 byte array (cannot be NULL)
+ *           msg32:      the 32-byte message hash assumed to be signed (cannot
+ *                       be NULL)
  */
 int secp256k1_schnorr_recover(
   const secp256k1_context_t* ctx,
-  const unsigned char *msg32,
+  secp256k1_pubkey_t *pubkey,
   const unsigned char *sig64,
-  secp256k1_pubkey_t *pubkey
+  const unsigned char *msg32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 
 /** Generate a nonce pair deterministically for use with
  *  secp256k1_schnorr_partial_sign.
  *  Returns: 1: valid nonce pair was generated.
  *           0: otherwise (nonce generation function failed)
- *  In:      ctx:         pointer to a context object, initialized for signing
+ *  Args:    ctx:         pointer to a context object, initialized for signing
  *                        (cannot be NULL)
- *           msg32:       the 32-byte message hash assumed to be signed (cannot
+ *  Out:     pubnonce:    public side of the nonce (cannot be NULL)
+ *           privnonce32: private side of the nonce (32 byte) (cannot be NULL)
+ *  In:      msg32:       the 32-byte message hash assumed to be signed (cannot
  *                        be NULL)
  *           sec32:       the 32-byte private key (cannot be NULL)
  *           noncefp:     pointer to a nonce generation function. If NULL,
  *                        secp256k1_nonce_function_default is used
  *           noncedata:   pointer to arbitrary data used by the nonce generation
  *                        function (can be NULL)
- *  Out:     pubnonce:    public side of the nonce (cannot be NULL)
- *           privnonce32: private side of the nonce (32 byte) (cannot be NULL)
  *
  *  Do not use the output as a private/public key pair for signing/validation.
  */
 int secp256k1_schnorr_generate_nonce_pair(
   const secp256k1_context_t* ctx,
+  secp256k1_pubkey_t *pubnonce,
+  unsigned char *privnonce32,
   const unsigned char *msg32,
   const unsigned char *sec32,
   secp256k1_nonce_function_t noncefp,
-  const void* noncedata,
-  secp256k1_pubkey_t *pubnonce,
-  unsigned char *privnonce32
+  const void* noncedata
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(6) SECP256K1_ARG_NONNULL(7);
 
 /** Produce a partial Schnorr signature, which can be combined using
@@ -103,14 +103,14 @@ int secp256k1_schnorr_generate_nonce_pair(
  *           0: no valid signature exists with this combination of keys, nonces
  *              and message (chance around 1 in 2^128)
  *          -1: invalid private key, nonce, or public nonces.
- *  In:   ctx:             pointer to context object, initialized for signing (cannot
+ *  Args: ctx:             pointer to context object, initialized for signing (cannot
  *                         be NULL)
- *        msg32:           pointer to 32-byte message to sign
+ *  Out:  sig64:           pointer to 64-byte array to put partial signature in
+ *  In:   msg32:           pointer to 32-byte message to sign
  *        sec32:           pointer to 32-byte private key
- *        secnonce32:      pointer to 32-byte array containing our nonce
  *        pubnonce_others: pointer to pubkey containing the sum of the other's
  *                         nonces (see secp256k1_ec_pubkey_combine)
- *  Out:  sig64:           pointer to 64-byte array to put partial signature in
+ *        secnonce32:      pointer to 32-byte array containing our nonce
  *
  * The intended procedure for creating a multiparty signature is:
  * - Each signer S[i] with private key x[i] and public key Q[i] runs
@@ -140,31 +140,31 @@ int secp256k1_schnorr_generate_nonce_pair(
  */
 SECP256K1_WARN_UNUSED_RESULT int secp256k1_schnorr_partial_sign(
   const secp256k1_context_t* ctx,
-  const unsigned char *msg32,
   unsigned char *sig64,
+  const unsigned char *msg32,
   const unsigned char *sec32,
-  const unsigned char *secnonce32,
-  const secp256k1_pubkey_t *pubnonce_others
+  const secp256k1_pubkey_t *pubnonce_others,
+  const unsigned char *secnonce32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4) SECP256K1_ARG_NONNULL(5) SECP256K1_ARG_NONNULL(6);
 
 /** Combine multiple Schnorr partial signatures.
  * Returns: 1: the passed signatures were succesfully combined.
  *          0: the resulting signature is not valid (chance of 1 in 2^256)
  *         -1: some inputs were invalid, or the signatures were not created
  *             using the same set of nonces
- * In:     ctx:      pointer to a context object
- *         sig64:    pointer to a 64-byte array to place the combined signature
+ * Args:   ctx:      pointer to a context object
+ * Out:    sig64:    pointer to a 64-byte array to place the combined signature
  *                   (cannot be NULL)
- *         n:        the number of signatures to combine (at least 1)
- * Out:    sig64sin: pointer to an array of n pointers to 64-byte input
+ * In:     sig64sin: pointer to an array of n pointers to 64-byte input
  *                   signatures
+ *         n:        the number of signatures to combine (at least 1)
  */
 SECP256K1_WARN_UNUSED_RESULT int secp256k1_schnorr_partial_combine(
   const secp256k1_context_t* ctx,
   unsigned char *sig64,
-  int n,
-  const unsigned char * const * sig64sin
-) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(4);
+  const unsigned char * const * sig64sin,
+  int n
+) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 
 # ifdef __cplusplus
 }

src/bench_recover.c

@@ -26,7 +26,7 @@ void bench_recover(void* arg) {
         int pubkeylen = 33;
         secp256k1_ecdsa_recoverable_signature_t sig;
         CHECK(secp256k1_ecdsa_recoverable_signature_parse_compact(data->ctx, &sig, data->sig, i % 2));
-        CHECK(secp256k1_ecdsa_recover(data->ctx, data->msg, &sig, &pubkey));
+        CHECK(secp256k1_ecdsa_recover(data->ctx, &pubkey, &sig, data->msg));
         CHECK(secp256k1_ec_pubkey_serialize(data->ctx, pubkeyc, &pubkeylen, &pubkey, 1));
         for (j = 0; j < 32; j++) {
             data->sig[j + 32] = data->msg[j];    /* Move former message to S. */

src/bench_schnorr_verify.c

@@ -34,7 +34,7 @@ static void benchmark_schnorr_init(void* arg) {
     for (k = 0; k < data->numsigs; k++) {
         secp256k1_pubkey_t pubkey;
         for (i = 0; i < 32; i++) data->sigs[k].key[i] = 33 + i + k;
-        secp256k1_schnorr_sign(data->ctx, data->msg, data->sigs[k].sig, data->sigs[k].key, NULL, NULL);
+        secp256k1_schnorr_sign(data->ctx, data->sigs[k].sig, data->msg, data->sigs[k].key, NULL, NULL);
         data->sigs[k].pubkeylen = 33;
         CHECK(secp256k1_ec_pubkey_create(data->ctx, &pubkey, data->sigs[k].key));
         CHECK(secp256k1_ec_pubkey_serialize(data->ctx, data->sigs[k].pubkey, &data->sigs[k].pubkeylen, &pubkey, 1));
@@ -49,7 +49,7 @@ static void benchmark_schnorr_verify(void* arg) {
         secp256k1_pubkey_t pubkey;
         data->sigs[0].sig[(i >> 8) % 64] ^= (i & 0xFF);
         CHECK(secp256k1_ec_pubkey_parse(data->ctx, &pubkey, data->sigs[0].pubkey, data->sigs[0].pubkeylen));
-        CHECK(secp256k1_schnorr_verify(data->ctx, data->msg, data->sigs[0].sig, &pubkey) == ((i & 0xFF) == 0));
+        CHECK(secp256k1_schnorr_verify(data->ctx, data->sigs[0].sig, data->msg, &pubkey) == ((i & 0xFF) == 0));
         data->sigs[0].sig[(i >> 8) % 64] ^= (i & 0xFF);
     }
 }

src/bench_sign.c

@@ -31,7 +31,7 @@ static void bench_sign(void* arg) {
         int siglen = 74;
         int j;
         secp256k1_ecdsa_signature_t signature;
-        CHECK(secp256k1_ecdsa_sign(data->ctx, data->msg, &signature, data->key, NULL, NULL));
+        CHECK(secp256k1_ecdsa_sign(data->ctx, &signature, data->msg, data->key, NULL, NULL));
         CHECK(secp256k1_ecdsa_signature_serialize_der(data->ctx, sig, &siglen, &signature));
         for (j = 0; j < 32; j++) {
             data->msg[j] = sig[j];

src/bench_verify.c

@@ -33,7 +33,7 @@ static void benchmark_verify(void* arg) {
         data->sig[data->siglen - 3] ^= ((i >> 16) & 0xFF);
         CHECK(secp256k1_ec_pubkey_parse(data->ctx, &pubkey, data->pubkey, data->pubkeylen) == 1);
         CHECK(secp256k1_ecdsa_signature_parse_der(data->ctx, &sig, data->sig, data->siglen) == 1);
-        CHECK(secp256k1_ecdsa_verify(data->ctx, data->msg, &sig, &pubkey) == (i == 0));
+        CHECK(secp256k1_ecdsa_verify(data->ctx, &sig, data->msg, &pubkey) == (i == 0));
         data->sig[data->siglen - 1] ^= (i & 0xFF);
         data->sig[data->siglen - 2] ^= ((i >> 8) & 0xFF);
         data->sig[data->siglen - 3] ^= ((i >> 16) & 0xFF);
@@ -51,7 +51,7 @@ int main(void) {
     for (i = 0; i < 32; i++) data.msg[i] = 1 + i;
     for (i = 0; i < 32; i++) data.key[i] = 33 + i;
     data.siglen = 72;
-    CHECK(secp256k1_ecdsa_sign(data.ctx, data.msg, &sig, data.key, NULL, NULL));
+    CHECK(secp256k1_ecdsa_sign(data.ctx, &sig, data.msg, data.key, NULL, NULL));
     CHECK(secp256k1_ecdsa_signature_serialize_der(data.ctx, data.sig, &data.siglen, &sig));
     CHECK(secp256k1_ec_pubkey_create(data.ctx, &pubkey, data.key));
     CHECK(secp256k1_ec_pubkey_serialize(data.ctx, data.pubkey, &data.pubkeylen, &pubkey, 1) == 1);

src/modules/recovery/main_impl.h

@@ -83,7 +83,7 @@ int secp256k1_ecdsa_recoverable_signature_convert(const secp256k1_context_t* ctx
     return 1;
 }
 
-int secp256k1_ecdsa_sign_recoverable(const secp256k1_context_t* ctx, const unsigned char *msg32, secp256k1_ecdsa_recoverable_signature_t *signature, const unsigned char *seckey, secp256k1_nonce_function_t noncefp, const void* noncedata) {
+int secp256k1_ecdsa_sign_recoverable(const secp256k1_context_t* ctx, secp256k1_ecdsa_recoverable_signature_t *signature, const unsigned char *msg32, const unsigned char *seckey, secp256k1_nonce_function_t noncefp, const void* noncedata) {
     secp256k1_scalar_t r, s;
     secp256k1_scalar_t sec, non, msg;
     int recid;
@@ -105,7 +105,7 @@ int secp256k1_ecdsa_sign_recoverable(const secp256k1_context_t* ctx, const unsig
         secp256k1_scalar_set_b32(&msg, msg32, NULL);
         while (1) {
             unsigned char nonce32[32];
-            ret = noncefp(nonce32, msg32, seckey, NULL, count, noncedata);
+            ret = noncefp(nonce32, seckey, msg32, NULL, noncedata, count);
             if (!ret) {
                 break;
             }
@@ -130,7 +130,7 @@ int secp256k1_ecdsa_sign_recoverable(const secp256k1_context_t* ctx, const unsig
     return ret;
 }
 
-int secp256k1_ecdsa_recover(const secp256k1_context_t* ctx, const unsigned char *msg32, const secp256k1_ecdsa_recoverable_signature_t *signature, secp256k1_pubkey_t *pubkey) {
+int secp256k1_ecdsa_recover(const secp256k1_context_t* ctx, secp256k1_pubkey_t *pubkey, const secp256k1_ecdsa_recoverable_signature_t *signature, const unsigned char *msg32) {
     secp256k1_ge_t q;
     secp256k1_scalar_t r, s;
     secp256k1_scalar_t m;