csecp256k1

Haskell FFI bindings to bitcoin-core/secp256k1 (docs.ppad.tech/csecp256k1).
git clone git://git.ppad.tech/csecp256k1.git
Log | Files | Refs | README | LICENSE

secp256k1_schnorrsig.h (8564B)


      1 #ifndef SECP256K1_SCHNORRSIG_H
      2 #define SECP256K1_SCHNORRSIG_H
      3 
      4 #include "secp256k1.h"
      5 #include "secp256k1_extrakeys.h"
      6 
      7 #ifdef __cplusplus
      8 extern "C" {
      9 #endif
     10 
     11 /** This module implements a variant of Schnorr signatures compliant with
     12  *  Bitcoin Improvement Proposal 340 "Schnorr Signatures for secp256k1"
     13  *  (https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki).
     14  */
     15 
     16 /** A pointer to a function to deterministically generate a nonce.
     17  *
     18  *  Same as haskellsecp256k1_v0_1_0_nonce function with the exception of accepting an
     19  *  additional pubkey argument and not requiring an attempt argument. The pubkey
     20  *  argument can protect signature schemes with key-prefixed challenge hash
     21  *  inputs against reusing the nonce when signing with the wrong precomputed
     22  *  pubkey.
     23  *
     24  *  Returns: 1 if a nonce was successfully generated. 0 will cause signing to
     25  *           return an error.
     26  *  Out:  nonce32: pointer to a 32-byte array to be filled by the function
     27  *  In:       msg: the message being verified. Is NULL if and only if msglen
     28  *                 is 0.
     29  *         msglen: the length of the message
     30  *          key32: pointer to a 32-byte secret key (will not be NULL)
     31  *     xonly_pk32: the 32-byte serialized xonly pubkey corresponding to key32
     32  *                 (will not be NULL)
     33  *           algo: pointer to an array describing the signature
     34  *                 algorithm (will not be NULL)
     35  *        algolen: the length of the algo array
     36  *           data: arbitrary data pointer that is passed through
     37  *
     38  *  Except for test cases, this function should compute some cryptographic hash of
     39  *  the message, the key, the pubkey, the algorithm description, and data.
     40  */
     41 typedef int (*haskellsecp256k1_v0_1_0_nonce_function_hardened)(
     42     unsigned char *nonce32,
     43     const unsigned char *msg,
     44     size_t msglen,
     45     const unsigned char *key32,
     46     const unsigned char *xonly_pk32,
     47     const unsigned char *algo,
     48     size_t algolen,
     49     void *data
     50 );
     51 
     52 /** An implementation of the nonce generation function as defined in Bitcoin
     53  *  Improvement Proposal 340 "Schnorr Signatures for secp256k1"
     54  *  (https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki).
     55  *
     56  *  If a data pointer is passed, it is assumed to be a pointer to 32 bytes of
     57  *  auxiliary random data as defined in BIP-340. If the data pointer is NULL,
     58  *  the nonce derivation procedure follows BIP-340 by setting the auxiliary
     59  *  random data to zero. The algo argument must be non-NULL, otherwise the
     60  *  function will fail and return 0. The hash will be tagged with algo.
     61  *  Therefore, to create BIP-340 compliant signatures, algo must be set to
     62  *  "BIP0340/nonce" and algolen to 13.
     63  */
     64 SECP256K1_API const haskellsecp256k1_v0_1_0_nonce_function_hardened haskellsecp256k1_v0_1_0_nonce_function_bip340;
     65 
     66 /** Data structure that contains additional arguments for schnorrsig_sign_custom.
     67  *
     68  *  A schnorrsig_extraparams structure object can be initialized correctly by
     69  *  setting it to SECP256K1_SCHNORRSIG_EXTRAPARAMS_INIT.
     70  *
     71  *  Members:
     72  *      magic: set to SECP256K1_SCHNORRSIG_EXTRAPARAMS_MAGIC at initialization
     73  *             and has no other function than making sure the object is
     74  *             initialized.
     75  *    noncefp: pointer to a nonce generation function. If NULL,
     76  *             haskellsecp256k1_v0_1_0_nonce_function_bip340 is used
     77  *      ndata: pointer to arbitrary data used by the nonce generation function
     78  *             (can be NULL). If it is non-NULL and
     79  *             haskellsecp256k1_v0_1_0_nonce_function_bip340 is used, then ndata must be a
     80  *             pointer to 32-byte auxiliary randomness as per BIP-340.
     81  */
     82 typedef struct {
     83     unsigned char magic[4];
     84     haskellsecp256k1_v0_1_0_nonce_function_hardened noncefp;
     85     void *ndata;
     86 } haskellsecp256k1_v0_1_0_schnorrsig_extraparams;
     87 
     88 #define SECP256K1_SCHNORRSIG_EXTRAPARAMS_MAGIC { 0xda, 0x6f, 0xb3, 0x8c }
     89 #define SECP256K1_SCHNORRSIG_EXTRAPARAMS_INIT {\
     90     SECP256K1_SCHNORRSIG_EXTRAPARAMS_MAGIC,\
     91     NULL,\
     92     NULL\
     93 }
     94 
     95 /** Create a Schnorr signature.
     96  *
     97  *  Does _not_ strictly follow BIP-340 because it does not verify the resulting
     98  *  signature. Instead, you can manually use haskellsecp256k1_v0_1_0_schnorrsig_verify and
     99  *  abort if it fails.
    100  *
    101  *  This function only signs 32-byte messages. If you have messages of a
    102  *  different size (or the same size but without a context-specific tag
    103  *  prefix), it is recommended to create a 32-byte message hash with
    104  *  haskellsecp256k1_v0_1_0_tagged_sha256 and then sign the hash. Tagged hashing allows
    105  *  providing an context-specific tag for domain separation. This prevents
    106  *  signatures from being valid in multiple contexts by accident.
    107  *
    108  *  Returns 1 on success, 0 on failure.
    109  *  Args:    ctx: pointer to a context object (not haskellsecp256k1_v0_1_0_context_static).
    110  *  Out:   sig64: pointer to a 64-byte array to store the serialized signature.
    111  *  In:    msg32: the 32-byte message being signed.
    112  *       keypair: pointer to an initialized keypair.
    113  *    aux_rand32: 32 bytes of fresh randomness. While recommended to provide
    114  *                this, it is only supplemental to security and can be NULL. A
    115  *                NULL argument is treated the same as an all-zero one. See
    116  *                BIP-340 "Default Signing" for a full explanation of this
    117  *                argument and for guidance if randomness is expensive.
    118  */
    119 SECP256K1_API int haskellsecp256k1_v0_1_0_schnorrsig_sign32(
    120     const haskellsecp256k1_v0_1_0_context *ctx,
    121     unsigned char *sig64,
    122     const unsigned char *msg32,
    123     const haskellsecp256k1_v0_1_0_keypair *keypair,
    124     const unsigned char *aux_rand32
    125 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
    126 
    127 /** Same as haskellsecp256k1_v0_1_0_schnorrsig_sign32, but DEPRECATED. Will be removed in
    128  *  future versions. */
    129 SECP256K1_API int haskellsecp256k1_v0_1_0_schnorrsig_sign(
    130     const haskellsecp256k1_v0_1_0_context *ctx,
    131     unsigned char *sig64,
    132     const unsigned char *msg32,
    133     const haskellsecp256k1_v0_1_0_keypair *keypair,
    134     const unsigned char *aux_rand32
    135 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4)
    136   SECP256K1_DEPRECATED("Use haskellsecp256k1_v0_1_0_schnorrsig_sign32 instead");
    137 
    138 /** Create a Schnorr signature with a more flexible API.
    139  *
    140  *  Same arguments as haskellsecp256k1_v0_1_0_schnorrsig_sign except that it allows signing
    141  *  variable length messages and accepts a pointer to an extraparams object that
    142  *  allows customizing signing by passing additional arguments.
    143  *
    144  *  Equivalent to haskellsecp256k1_v0_1_0_schnorrsig_sign32(..., aux_rand32) if msglen is 32
    145  *  and extraparams is initialized as follows:
    146  *  ```
    147  *  haskellsecp256k1_v0_1_0_schnorrsig_extraparams extraparams = SECP256K1_SCHNORRSIG_EXTRAPARAMS_INIT;
    148  *  extraparams.ndata = (unsigned char*)aux_rand32;
    149  *  ```
    150  *
    151  *  Returns 1 on success, 0 on failure.
    152  *  Args:   ctx: pointer to a context object (not haskellsecp256k1_v0_1_0_context_static).
    153  *  Out:  sig64: pointer to a 64-byte array to store the serialized signature.
    154  *  In:     msg: the message being signed. Can only be NULL if msglen is 0.
    155  *       msglen: length of the message.
    156  *      keypair: pointer to an initialized keypair.
    157  *  extraparams: pointer to an extraparams object (can be NULL).
    158  */
    159 SECP256K1_API int haskellsecp256k1_v0_1_0_schnorrsig_sign_custom(
    160     const haskellsecp256k1_v0_1_0_context *ctx,
    161     unsigned char *sig64,
    162     const unsigned char *msg,
    163     size_t msglen,
    164     const haskellsecp256k1_v0_1_0_keypair *keypair,
    165     haskellsecp256k1_v0_1_0_schnorrsig_extraparams *extraparams
    166 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(5);
    167 
    168 /** Verify a Schnorr signature.
    169  *
    170  *  Returns: 1: correct signature
    171  *           0: incorrect signature
    172  *  Args:    ctx: pointer to a context object.
    173  *  In:    sig64: pointer to the 64-byte signature to verify.
    174  *           msg: the message being verified. Can only be NULL if msglen is 0.
    175  *        msglen: length of the message
    176  *        pubkey: pointer to an x-only public key to verify with
    177  */
    178 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int haskellsecp256k1_v0_1_0_schnorrsig_verify(
    179     const haskellsecp256k1_v0_1_0_context *ctx,
    180     const unsigned char *sig64,
    181     const unsigned char *msg,
    182     size_t msglen,
    183     const haskellsecp256k1_v0_1_0_xonly_pubkey *pubkey
    184 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(5);
    185 
    186 #ifdef __cplusplus
    187 }
    188 #endif
    189 
    190 #endif /* SECP256K1_SCHNORRSIG_H */