secp256k1_extrakeys.h (10873B)
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 secp256k1_xonly_pubkey_serialize and secp256k1_xonly_pubkey_parse. To 20 * compare keys, use secp256k1_xonly_pubkey_cmp. 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. 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 secp256k1_xonly_pubkey_parse( 48 const secp256k1_context *ctx, 49 secp256k1_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: a secp256k1 context object. 58 * Out: output32: a pointer to a 32-byte array to place the serialized key in. 59 * In: pubkey: a pointer to a secp256k1_xonly_pubkey containing an initialized public key. 60 */ 61 SECP256K1_API int secp256k1_xonly_pubkey_serialize( 62 const secp256k1_context *ctx, 63 unsigned char *output32, 64 const secp256k1_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: a secp256k1 context object. 73 * In: pubkey1: first public key to compare 74 * pubkey2: second public key to compare 75 */ 76 SECP256K1_API int secp256k1_xonly_pubkey_cmp( 77 const secp256k1_context *ctx, 78 const secp256k1_xonly_pubkey *pk1, 79 const secp256k1_xonly_pubkey *pk2 80 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); 81 82 /** Converts a secp256k1_pubkey into a secp256k1_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 secp256k1_xonly_pubkey_from_pubkey( 94 const secp256k1_context *ctx, 95 secp256k1_xonly_pubkey *xonly_pubkey, 96 int *pk_parity, 97 const secp256k1_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 secp256k1_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 secp256k1_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 secp256k1_xonly_pubkey_tweak_add( 121 const secp256k1_context *ctx, 122 secp256k1_pubkey *output_pubkey, 123 const secp256k1_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 * secp256k1_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 secp256k1_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 * secp256k1_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 secp256k1_xonly_pubkey_tweak_add_check( 151 const secp256k1_context *ctx, 152 const unsigned char *tweaked_pubkey32, 153 int tweaked_pk_parity, 154 const secp256k1_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 secp256k1_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 secp256k1_keypair_create( 167 const secp256k1_context *ctx, 168 secp256k1_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 secp256k1_keypair_sec( 180 const secp256k1_context *ctx, 181 unsigned char *seckey, 182 const secp256k1_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 secp256k1_keypair_pub( 193 const secp256k1_context *ctx, 194 secp256k1_pubkey *pubkey, 195 const secp256k1_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 secp256k1_keypair_pub and then 201 * secp256k1_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 secp256k1_xonly_pubkey_from_pubkey. 209 * In: keypair: pointer to a keypair. 210 */ 211 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_xonly_pub( 212 const secp256k1_context *ctx, 213 secp256k1_xonly_pubkey *pubkey, 214 int *pk_parity, 215 const secp256k1_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 secp256k1_keypair_pub results in the same 222 * public key as calling secp256k1_keypair_xonly_pub and then 223 * secp256k1_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 * secp256k1_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 secp256k1_keypair_xonly_tweak_add( 238 const secp256k1_context *ctx, 239 secp256k1_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 */