schnorrsig API overhaul

README.md

@@ -17,6 +17,7 @@ Features:
 * Suitable for embedded systems.
 * Optional module for public key recovery.
 * Optional module for ECDH key exchange.
+* Optional module for Schnorr signatures according to [BIP-340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki) (experimental).
 
 Experimental features have not received enough scrutiny to satisfy the standard of quality of this library but are made available for testing and review by the community. The APIs of these features should not be considered stable.
 

include/secp256k1.h

@@ -793,6 +793,31 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_combine(
     size_t n
 ) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 
+/** Compute a tagged hash as defined in BIP-340.
+ *
+ *  This is useful for creating a message hash and achieving domain separation
+ *  through an application-specific tag. This function returns
+ *  SHA256(SHA256(tag)||SHA256(tag)||msg). Therefore, tagged hash
+ *  implementations optimized for a specific tag can precompute the SHA256 state
+ *  after hashing the tag hashes.
+ *
+ *  Returns 0 if the arguments are invalid and 1 otherwise.
+ *  Args:    ctx: pointer to a context object
+ *  Out:  hash32: pointer to a 32-byte array to store the resulting hash
+ *  In:      tag: pointer to an array containing the tag
+ *        taglen: length of the tag array
+ *           msg: pointer to an array containing the message
+ *        msglen: length of the message array
+ */
+SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_tagged_sha256(
+    const secp256k1_context* ctx,
+    unsigned char *hash32,
+    const unsigned char *tag,
+    size_t taglen,
+    const unsigned char *msg,
+    size_t msglen
+) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(5);
+
 #ifdef __cplusplus
 }
 #endif

include/secp256k1_schnorrsig.h

