include/secp256k1_extrakeys.h

   1 #ifndef SECP256K1_EXTRAKEYS_H
   2 #define SECP256K1_EXTRAKEYS_H
   3
   4 #include "secp256k1.h"
   5
   6 #ifdef __cplusplus
   7 extern "C" {
   8 #endif
   9
  10 /** Opaque data structure that holds a parsed and valid "x-only" public key.
  11  *  An x-only pubkey encodes a point whose Y coordinate is even. It is
  12  *  serialized using only its X coordinate (32 bytes). See BIP-340 for more
  13  *  information about x-only pubkeys.
  14  *
  15  *  The exact representation of data inside is implementation defined and not
  16  *  guaranteed to be portable between different platforms or versions. It is
  17  *  however guaranteed to be 64 bytes in size, and can be safely copied/moved.
  18  *  If you need to convert to a format suitable for storage, transmission, or
  19  *  comparison, use secp256k1_xonly_pubkey_serialize and
  20  *  secp256k1_xonly_pubkey_parse.
  21  */
  22 typedef struct {
  23     unsigned char data[64];
  24 } secp256k1_xonly_pubkey;
  25
  26 /** Opaque data structure that holds a keypair consisting of a secret and a
  27  *  public key.
  28  *
  29  *  The exact representation of data inside is implementation defined and not
  30  *  guaranteed to be portable between different platforms or versions. It is
  31  *  however guaranteed to be 96 bytes in size, and can be safely copied/moved.
  32  */
  33 typedef struct {
  34     unsigned char data[96];
  35 } secp256k1_keypair;
  36
  37 /** Parse a 32-byte sequence into a xonly_pubkey object.
  38  *
  39  *  Returns: 1 if the public key was fully valid.
  40  *           0 if the public key could not be parsed or is invalid.
  41  *
  42  *  Args:   ctx: a secp256k1 context object (cannot be NULL).
  43  *  Out: pubkey: pointer to a pubkey object. If 1 is returned, it is set to a
  44  *               parsed version of input. If not, it's set to an invalid value.
  45  *               (cannot be NULL).
  46  *  In: input32: pointer to a serialized xonly_pubkey (cannot be NULL)
  47  */
  48 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_parse(
  49     const secp256k1_context* ctx,
  50     secp256k1_xonly_pubkey* pubkey,
  51     const unsigned char *input32
  52 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
  53
  54 /** Serialize an xonly_pubkey object into a 32-byte sequence.
  55  *
  56  *  Returns: 1 always.
  57  *
  58  *  Args:     ctx: a secp256k1 context object (cannot be NULL).
  59  *  Out: output32: a pointer to a 32-byte array to place the serialized key in
  60  *                 (cannot be NULL).
  61  *  In:    pubkey: a pointer to a secp256k1_xonly_pubkey containing an
  62  *                 initialized public key (cannot be NULL).
  63  */
  64 SECP256K1_API int secp256k1_xonly_pubkey_serialize(
  65     const secp256k1_context* ctx,
  66     unsigned char *output32,
  67     const secp256k1_xonly_pubkey* pubkey
  68 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
  69
  70 /** Converts a secp256k1_pubkey into a secp256k1_xonly_pubkey.
  71  *
  72  *  Returns: 1 if the public key was successfully converted
  73  *           0 otherwise
  74  *
  75  *  Args:         ctx: pointer to a context object (cannot be NULL)
  76  *  Out: xonly_pubkey: pointer to an x-only public key object for placing the
  77  *                     converted public key (cannot be NULL)
  78  *          pk_parity: pointer to an integer that will be set to 1 if the point
  79  *                     encoded by xonly_pubkey is the negation of the pubkey and
  80  *                     set to 0 otherwise. (can be NULL)
  81  *  In:        pubkey: pointer to a public key that is converted (cannot be NULL)
  82  */
  83 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_from_pubkey(
  84     const secp256k1_context* ctx,
  85     secp256k1_xonly_pubkey *xonly_pubkey,
  86     int *pk_parity,
  87     const secp256k1_pubkey *pubkey
  88 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(4);
  89
  90 /** Tweak an x-only public key by adding the generator multiplied with tweak32
  91  *  to it.
  92  *
  93  *  Note that the resulting point can not in general be represented by an x-only
  94  *  pubkey because it may have an odd Y coordinate. Instead, the output_pubkey
  95  *  is a normal secp256k1_pubkey.
  96  *
  97  *  Returns: 0 if the arguments are invalid or the resulting public key would be
  98  *           invalid (only when the tweak is the negation of the corresponding
  99  *           secret key). 1 otherwise.
 100  *
 101  *  Args:           ctx: pointer to a context object initialized for verification
 102  *                       (cannot be NULL)
 103  *  Out:  output_pubkey: pointer to a public key to store the result. Will be set
 104  *                       to an invalid value if this function returns 0 (cannot
 105  *                       be NULL)
 106  *  In: internal_pubkey: pointer to an x-only pubkey to apply the tweak to.
 107  *                       (cannot be NULL).
 108  *              tweak32: pointer to a 32-byte tweak. If the tweak is invalid
 109  *                       according to secp256k1_ec_seckey_verify, this function
 110  *                       returns 0. For uniformly random 32-byte arrays the
 111  *                       chance of being invalid is negligible (around 1 in
 112  *                       2^128) (cannot be NULL).
 113  */
 114 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_tweak_add(
 115     const secp256k1_context* ctx,
 116     secp256k1_pubkey *output_pubkey,
 117     const secp256k1_xonly_pubkey *internal_pubkey,
 118     const unsigned char *tweak32
 119 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 120
 121 /** Checks that a tweaked pubkey is the result of calling
 122  *  secp256k1_xonly_pubkey_tweak_add with internal_pubkey and tweak32.
 123  *
 124  *  The tweaked pubkey is represented by its 32-byte x-only serialization and
 125  *  its pk_parity, which can both be obtained by converting the result of
 126  *  tweak_add to a secp256k1_xonly_pubkey.
 127  *
 128  *  Note that this alone does _not_ verify that the tweaked pubkey is a
 129  *  commitment. If the tweak is not chosen in a specific way, the tweaked pubkey
 130  *  can easily be the result of a different internal_pubkey and tweak.
 131  *
 132  *  Returns: 0 if the arguments are invalid or the tweaked pubkey is not the
 133  *           result of tweaking the internal_pubkey with tweak32. 1 otherwise.
 134  *  Args:            ctx: pointer to a context object initialized for verification
 135  *                       (cannot be NULL)
 136  *  In: tweaked_pubkey32: pointer to a serialized xonly_pubkey (cannot be NULL)
 137  *     tweaked_pk_parity: the parity of the tweaked pubkey (whose serialization
 138  *                        is passed in as tweaked_pubkey32). This must match the
 139  *                        pk_parity value that is returned when calling
 140  *                        secp256k1_xonly_pubkey with the tweaked pubkey, or
 141  *                        this function will fail.
 142  *       internal_pubkey: pointer to an x-only public key object to apply the
 143  *                        tweak to (cannot be NULL)
 144  *               tweak32: pointer to a 32-byte tweak (cannot be NULL)
 145  */
 146 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_tweak_add_check(
 147     const secp256k1_context* ctx,
 148     const unsigned char *tweaked_pubkey32,
 149     int tweaked_pk_parity,
 150     const secp256k1_xonly_pubkey *internal_pubkey,
 151     const unsigned char *tweak32
 152 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(4) SECP256K1_ARG_NONNULL(5);
 153
 154 /** Compute the keypair for a secret key.
 155  *
 156  *  Returns: 1: secret was valid, keypair is ready to use
 157  *           0: secret was invalid, try again with a different secret
 158  *  Args:    ctx: pointer to a context object, initialized for signing (cannot be NULL)
 159  *  Out: keypair: pointer to the created keypair (cannot be NULL)
 160  *  In:   seckey: pointer to a 32-byte secret key (cannot be NULL)
 161  */
 162 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_create(
 163     const secp256k1_context* ctx,
 164     secp256k1_keypair *keypair,
 165     const unsigned char *seckey
 166 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 167
 168 /** Get the public key from a keypair.
 169  *
 170  *  Returns: 0 if the arguments are invalid. 1 otherwise.
 171  *  Args:    ctx: pointer to a context object (cannot be NULL)
 172  *  Out: pubkey: pointer to a pubkey object. If 1 is returned, it is set to
 173  *               the keypair public key. If not, it's set to an invalid value.
 174  *               (cannot be NULL)
 175  *  In: keypair: pointer to a keypair (cannot be NULL)
 176  */
 177 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_pub(
 178     const secp256k1_context* ctx,
 179     secp256k1_pubkey *pubkey,
 180     const secp256k1_keypair *keypair
 181 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 182
 183 /** Get the x-only public key from a keypair.
 184  *
 185  *  This is the same as calling secp256k1_keypair_pub and then
 186  *  secp256k1_xonly_pubkey_from_pubkey.
 187  *
 188  *  Returns: 0 if the arguments are invalid. 1 otherwise.
 189  *  Args:   ctx: pointer to a context object (cannot be NULL)
 190  *  Out: pubkey: pointer to an xonly_pubkey object. If 1 is returned, it is set
 191  *               to the keypair public key after converting it to an
 192  *               xonly_pubkey. If not, it's set to an invalid value (cannot be
 193  *               NULL).
 194  *    pk_parity: pointer to an integer that will be set to the pk_parity
 195  *               argument of secp256k1_xonly_pubkey_from_pubkey (can be NULL).
 196  *  In: keypair: pointer to a keypair (cannot be NULL)
 197  */
 198 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_xonly_pub(
 199     const secp256k1_context* ctx,
 200     secp256k1_xonly_pubkey *pubkey,
 201     int *pk_parity,
 202     const secp256k1_keypair *keypair
 203 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(4);
 204
 205 /** Tweak a keypair by adding tweak32 to the secret key and updating the public
 206  *  key accordingly.
 207  *
 208  *  Calling this function and then secp256k1_keypair_pub results in the same
 209  *  public key as calling secp256k1_keypair_xonly_pub and then
 210  *  secp256k1_xonly_pubkey_tweak_add.
 211  *
 212  *  Returns: 0 if the arguments are invalid or the resulting keypair would be
 213  *           invalid (only when the tweak is the negation of the keypair's
 214  *           secret key). 1 otherwise.
 215  *
 216  *  Args:       ctx: pointer to a context object initialized for verification
 217  *                   (cannot be NULL)
 218  *  In/Out: keypair: pointer to a keypair to apply the tweak to. Will be set to
 219  *                   an invalid value if this function returns 0 (cannot be
 220  *                   NULL).
 221  *  In:     tweak32: pointer to a 32-byte tweak. If the tweak is invalid according
 222  *                   to secp256k1_ec_seckey_verify, this function returns 0. For
 223  *                   uniformly random 32-byte arrays the chance of being invalid
 224  *                   is negligible (around 1 in 2^128) (cannot be NULL).
 225  */
 226 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_xonly_tweak_add(
 227     const secp256k1_context* ctx,
 228     secp256k1_keypair *keypair,
 229     const unsigned char *tweak32
 230 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 231
 232 #ifdef __cplusplus
 233 }
 234 #endif
 235
 236 #endif /* SECP256K1_EXTRAKEYS_H */