Merge #158: Small musig improvements

d895b10 musig: mention musig.md in example (Jonas Nick) 588009d musig: improve doc of partial_sig_verify regarding signing sessions (Jonas Nick) b109495 musig: remove superfluous comment (Jonas Nick) Pull request description: ACKs for top commit: robot-dreams: ACK d895b10 real-or-random: ACK d895b10 Tree-SHA512: 35169240868500bb27e5a6b8779f090d3f33a6c0cb1a4574e6e53e9c52782f454fe7df6d49b68e0acdd174e25a756bf6267339f0d4e94f28d5ae49145f21e298
BlockstreamResearch · Jan 25, 2022 · 8fd97d8 · 8fd97d8
2 parents 772df36 + d895b10
commit 8fd97d8
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 15 deletions.
diff --git a/examples/musig.c b/examples/musig.c
@@ -4,9 +4,9 @@
  * file COPYING or https://www.opensource.org/licenses/mit-license.php.*
  **********************************************************************/
 
-/**
- * This file demonstrates how to use the MuSig module to create a multisignature.
- * Additionally, see the documentation in include/secp256k1_musig.h.
+/** This file demonstrates how to use the MuSig module to create a
+ *  3-of-3 multisignature. Additionally, see the documentation in
+ *  include/secp256k1_musig.h and src/modules/musig/musig.md.
  */
 
 #include <stdio.h>

diff --git a/include/secp256k1_musig.h b/include/secp256k1_musig.h
@@ -459,6 +459,18 @@ SECP256K1_API int secp256k1_musig_partial_sign(
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4) SECP256K1_ARG_NONNULL(5) SECP256K1_ARG_NONNULL(6);
 
 /** Verifies an individual signer's partial signature
+ *
+ *  The signature is verified for a specific signing session. In order to avoid
+ *  accidentally verifying a signature from a different or non-existing signing
+ *  session, you must ensure the following:
+ *    1. The `keyagg_cache` argument is identical to the one used to create the
+ *       `session` with `musig_nonce_process`.
+ *    2. The `pubkey` argument must be identical to the one sent by the signer
+ *       before aggregating it with `musig_pubkey_agg` to create the
+ *       `keyagg_cache`.
+ *    3. The `pubnonce` argument must be identical to the one sent by the signer
+ *       before aggregating it with `musig_nonce_agg` and using the result to
+ *       create the `session` with `musig_nonce_process`.
  *
  *  This function is essential when using protocols with adaptor signatures.
  *  However, it is not essential for regular MuSig sessions, in the sense that if any
@@ -469,13 +481,14 @@ SECP256K1_API int secp256k1_musig_partial_sign(
  *  Returns: 0 if the arguments are invalid or the partial signature does not
  *           verify, 1 otherwise
  *  Args         ctx: pointer to a context object, initialized for verification
- *  In:  partial_sig: pointer to partial signature to verify
- *          pubnonce: public nonce sent by the signer who produced the signature
- *            pubkey: public key of the signer who produced the signature
+ *  In:  partial_sig: pointer to partial signature to verify, sent by
+ *                    the signer associated with `pubnonce` and `pubkey`
+ *          pubnonce: public nonce of the signer in the signing session
+ *            pubkey: public key of the signer in the signing session
  *      keyagg_cache: pointer to the keyagg_cache that was output when the
- *                    aggregate public key for this session
+ *                    aggregate public key for this signing session
  *           session: pointer to the session that was created with
- *                    musig_nonce_process
+ *                    `musig_nonce_process`
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_musig_partial_sig_verify(
     const secp256k1_context* ctx,

diff --git a/src/modules/musig/session_impl.h b/src/modules/musig/session_impl.h
@@ -673,13 +673,6 @@ int secp256k1_musig_partial_sig_verify(const secp256k1_context* ctx, const secp2
     secp256k1_musig_keyaggcoef(&mu, &cache_i, &pkp.x);
     secp256k1_scalar_mul(&e, &session_i.challenge, &mu);
 
-    /* If the MuSig-aggregate point has an odd Y coordinate, the signers will
-     * sign for the negation of their individual xonly public key. If the
-     * aggregate key is untweaked, then internal_key_parity is 0, so `e` is
-     * negated exactly when the aggregate key parity is odd. If the aggregate
-     * key is tweaked, then negation happens when the aggregate key has an odd Y
-     * coordinate XOR the internal key has an odd Y coordinate.*/
-
     /* When producing a partial signature, signer i uses a possibly
      * negated secret key:
      *