@@ -23,24 +23,29 @@ extern "C" {
  *
  *  Returns: 1 if a nonce was successfully generated. 0 will cause signing to
  *           return an error.
- *  Out:     nonce32:   pointer to a 32-byte array to be filled by the function.
- *  In:      msg32:     the 32-byte message hash being verified (will not be NULL)
- *           key32:     pointer to a 32-byte secret key (will not be NULL)
- *      xonly_pk32:     the 32-byte serialized xonly pubkey corresponding to key32
- *                      (will not be NULL)
- *           algo16:    pointer to a 16-byte array describing the signature
- *                      algorithm (will not be NULL).
- *           data:      Arbitrary data pointer that is passed through.
+ *  Out:  nonce32: pointer to a 32-byte array to be filled by the function
+ *  In:       msg: the message being verified. Is NULL if and only if msglen
+ *                 is 0.
+ *         msglen: the length of the message
+ *          key32: pointer to a 32-byte secret key (will not be NULL)
+ *     xonly_pk32: the 32-byte serialized xonly pubkey corresponding to key32
+ *                 (will not be NULL)
+ *           algo: pointer to an array describing the signature
+ *                 algorithm (will not be NULL)
+ *        algolen: the length of the algo array
+ *           data: arbitrary data pointer that is passed through
  *
  *  Except for test cases, this function should compute some cryptographic hash of
  *  the message, the key, the pubkey, the algorithm description, and data.
  */
 typedef int (*secp256k1_nonce_function_hardened)(
     unsigned char *nonce32,
-    const unsigned char *msg32,
+    const unsigned char *msg,
+    size_t msglen,
     const unsigned char *key32,
     const unsigned char *xonly_pk32,
-    const unsigned char *algo16,
+    const unsigned char *algo,
+    size_t algolen,
     void *data
 );
 
@@ -50,59 +55,113 @@ typedef int (*secp256k1_nonce_function_hardened)(
  *
  *  If a data pointer is passed, it is assumed to be a pointer to 32 bytes of
  *  auxiliary random data as defined in BIP-340. If the data pointer is NULL,
- *  schnorrsig_sign does not produce BIP-340 compliant signatures. The algo16
- *  argument must be non-NULL, otherwise the function will fail and return 0.
- *  The hash will be tagged with algo16 after removing all terminating null
- *  bytes. Therefore, to create BIP-340 compliant signatures, algo16 must be set
- *  to "BIP0340/nonce\0\0\0"
+ *  the nonce derivation procedure follows BIP-340 by setting the auxiliary
+ *  random data to zero. The algo argument must be non-NULL, otherwise the
+ *  function will fail and return 0. The hash will be tagged with algo.
+ *  Therefore, to create BIP-340 compliant signatures, algo must be set to
+ *  "BIP0340/nonce" and algolen to 13.
  */
 SECP256K1_API extern const secp256k1_nonce_function_hardened secp256k1_nonce_function_bip340;
 
+/** Data structure that contains additional arguments for schnorrsig_sign_custom.
+ *
+ *  A schnorrsig_extraparams structure object can be initialized correctly by
+ *  setting it to SECP256K1_SCHNORRSIG_EXTRAPARAMS_INIT.
+ *
+ *  Members:
+ *      magic: set to SECP256K1_SCHNORRSIG_EXTRAPARAMS_MAGIC at initialization
+ *             and has no other function than making sure the object is
+ *             initialized.
+ *    noncefp: pointer to a nonce generation function. If NULL,
+ *             secp256k1_nonce_function_bip340 is used
+ *      ndata: pointer to arbitrary data used by the nonce generation function
+ *             (can be NULL). If it is non-NULL and
+ *             secp256k1_nonce_function_bip340 is used, then ndata must be a
+ *             pointer to 32-byte auxiliary randomness as per BIP-340.
+ */
+typedef struct {
+    unsigned char magic[4];
+    secp256k1_nonce_function_hardened noncefp;
+    void* ndata;
+} secp256k1_schnorrsig_extraparams;
+
+#define SECP256K1_SCHNORRSIG_EXTRAPARAMS_MAGIC "\xda\x6f\xb3\x8c"
+#define SECP256K1_SCHNORRSIG_EXTRAPARAMS_INIT {\
+    SECP256K1_SCHNORRSIG_EXTRAPARAMS_MAGIC,\
+    NULL,\
+    NULL\
+}
+
 /** Create a Schnorr signature.
  *
  *  Does _not_ strictly follow BIP-340 because it does not verify the resulting
  *  signature. Instead, you can manually use secp256k1_schnorrsig_verify and
  *  abort if it fails.
  *
- *  Otherwise BIP-340 compliant if the noncefp argument is NULL or
- *  secp256k1_nonce_function_bip340 and the ndata argument is 32-byte auxiliary
- *  randomness.
+ *  This function only signs 32-byte messages. If you have messages of a
+ *  different size (or the same size but without a context-specific tag
+ *  prefix), it is recommended to create a 32-byte message hash with
+ *  secp256k1_tagged_sha256 and then sign the hash. Tagged hashing allows
+ *  providing an context-specific tag for domain separation. This prevents
+ *  signatures from being valid in multiple contexts by accident.
  *
  *  Returns 1 on success, 0 on failure.
  *  Args:    ctx: pointer to a context object, initialized for signing (cannot be NULL)
  *  Out:   sig64: pointer to a 64-byte array to store the serialized signature (cannot be NULL)
  *  In:    msg32: the 32-byte message being signed (cannot be NULL)
  *       keypair: pointer to an initialized keypair (cannot be NULL)
- *       noncefp: pointer to a nonce generation function. If NULL, secp256k1_nonce_function_bip340 is used
- *         ndata: pointer to arbitrary data used by the nonce generation
- *                function (can be NULL). If it is non-NULL and
- *                secp256k1_nonce_function_bip340 is used, then ndata must be a
- *                pointer to 32-byte auxiliary randomness as per BIP-340.
+ *    aux_rand32: 32 bytes of fresh randomness. While recommended to provide
+ *                this, it is only supplemental to security and can be NULL. See
+ *                BIP-340 "Default Signing" for a full explanation of this
+ *                argument and for guidance if randomness is expensive.
  */
 SECP256K1_API int secp256k1_schnorrsig_sign(
     const secp256k1_context* ctx,
     unsigned char *sig64,
     const unsigned char *msg32,
     const secp256k1_keypair *keypair,
-    secp256k1_nonce_function_hardened noncefp,
-    void *ndata
+    unsigned char *aux_rand32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 
+/** Create a Schnorr signature with a more flexible API.
+ *
+ *  Same arguments as secp256k1_schnorrsig_sign except that it allows signing
+ *  variable length messages and accepts a pointer to an extraparams object that
+ *  allows customizing signing by passing additional arguments.
+ *
+ *  Creates the same signatures as schnorrsig_sign if msglen is 32 and the
+ *  extraparams.ndata is the same as aux_rand32.
+ *
+ *  In:     msg: the message being signed. Can only be NULL if msglen is 0.
+ *       msglen: length of the message
+ *  extraparams: pointer to a extraparams object (can be NULL)
+ */
+SECP256K1_API int secp256k1_schnorrsig_sign_custom(
+    const secp256k1_context* ctx,
+    unsigned char *sig64,
+    const unsigned char *msg,
+    size_t msglen,
+    const secp256k1_keypair *keypair,
+    secp256k1_schnorrsig_extraparams *extraparams
+) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(5);
+
 /** Verify a Schnorr signature.
  *
  *  Returns: 1: correct signature
  *           0: incorrect signature
  *  Args:    ctx: a secp256k1 context object, initialized for verification.
  *  In:    sig64: pointer to the 64-byte signature to verify (cannot be NULL)
- *         msg32: the 32-byte message being verified (cannot be NULL)
+ *           msg: the message being verified. Can only be NULL if msglen is 0.
+ *        msglen: length of the message
  *        pubkey: pointer to an x-only public key to verify with (cannot be NULL)
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_schnorrsig_verify(
     const secp256k1_context* ctx,
     const unsigned char *sig64,
-    const unsigned char *msg32,
+    const unsigned char *msg,
+    size_t msglen,
     const secp256k1_xonly_pubkey *pubkey
-) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
+) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(5);
 
 #ifdef __cplusplus
 }

src/bench_schnorrsig.c

@@ -13,6 +13,8 @@
 #include "util.h"
 #include "bench.h"
 
+#define MSGLEN 32
+
 typedef struct {
     secp256k1_context *ctx;
     int n;
@@ -26,13 +28,13 @@ typedef struct {
 void bench_schnorrsig_sign(void* arg, int iters) {
     bench_schnorrsig_data *data = (bench_schnorrsig_data *)arg;
     int i;
-    unsigned char msg[32] = "benchmarkexamplemessagetemplate";
+    unsigned char msg[MSGLEN] = {0};
     unsigned char sig[64];
 
     for (i = 0; i < iters; i++) {
         msg[0] = i;
         msg[1] = i >> 8;
-        CHECK(secp256k1_schnorrsig_sign(data->ctx, sig, msg, data->keypairs[i], NULL, NULL));
+        CHECK(secp256k1_schnorrsig_sign_custom(data->ctx, sig, msg, MSGLEN, data->keypairs[i], NULL));
     }
 }
 
@@ -43,7 +45,7 @@ void bench_schnorrsig_verify(void* arg, int iters) {
     for (i = 0; i < iters; i++) {
         secp256k1_xonly_pubkey pk;
         CHECK(secp256k1_xonly_pubkey_parse(data->ctx, &pk, data->pk[i]) == 1);
-        CHECK(secp256k1_schnorrsig_verify(data->ctx, data->sigs[i], data->msgs[i], &pk));
+        CHECK(secp256k1_schnorrsig_verify(data->ctx, data->sigs[i], data->msgs[i], MSGLEN, &pk));
     }
 }
 
@@ -58,9 +60,10 @@ int main(void) {
     data.msgs = (const unsigned char **)malloc(iters * sizeof(unsigned char *));
     data.sigs = (const unsigned char **)malloc(iters * sizeof(unsigned char *));
 
+    CHECK(MSGLEN >= 4);
     for (i = 0; i < iters; i++) {
         unsigned char sk[32];
-        unsigned char *msg = (unsigned char *)malloc(32);
+        unsigned char *msg = (unsigned char *)malloc(MSGLEN);
         unsigned char *sig = (unsigned char *)malloc(64);
         secp256k1_keypair *keypair = (secp256k1_keypair *)malloc(sizeof(*keypair));
         unsigned char *pk_char = (unsigned char *)malloc(32);
@@ -69,7 +72,7 @@ int main(void) {
         msg[1] = sk[1] = i >> 8;
         msg[2] = sk[2] = i >> 16;
         msg[3] = sk[3] = i >> 24;
-        memset(&msg[4], 'm', 28);
+        memset(&msg[4], 'm', MSGLEN - 4);
         memset(&sk[4], 's', 28);
 
         data.keypairs[i] = keypair;
@@ -78,7 +81,7 @@ int main(void) {
         data.sigs[i] = sig;
 
         CHECK(secp256k1_keypair_create(data.ctx, keypair, sk));
-        CHECK(secp256k1_schnorrsig_sign(data.ctx, sig, msg, keypair, NULL, NULL));
+        CHECK(secp256k1_schnorrsig_sign_custom(data.ctx, sig, msg, MSGLEN, keypair, NULL));
         CHECK(secp256k1_keypair_xonly_pub(data.ctx, &pk, NULL, keypair));
         CHECK(secp256k1_xonly_pubkey_serialize(data.ctx, pk_char, &pk) == 1);
     }