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 secp256k1_xonly_pubkey {
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 secp256k1_keypair {
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: 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 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: 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 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: 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 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 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 valid secret key.
159 *
160 * See the documentation of `secp256k1_ec_seckey_verify` for more information
161 * about the validity of secret keys.
162 *
163 * Returns: 1: secret key is valid
164 * 0: secret key is invalid
165 * Args: ctx: pointer to a context object (not secp256k1_context_static).
166 * Out: keypair: pointer to the created keypair.
167 * In: seckey: pointer to a 32-byte secret key.
168 */
169 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_create(
170 const secp256k1_context *ctx,
171 secp256k1_keypair *keypair,
172 const unsigned char *seckey
173 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
174 175 /** Get the secret key from a keypair.
176 *
177 * Returns: 1 always.
178 * Args: ctx: pointer to a context object.
179 * Out: seckey: pointer to a 32-byte buffer for the secret key.
180 * In: keypair: pointer to a keypair.
181 */
182 SECP256K1_API int secp256k1_keypair_sec(
183 const secp256k1_context *ctx,
184 unsigned char *seckey,
185 const secp256k1_keypair *keypair
186 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
187 188 /** Get the public key from a keypair.
189 *
190 * Returns: 1 always.
191 * Args: ctx: pointer to a context object.
192 * Out: pubkey: pointer to a pubkey object, set to the keypair public key.
193 * In: keypair: pointer to a keypair.
194 */
195 SECP256K1_API int secp256k1_keypair_pub(
196 const secp256k1_context *ctx,
197 secp256k1_pubkey *pubkey,
198 const secp256k1_keypair *keypair
199 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
200 201 /** Get the x-only public key from a keypair.
202 *
203 * This is the same as calling secp256k1_keypair_pub and then
204 * secp256k1_xonly_pubkey_from_pubkey.
205 *
206 * Returns: 1 always.
207 * Args: ctx: pointer to a context object.
208 * Out: pubkey: pointer to an xonly_pubkey object, set to the keypair
209 * public key after converting it to an xonly_pubkey.
210 * pk_parity: Ignored if NULL. Otherwise, pointer to an integer that will be set to the
211 * pk_parity argument of secp256k1_xonly_pubkey_from_pubkey.
212 * In: keypair: pointer to a keypair.
213 */
214 SECP256K1_API int secp256k1_keypair_xonly_pub(
215 const secp256k1_context *ctx,
216 secp256k1_xonly_pubkey *pubkey,
217 int *pk_parity,
218 const secp256k1_keypair *keypair
219 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(4);
220 221 /** Tweak a keypair by adding tweak32 to the secret key and updating the public
222 * key accordingly.
223 *
224 * Calling this function and then secp256k1_keypair_pub results in the same
225 * public key as calling secp256k1_keypair_xonly_pub and then
226 * secp256k1_xonly_pubkey_tweak_add.
227 *
228 * Returns: 0 if the arguments are invalid or the resulting keypair would be
229 * invalid (only when the tweak is the negation of the keypair's
230 * secret key). 1 otherwise.
231 *
232 * Args: ctx: pointer to a context object.
233 * In/Out: keypair: pointer to a keypair to apply the tweak to. Will be set to
234 * an invalid value if this function returns 0.
235 * In: tweak32: pointer to a 32-byte tweak, which must be valid according to
236 * secp256k1_ec_seckey_verify or 32 zero bytes. For uniformly
237 * random 32-byte tweaks, the chance of being invalid is
238 * negligible (around 1 in 2^128).
239 */
240 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_keypair_xonly_tweak_add(
241 const secp256k1_context *ctx,
242 secp256k1_keypair *keypair,
243 const unsigned char *tweak32
244 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
245 246 #ifdef __cplusplus
247 }
248 #endif
249 250 #endif /* SECP256K1_EXTRAKEYS_H */
251