[SECP256K1] Rename msg32 to msghash32 in ecdsa_sign/verify and add explanation

Summary:
Backport of [[bitcoin-core/secp256k1#854 | secp256k1#854]]

Did the same for the schnorr module.

Test Plan:
  ninja check-secp256k1

Reviewers: #bitcoin_abc, PiRK

Reviewed By: #bitcoin_abc, PiRK

Differential Revision: https://reviews.bitcoinabc.org/D9376

Author: jonasnick

src/secp256k1/include/secp256k1.h

@@ -452,7 +452,14 @@ SECP256K1_API int secp256k1_ecdsa_signature_serialize_compact(
  *           0: incorrect or unparseable signature
  *  Args:    ctx:       a secp256k1 context object, initialized for verification.
  *  In:      sig:       the signature being verified (cannot be NULL)
- *           msg32:     the 32-byte message hash being verified (cannot be NULL)
+ *           msghash32: the 32-byte message hash being verified (cannot be NULL).
+ *                      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
+ *                      create a "valid" signature without knowledge of the
+ *                      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)
  *
  * To avoid accepting malleable signatures, only ECDSA signatures in lower-S
@@ -467,7 +474,7 @@ SECP256K1_API int secp256k1_ecdsa_signature_serialize_compact(
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_verify(
     const secp256k1_context* ctx,
     const secp256k1_ecdsa_signature *sig,
-    const unsigned char *msg32,
+    const unsigned char *msghash32,
     const secp256k1_pubkey *pubkey
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 
@@ -532,20 +539,20 @@ 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:      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)
+ *  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)
  *
  * The created signature is always in lower-S form. See
  * secp256k1_ecdsa_signature_normalize for more details.
  */
 SECP256K1_API int secp256k1_ecdsa_sign(
     const secp256k1_context* ctx,
     secp256k1_ecdsa_signature *sig,
-    const unsigned char *msg32,
+    const unsigned char *msghash32,
     const unsigned char *seckey,
     secp256k1_nonce_function noncefp,
     const void *ndata
@@ -626,23 +633,23 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_negate(
  *                  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)
- *  In:      tweak: pointer to a 32-byte tweak. If the tweak is invalid according to
+ *  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).
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_add(
     const secp256k1_context* ctx,
     unsigned char *seckey,
-    const unsigned char *tweak
+    const unsigned char *tweak32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 
 /** Same as secp256k1_ec_seckey_tweak_add, but DEPRECATED. Will be removed in
  *  future versions. */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_add(
     const secp256k1_context* ctx,
     unsigned char *seckey,
-    const unsigned char *tweak
+    const unsigned char *tweak32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 
 /** Tweak a public key by adding tweak times the generator to it.
@@ -654,15 +661,15 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_add(
  *                  (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).
- *  In:      tweak: pointer to a 32-byte tweak. If the tweak is invalid according to
+ *  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).
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_add(
     const secp256k1_context* ctx,
     secp256k1_pubkey *pubkey,
-    const unsigned char *tweak
+    const unsigned char *tweak32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 
 /** Tweak a secret key by multiplying it by a tweak.
@@ -673,23 +680,23 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_add(
  *                  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)
- *  In:      tweak: pointer to a 32-byte tweak. If the tweak is invalid according to
+ *  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).
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_mul(
     const secp256k1_context* ctx,
     unsigned char *seckey,
-    const unsigned char *tweak
+    const unsigned char *tweak32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 
 /** Same as secp256k1_ec_seckey_tweak_mul, but DEPRECATED. Will be removed in
  *  future versions. */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_mul(
     const secp256k1_context* ctx,
     unsigned char *seckey,
-    const unsigned char *tweak
+    const unsigned char *tweak32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 
 /** Tweak a public key by multiplying it by a tweak value.
@@ -699,15 +706,15 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_mul(
  *                  (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).
- *  In:      tweak: pointer to a 32-byte tweak. If the tweak is invalid according to
+ *  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).
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_mul(
     const secp256k1_context* ctx,
     secp256k1_pubkey *pubkey,
-    const unsigned char *tweak
+    const unsigned char *tweak32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 
 /** Updates the context randomization to protect against side-channel leakage.

src/secp256k1/include/secp256k1_recovery.h

@@ -71,17 +71,17 @@ 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:      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)
+ *  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)
  */
 SECP256K1_API int secp256k1_ecdsa_sign_recoverable(
     const secp256k1_context* ctx,
     secp256k1_ecdsa_recoverable_signature *sig,
-    const unsigned char *msg32,
+    const unsigned char *msghash32,
     const unsigned char *seckey,
     secp256k1_nonce_function noncefp,
     const void *ndata
@@ -91,16 +91,16 @@ 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)
- *           msg32:      the 32-byte message hash assumed to be signed (cannot be NULL)
+ *  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)
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_recover(
     const secp256k1_context* ctx,
     secp256k1_pubkey *pubkey,
     const secp256k1_ecdsa_recoverable_signature *sig,
-    const unsigned char *msg32
+    const unsigned char *msghash32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 
 #ifdef __cplusplus

src/secp256k1/include/secp256k1_schnorr.h

@@ -13,13 +13,18 @@ extern "C" {
  *          0: incorrect signature
  * 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)
+ *          msghash32: the 32-byte message hash being verified (cannot be NULL).
+ *                     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
+ *                     create a "valid" signature without knowledge of the
+ *                     secret key.
  *          pubkey:    the public key to verify with (cannot be NULL)
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_schnorr_verify(
   const secp256k1_context* ctx,
   const unsigned char *sig64,
-  const unsigned char *msg32,
+  const unsigned char *msghash32,
   const secp256k1_pubkey *pubkey
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 
@@ -30,21 +35,21 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_schnorr_verify(
  * Returns: 1: signature created
  *          0: the nonce generation function failed, or the private key was
  *             invalid.
- * Args:    ctx:    pointer to a context object, initialized for signing
- *                  (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)
+ * Args:    ctx:       pointer to a context object, initialized for signing
+ *                     (cannot be NULL)
+ * Out:     sig64:     pointer to a 64-byte 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)
  */
 SECP256K1_API int secp256k1_schnorr_sign(
   const secp256k1_context *ctx,
   unsigned char *sig64,
-  const unsigned char *msg32,
+  const unsigned char *msghash32,
   const unsigned char *seckey,
   secp256k1_nonce_function noncefp,
   const void *ndata

src/secp256k1/src/modules/recovery/main_impl.h

@@ -120,35 +120,35 @@ static int secp256k1_ecdsa_sig_recover(const secp256k1_ecmult_context *ctx, cons
     return !secp256k1_gej_is_infinity(&qj);
 }
 
-int secp256k1_ecdsa_sign_recoverable(const secp256k1_context* ctx, secp256k1_ecdsa_recoverable_signature *signature, const unsigned char *msg32, const unsigned char *seckey, secp256k1_nonce_function noncefp, const void* noncedata) {
+int secp256k1_ecdsa_sign_recoverable(const secp256k1_context* ctx, secp256k1_ecdsa_recoverable_signature *signature, const unsigned char *msghash32, const unsigned char *seckey, secp256k1_nonce_function noncefp, const void* noncedata) {
     secp256k1_scalar r, s;
     int ret, recid;
     const unsigned char secp256k1_ecdsa_recoverable_algo16[17] = "ECDSA+Recovery  ";
     VERIFY_CHECK(ctx != NULL);
     ARG_CHECK(secp256k1_ecmult_gen_context_is_built(&ctx->ecmult_gen_ctx));
-    ARG_CHECK(msg32 != NULL);
+    ARG_CHECK(msghash32 != NULL);
     ARG_CHECK(signature != NULL);
     ARG_CHECK(seckey != NULL);
 
-    ret = secp256k1_ecdsa_sign_inner(ctx, &r, &s, &recid, msg32, seckey, noncefp, secp256k1_ecdsa_recoverable_algo16, noncedata);
+    ret = secp256k1_ecdsa_sign_inner(ctx, &r, &s, &recid, msghash32, seckey, noncefp, secp256k1_ecdsa_recoverable_algo16, noncedata);
     secp256k1_ecdsa_recoverable_signature_save(signature, &r, &s, recid);
     return ret;
 }
 
-int secp256k1_ecdsa_recover(const secp256k1_context* ctx, secp256k1_pubkey *pubkey, const secp256k1_ecdsa_recoverable_signature *signature, const unsigned char *msg32) {
+int secp256k1_ecdsa_recover(const secp256k1_context* ctx, secp256k1_pubkey *pubkey, const secp256k1_ecdsa_recoverable_signature *signature, const unsigned char *msghash32) {
     secp256k1_ge q;
     secp256k1_scalar r, s;
     secp256k1_scalar m;
     int recid;
     VERIFY_CHECK(ctx != NULL);
     ARG_CHECK(secp256k1_ecmult_context_is_built(&ctx->ecmult_ctx));
-    ARG_CHECK(msg32 != NULL);
+    ARG_CHECK(msghash32 != NULL);
     ARG_CHECK(signature != NULL);
     ARG_CHECK(pubkey != NULL);
 
     secp256k1_ecdsa_recoverable_signature_load(ctx, &r, &s, &recid, signature);
     VERIFY_CHECK(recid >= 0 && recid < 4);  /* should have been caught in parse_compact */
-    secp256k1_scalar_set_b32(&m, msg32, NULL);
+    secp256k1_scalar_set_b32(&m, msghash32, NULL);
     if (secp256k1_ecdsa_sig_recover(&ctx->ecmult_ctx, &r, &s, &q, &m, recid)) {
         secp256k1_pubkey_save(pubkey, &q);
         return 1;

src/secp256k1/src/modules/schnorr/main_impl.h

@@ -13,27 +13,27 @@
 int secp256k1_schnorr_verify(
     const secp256k1_context* ctx,
     const unsigned char *sig64,
-    const unsigned char *msg32,
+    const unsigned char *msghash32,
     const secp256k1_pubkey *pubkey
 ) {
     secp256k1_ge q;
     VERIFY_CHECK(ctx != NULL);
     ARG_CHECK(secp256k1_ecmult_context_is_built(&ctx->ecmult_ctx));
-    ARG_CHECK(msg32 != NULL);
+    ARG_CHECK(msghash32 != NULL);
     ARG_CHECK(sig64 != NULL);
     ARG_CHECK(pubkey != NULL);
 
     if (!secp256k1_pubkey_load(ctx, &q, pubkey)) {
         return 0;
     }
 
-    return secp256k1_schnorr_sig_verify(&ctx->ecmult_ctx, sig64, &q, msg32);
+    return secp256k1_schnorr_sig_verify(&ctx->ecmult_ctx, sig64, &q, msghash32);
 }
 
 int secp256k1_schnorr_sign(
     const secp256k1_context *ctx,
     unsigned char *sig64,
-    const unsigned char *msg32,
+    const unsigned char *msghash32,
     const unsigned char *seckey,
     secp256k1_nonce_function noncefp,
     const void *ndata
@@ -46,7 +46,7 @@ int secp256k1_schnorr_sign(
     int pubkeyret;
     VERIFY_CHECK(ctx != NULL);
     ARG_CHECK(secp256k1_ecmult_gen_context_is_built(&ctx->ecmult_gen_ctx));
-    ARG_CHECK(msg32 != NULL);
+    ARG_CHECK(msghash32 != NULL);
     ARG_CHECK(sig64 != NULL);
     ARG_CHECK(seckey != NULL);
 
@@ -65,7 +65,7 @@ int secp256k1_schnorr_sign(
     overflow |= secp256k1_scalar_is_zero(&sec);
     secp256k1_scalar_cmov(&sec, &secp256k1_scalar_one, overflow);
 
-    ret = secp256k1_schnorr_sig_sign(ctx, sig64, msg32, &sec, &p, noncefp, ndata);
+    ret = secp256k1_schnorr_sig_sign(ctx, sig64, msghash32, &sec, &p, noncefp, ndata);
     if (!ret) {
         memset(sig64, 0, 64);
     }