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 /** Parse a 32-byte sequence into a xonly_pubkey object.
  27  *
  28  *  Returns: 1 if the public key was fully valid.
  29  *           0 if the public key could not be parsed or is invalid.
  30  *
  31  *  Args:   ctx: a secp256k1 context object (cannot be NULL).
  32  *  Out: pubkey: pointer to a pubkey object. If 1 is returned, it is set to a
  33  *               parsed version of input. If not, it's set to an invalid value.
  34  *               (cannot be NULL).
  35  *  In: input32: pointer to a serialized xonly_pubkey (cannot be NULL)
  36  */
  37 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_parse(
  38     const secp256k1_context* ctx,
  39     secp256k1_xonly_pubkey* pubkey,
  40     const unsigned char *input32
  41 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
  42
  43 /** Serialize an xonly_pubkey object into a 32-byte sequence.
  44  *
  45  *  Returns: 1 always.
  46  *
  47  *  Args:     ctx: a secp256k1 context object (cannot be NULL).
  48  *  Out: output32: a pointer to a 32-byte array to place the serialized key in
  49  *                 (cannot be NULL).
  50  *  In:    pubkey: a pointer to a secp256k1_xonly_pubkey containing an
  51  *                 initialized public key (cannot be NULL).
  52  */
  53 SECP256K1_API int secp256k1_xonly_pubkey_serialize(
  54     const secp256k1_context* ctx,
  55     unsigned char *output32,
  56     const secp256k1_xonly_pubkey* pubkey
  57 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
  58
  59 /** Converts a secp256k1_pubkey into a secp256k1_xonly_pubkey.
  60  *
  61  *  Returns: 1 if the public key was successfully converted
  62  *           0 otherwise
  63  *
  64  *  Args:         ctx: pointer to a context object (cannot be NULL)
  65  *  Out: xonly_pubkey: pointer to an x-only public key object for placing the
  66  *                     converted public key (cannot be NULL)
  67  *          pk_parity: pointer to an integer that will be set to 1 if the point
  68  *                     encoded by xonly_pubkey is the negation of the pubkey and
  69  *                     set to 0 otherwise. (can be NULL)
  70  *  In:        pubkey: pointer to a public key that is converted (cannot be NULL)
  71  */
  72 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_from_pubkey(
  73     const secp256k1_context* ctx,
  74     secp256k1_xonly_pubkey *xonly_pubkey,
  75     int *pk_parity,
  76     const secp256k1_pubkey *pubkey
  77 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(4);
  78
  79 /** Tweak an x-only public key by adding the generator multiplied with tweak32
  80  *  to it.
  81  *
  82  *  Note that the resulting point can not in general be represented by an x-only
  83  *  pubkey because it may have an odd Y coordinate. Instead, the output_pubkey
  84  *  is a normal secp256k1_pubkey.
  85  *
  86  *  Returns: 0 if the arguments are invalid or the resulting public key would be
  87  *           invalid (only when the tweak is the negation of the corresponding
  88  *           secret key). 1 otherwise.
  89  *
  90  *  Args:           ctx: pointer to a context object initialized for verification
  91  *                       (cannot be NULL)
  92  *  Out:  output_pubkey: pointer to a public key to store the result. Will be set
  93  *                       to an invalid value if this function returns 0 (cannot
  94  *                       be NULL)
  95  *  In: internal_pubkey: pointer to an x-only pubkey to apply the tweak to.
  96  *                       (cannot be NULL).
  97  *              tweak32: pointer to a 32-byte tweak. If the tweak is invalid
  98  *                       according to secp256k1_ec_seckey_verify, this function
  99  *                       returns 0. For uniformly random 32-byte arrays the
 100  *                       chance of being invalid is negligible (around 1 in
 101  *                       2^128) (cannot be NULL).
 102  */
 103 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_tweak_add(
 104     const secp256k1_context* ctx,
 105     secp256k1_pubkey *output_pubkey,
 106     const secp256k1_xonly_pubkey *internal_pubkey,
 107     const unsigned char *tweak32
 108 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 109
 110 /** Checks that a tweaked pubkey is the result of calling
 111  *  secp256k1_xonly_pubkey_tweak_add with internal_pubkey and tweak32.
 112  *
 113  *  The tweaked pubkey is represented by its 32-byte x-only serialization and
 114  *  its pk_parity, which can both be obtained by converting the result of
 115  *  tweak_add to a secp256k1_xonly_pubkey.
 116  *
 117  *  Note that this alone does _not_ verify that the tweaked pubkey is a
 118  *  commitment. If the tweak is not chosen in a specific way, the tweaked pubkey
 119  *  can easily be the result of a different internal_pubkey and tweak.
 120  *
 121  *  Returns: 0 if the arguments are invalid or the tweaked pubkey is not the
 122  *           result of tweaking the internal_pubkey with tweak32. 1 otherwise.
 123  *  Args:            ctx: pointer to a context object initialized for verification
 124  *                       (cannot be NULL)
 125  *  In: tweaked_pubkey32: pointer to a serialized xonly_pubkey (cannot be NULL)
 126  *     tweaked_pk_parity: the parity of the tweaked pubkey (whose serialization
 127  *                        is passed in as tweaked_pubkey32). This must match the
 128  *                        pk_parity value that is returned when calling
 129  *                        secp256k1_xonly_pubkey with the tweaked pubkey, or
 130  *                        this function will fail.
 131  *       internal_pubkey: pointer to an x-only public key object to apply the
 132  *                        tweak to (cannot be NULL)
 133  *               tweak32: pointer to a 32-byte tweak (cannot be NULL)
 134  */
 135 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_tweak_add_check(
 136     const secp256k1_context* ctx,
 137     const unsigned char *tweaked_pubkey32,
 138     int tweaked_pk_parity,
 139     const secp256k1_xonly_pubkey *internal_pubkey,
 140     const unsigned char *tweak32
 141 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(4) SECP256K1_ARG_NONNULL(5);
 142
 143 #ifdef __cplusplus
 144 }
 145 #endif
 146
 147 #endif /* SECP256K1_EXTRAKEYS_H */