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_extrakeys.h (11698B)


      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, use
     19  *  use haskellsecp256k1_v0_1_0_xonly_pubkey_serialize and haskellsecp256k1_v0_1_0_xonly_pubkey_parse. To
     20  *  compare keys, use haskellsecp256k1_v0_1_0_xonly_pubkey_cmp.
     21  */
     22 typedef struct {
     23     unsigned char data[64];
     24 } haskellsecp256k1_v0_1_0_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 } haskellsecp256k1_v0_1_0_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: pointer to a context object.
     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  *  In: input32: pointer to a serialized xonly_pubkey.
     46  */
     47 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int haskellsecp256k1_v0_1_0_xonly_pubkey_parse(
     48     const haskellsecp256k1_v0_1_0_context *ctx,
     49     haskellsecp256k1_v0_1_0_xonly_pubkey *pubkey,
     50     const unsigned char *input32
     51 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
     52 
     53 /** Serialize an xonly_pubkey object into a 32-byte sequence.
     54  *
     55  *  Returns: 1 always.
     56  *
     57  *  Args:     ctx: pointer to a context object.
     58  *  Out: output32: pointer to a 32-byte array to place the serialized key in.
     59  *  In:    pubkey: pointer to a haskellsecp256k1_v0_1_0_xonly_pubkey containing an initialized public key.
     60  */
     61 SECP256K1_API int haskellsecp256k1_v0_1_0_xonly_pubkey_serialize(
     62     const haskellsecp256k1_v0_1_0_context *ctx,
     63     unsigned char *output32,
     64     const haskellsecp256k1_v0_1_0_xonly_pubkey *pubkey
     65 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
     66 
     67 /** Compare two x-only public keys using lexicographic order
     68  *
     69  *  Returns: <0 if the first public key is less than the second
     70  *           >0 if the first public key is greater than the second
     71  *           0 if the two public keys are equal
     72  *  Args: ctx:      pointer to a context object.
     73  *  In:   pubkey1:  first public key to compare
     74  *        pubkey2:  second public key to compare
     75  */
     76 SECP256K1_API int haskellsecp256k1_v0_1_0_xonly_pubkey_cmp(
     77     const haskellsecp256k1_v0_1_0_context *ctx,
     78     const haskellsecp256k1_v0_1_0_xonly_pubkey *pk1,
     79     const haskellsecp256k1_v0_1_0_xonly_pubkey *pk2
     80 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
     81 
     82 /** Converts a haskellsecp256k1_v0_1_0_pubkey into a haskellsecp256k1_v0_1_0_xonly_pubkey.
     83  *
     84  *  Returns: 1 always.
     85  *
     86  *  Args:         ctx: pointer to a context object.
     87  *  Out: xonly_pubkey: pointer to an x-only public key object for placing the converted public key.
     88  *          pk_parity: Ignored if NULL. Otherwise, pointer to an integer that
     89  *                     will be set to 1 if the point encoded by xonly_pubkey is
     90  *                     the negation of the pubkey and set to 0 otherwise.
     91  *  In:        pubkey: pointer to a public key that is converted.
     92  */
     93 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int haskellsecp256k1_v0_1_0_xonly_pubkey_from_pubkey(
     94     const haskellsecp256k1_v0_1_0_context *ctx,
     95     haskellsecp256k1_v0_1_0_xonly_pubkey *xonly_pubkey,
     96     int *pk_parity,
     97     const haskellsecp256k1_v0_1_0_pubkey *pubkey
     98 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(4);
     99 
    100 /** Tweak an x-only public key by adding the generator multiplied with tweak32
    101  *  to it.
    102  *
    103  *  Note that the resulting point can not in general be represented by an x-only
    104  *  pubkey because it may have an odd Y coordinate. Instead, the output_pubkey
    105  *  is a normal haskellsecp256k1_v0_1_0_pubkey.
    106  *
    107  *  Returns: 0 if the arguments are invalid or the resulting public key would be
    108  *           invalid (only when the tweak is the negation of the corresponding
    109  *           secret key). 1 otherwise.
    110  *
    111  *  Args:           ctx: pointer to a context object.
    112  *  Out:  output_pubkey: pointer to a public key to store the result. Will be set
    113  *                       to an invalid value if this function returns 0.
    114  *  In: internal_pubkey: pointer to an x-only pubkey to apply the tweak to.
    115  *              tweak32: pointer to a 32-byte tweak, which must be valid
    116  *                       according to haskellsecp256k1_v0_1_0_ec_seckey_verify or 32 zero
    117  *                       bytes. For uniformly random 32-byte tweaks, the chance of
    118  *                       being invalid is negligible (around 1 in 2^128).
    119  */
    120 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int haskellsecp256k1_v0_1_0_xonly_pubkey_tweak_add(
    121     const haskellsecp256k1_v0_1_0_context *ctx,
    122     haskellsecp256k1_v0_1_0_pubkey *output_pubkey,
    123     const haskellsecp256k1_v0_1_0_xonly_pubkey *internal_pubkey,
    124     const unsigned char *tweak32
    125 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
    126 
    127 /** Checks that a tweaked pubkey is the result of calling
    128  *  haskellsecp256k1_v0_1_0_xonly_pubkey_tweak_add with internal_pubkey and tweak32.
    129  *
    130  *  The tweaked pubkey is represented by its 32-byte x-only serialization and
    131  *  its pk_parity, which can both be obtained by converting the result of
    132  *  tweak_add to a haskellsecp256k1_v0_1_0_xonly_pubkey.
    133  *
    134  *  Note that this alone does _not_ verify that the tweaked pubkey is a
    135  *  commitment. If the tweak is not chosen in a specific way, the tweaked pubkey
    136  *  can easily be the result of a different internal_pubkey and tweak.
    137  *
    138  *  Returns: 0 if the arguments are invalid or the tweaked pubkey is not the
    139  *           result of tweaking the internal_pubkey with tweak32. 1 otherwise.
    140  *  Args:            ctx: pointer to a context object.
    141  *  In: tweaked_pubkey32: pointer to a serialized xonly_pubkey.
    142  *     tweaked_pk_parity: the parity of the tweaked pubkey (whose serialization
    143  *                        is passed in as tweaked_pubkey32). This must match the
    144  *                        pk_parity value that is returned when calling
    145  *                        haskellsecp256k1_v0_1_0_xonly_pubkey with the tweaked pubkey, or
    146  *                        this function will fail.
    147  *       internal_pubkey: pointer to an x-only public key object to apply the tweak to.
    148  *               tweak32: pointer to a 32-byte tweak.
    149  */
    150 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int haskellsecp256k1_v0_1_0_xonly_pubkey_tweak_add_check(
    151     const haskellsecp256k1_v0_1_0_context *ctx,
    152     const unsigned char *tweaked_pubkey32,
    153     int tweaked_pk_parity,
    154     const haskellsecp256k1_v0_1_0_xonly_pubkey *internal_pubkey,
    155     const unsigned char *tweak32
    156 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(4) SECP256K1_ARG_NONNULL(5);
    157 
    158 /** Compute the keypair for a secret key.
    159  *
    160  *  Returns: 1: secret was valid, keypair is ready to use
    161  *           0: secret was invalid, try again with a different secret
    162  *  Args:    ctx: pointer to a context object (not haskellsecp256k1_v0_1_0_context_static).
    163  *  Out: keypair: pointer to the created keypair.
    164  *  In:   seckey: pointer to a 32-byte secret key.
    165  */
    166 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int haskellsecp256k1_v0_1_0_keypair_create(
    167     const haskellsecp256k1_v0_1_0_context *ctx,
    168     haskellsecp256k1_v0_1_0_keypair *keypair,
    169     const unsigned char *seckey
    170 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
    171 
    172 /** Get the secret key from a keypair.
    173  *
    174  *  Returns: 1 always.
    175  *  Args:   ctx: pointer to a context object.
    176  *  Out: seckey: pointer to a 32-byte buffer for the secret key.
    177  *  In: keypair: pointer to a keypair.
    178  */
    179 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int haskellsecp256k1_v0_1_0_keypair_sec(
    180     const haskellsecp256k1_v0_1_0_context *ctx,
    181     unsigned char *seckey,
    182     const haskellsecp256k1_v0_1_0_keypair *keypair
    183 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
    184 
    185 /** Get the public key from a keypair.
    186  *
    187  *  Returns: 1 always.
    188  *  Args:   ctx: pointer to a context object.
    189  *  Out: pubkey: pointer to a pubkey object, set to the keypair public key.
    190  *  In: keypair: pointer to a keypair.
    191  */
    192 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int haskellsecp256k1_v0_1_0_keypair_pub(
    193     const haskellsecp256k1_v0_1_0_context *ctx,
    194     haskellsecp256k1_v0_1_0_pubkey *pubkey,
    195     const haskellsecp256k1_v0_1_0_keypair *keypair
    196 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
    197 
    198 /** Get the x-only public key from a keypair.
    199  *
    200  *  This is the same as calling haskellsecp256k1_v0_1_0_keypair_pub and then
    201  *  haskellsecp256k1_v0_1_0_xonly_pubkey_from_pubkey.
    202  *
    203  *  Returns: 1 always.
    204  *  Args:   ctx: pointer to a context object.
    205  *  Out: pubkey: pointer to an xonly_pubkey object, set to the keypair
    206  *               public key after converting it to an xonly_pubkey.
    207  *    pk_parity: Ignored if NULL. Otherwise, pointer to an integer that will be set to the
    208  *               pk_parity argument of haskellsecp256k1_v0_1_0_xonly_pubkey_from_pubkey.
    209  *  In: keypair: pointer to a keypair.
    210  */
    211 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int haskellsecp256k1_v0_1_0_keypair_xonly_pub(
    212     const haskellsecp256k1_v0_1_0_context *ctx,
    213     haskellsecp256k1_v0_1_0_xonly_pubkey *pubkey,
    214     int *pk_parity,
    215     const haskellsecp256k1_v0_1_0_keypair *keypair
    216 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(4);
    217 
    218 /** Tweak a keypair by adding tweak32 to the secret key and updating the public
    219  *  key accordingly.
    220  *
    221  *  Calling this function and then haskellsecp256k1_v0_1_0_keypair_pub results in the same
    222  *  public key as calling haskellsecp256k1_v0_1_0_keypair_xonly_pub and then
    223  *  haskellsecp256k1_v0_1_0_xonly_pubkey_tweak_add.
    224  *
    225  *  Returns: 0 if the arguments are invalid or the resulting keypair would be
    226  *           invalid (only when the tweak is the negation of the keypair's
    227  *           secret key). 1 otherwise.
    228  *
    229  *  Args:       ctx: pointer to a context object.
    230  *  In/Out: keypair: pointer to a keypair to apply the tweak to. Will be set to
    231  *                   an invalid value if this function returns 0.
    232  *  In:     tweak32: pointer to a 32-byte tweak, which must be valid according to
    233  *                   haskellsecp256k1_v0_1_0_ec_seckey_verify or 32 zero bytes. For uniformly
    234  *                   random 32-byte tweaks, the chance of being invalid is
    235  *                   negligible (around 1 in 2^128).
    236  */
    237 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int haskellsecp256k1_v0_1_0_keypair_xonly_tweak_add(
    238     const haskellsecp256k1_v0_1_0_context *ctx,
    239     haskellsecp256k1_v0_1_0_keypair *keypair,
    240     const unsigned char *tweak32
    241 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
    242 
    243 #ifdef __cplusplus
    244 }
    245 #endif
    246 
    247 #endif /* SECP256K1_EXTRAKEYS_H */