secp256k1.h (42619B)
1 #ifndef SECP256K1_H 2 #define SECP256K1_H 3 4 #ifdef __cplusplus 5 extern "C" { 6 #endif 7 8 #include <stddef.h> 9 10 /** Unless explicitly stated all pointer arguments must not be NULL. 11 * 12 * The following rules specify the order of arguments in API calls: 13 * 14 * 1. Context pointers go first, followed by output arguments, combined 15 * output/input arguments, and finally input-only arguments. 16 * 2. Array lengths always immediately follow the argument whose length 17 * they describe, even if this violates rule 1. 18 * 3. Within the OUT/OUTIN/IN groups, pointers to data that is typically generated 19 * later go first. This means: signatures, public nonces, secret nonces, 20 * messages, public keys, secret keys, tweaks. 21 * 4. Arguments that are not data pointers go last, from more complex to less 22 * complex: function pointers, algorithm names, messages, void pointers, 23 * counts, flags, booleans. 24 * 5. Opaque data pointers follow the function pointer they are to be passed to. 25 */ 26 27 /** Opaque data structure that holds context information 28 * 29 * The primary purpose of context objects is to store randomization data for 30 * enhanced protection against side-channel leakage. This protection is only 31 * effective if the context is randomized after its creation. See 32 * secp256k1_context_create for creation of contexts and 33 * secp256k1_context_randomize for randomization. 34 * 35 * A secondary purpose of context objects is to store pointers to callback 36 * functions that the library will call when certain error states arise. See 37 * secp256k1_context_set_error_callback as well as 38 * secp256k1_context_set_illegal_callback for details. Future library versions 39 * may use context objects for additional purposes. 40 * 41 * A constructed context can safely be used from multiple threads 42 * simultaneously, but API calls that take a non-const pointer to a context 43 * need exclusive access to it. In particular this is the case for 44 * secp256k1_context_destroy, secp256k1_context_preallocated_destroy, 45 * and secp256k1_context_randomize. 46 * 47 * Regarding randomization, either do it once at creation time (in which case 48 * you do not need any locking for the other calls), or use a read-write lock. 49 */ 50 typedef struct secp256k1_context_struct secp256k1_context; 51 52 /** Opaque data structure that holds rewritable "scratch space" 53 * 54 * The purpose of this structure is to replace dynamic memory allocations, 55 * because we target architectures where this may not be available. It is 56 * essentially a resizable (within specified parameters) block of bytes, 57 * which is initially created either by memory allocation or TODO as a pointer 58 * into some fixed rewritable space. 59 * 60 * Unlike the context object, this cannot safely be shared between threads 61 * without additional synchronization logic. 62 */ 63 typedef struct secp256k1_scratch_space_struct secp256k1_scratch_space; 64 65 /** Opaque data structure that holds a parsed and valid public key. 66 * 67 * The exact representation of data inside is implementation defined and not 68 * guaranteed to be portable between different platforms or versions. It is 69 * however guaranteed to be 64 bytes in size, and can be safely copied/moved. 70 * If you need to convert to a format suitable for storage or transmission, 71 * use secp256k1_ec_pubkey_serialize and secp256k1_ec_pubkey_parse. To 72 * compare keys, use secp256k1_ec_pubkey_cmp. 73 */ 74 typedef struct { 75 unsigned char data[64]; 76 } secp256k1_pubkey; 77 78 /** Opaque data structured that holds a parsed ECDSA signature. 79 * 80 * The exact representation of data inside is implementation defined and not 81 * guaranteed to be portable between different platforms or versions. It is 82 * however guaranteed to be 64 bytes in size, and can be safely copied/moved. 83 * If you need to convert to a format suitable for storage, transmission, or 84 * comparison, use the secp256k1_ecdsa_signature_serialize_* and 85 * secp256k1_ecdsa_signature_parse_* functions. 86 */ 87 typedef struct { 88 unsigned char data[64]; 89 } secp256k1_ecdsa_signature; 90 91 /** A pointer to a function to deterministically generate a nonce. 92 * 93 * Returns: 1 if a nonce was successfully generated. 0 will cause signing to fail. 94 * Out: nonce32: pointer to a 32-byte array to be filled by the function. 95 * In: msg32: the 32-byte message hash being verified (will not be NULL) 96 * key32: pointer to a 32-byte secret key (will not be NULL) 97 * algo16: pointer to a 16-byte array describing the signature 98 * algorithm (will be NULL for ECDSA for compatibility). 99 * data: Arbitrary data pointer that is passed through. 100 * attempt: how many iterations we have tried to find a nonce. 101 * This will almost always be 0, but different attempt values 102 * are required to result in a different nonce. 103 * 104 * Except for test cases, this function should compute some cryptographic hash of 105 * the message, the algorithm, the key and the attempt. 106 */ 107 typedef int (*secp256k1_nonce_function)( 108 unsigned char *nonce32, 109 const unsigned char *msg32, 110 const unsigned char *key32, 111 const unsigned char *algo16, 112 void *data, 113 unsigned int attempt 114 ); 115 116 # if !defined(SECP256K1_GNUC_PREREQ) 117 # if defined(__GNUC__)&&defined(__GNUC_MINOR__) 118 # define SECP256K1_GNUC_PREREQ(_maj,_min) \ 119 ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min)) 120 # else 121 # define SECP256K1_GNUC_PREREQ(_maj,_min) 0 122 # endif 123 # endif 124 125 /* When this header is used at build-time the SECP256K1_BUILD define needs to be set 126 * to correctly setup export attributes and nullness checks. This is normally done 127 * by secp256k1.c but to guard against this header being included before secp256k1.c 128 * has had a chance to set the define (e.g. via test harnesses that just includes 129 * secp256k1.c) we set SECP256K1_NO_BUILD when this header is processed without the 130 * BUILD define so this condition can be caught. 131 */ 132 #ifndef SECP256K1_BUILD 133 # define SECP256K1_NO_BUILD 134 #endif 135 136 /* Symbol visibility. */ 137 #if defined(_WIN32) 138 /* GCC for Windows (e.g., MinGW) accepts the __declspec syntax 139 * for MSVC compatibility. A __declspec declaration implies (but is not 140 * exactly equivalent to) __attribute__ ((visibility("default"))), and so we 141 * actually want __declspec even on GCC, see "Microsoft Windows Function 142 * Attributes" in the GCC manual and the recommendations in 143 * https://gcc.gnu.org/wiki/Visibility. */ 144 # if defined(SECP256K1_BUILD) 145 # if defined(DLL_EXPORT) || defined(SECP256K1_DLL_EXPORT) 146 /* Building libsecp256k1 as a DLL. 147 * 1. If using Libtool, it defines DLL_EXPORT automatically. 148 * 2. In other cases, SECP256K1_DLL_EXPORT must be defined. */ 149 # define SECP256K1_API extern __declspec (dllexport) 150 # endif 151 /* The user must define SECP256K1_STATIC when consuming libsecp256k1 as a static 152 * library on Windows. */ 153 # elif !defined(SECP256K1_STATIC) 154 /* Consuming libsecp256k1 as a DLL. */ 155 # define SECP256K1_API extern __declspec (dllimport) 156 # endif 157 #endif 158 #ifndef SECP256K1_API 159 # if defined(__GNUC__) && (__GNUC__ >= 4) && defined(SECP256K1_BUILD) 160 /* Building libsecp256k1 on non-Windows using GCC or compatible. */ 161 # define SECP256K1_API extern __attribute__ ((visibility ("default"))) 162 # else 163 /* All cases not captured above. */ 164 # define SECP256K1_API extern 165 # endif 166 #endif 167 168 /* Warning attributes 169 * NONNULL is not used if SECP256K1_BUILD is set to avoid the compiler optimizing out 170 * some paranoid null checks. */ 171 # if defined(__GNUC__) && SECP256K1_GNUC_PREREQ(3, 4) 172 # define SECP256K1_WARN_UNUSED_RESULT __attribute__ ((__warn_unused_result__)) 173 # else 174 # define SECP256K1_WARN_UNUSED_RESULT 175 # endif 176 # if !defined(SECP256K1_BUILD) && defined(__GNUC__) && SECP256K1_GNUC_PREREQ(3, 4) 177 # define SECP256K1_ARG_NONNULL(_x) __attribute__ ((__nonnull__(_x))) 178 # else 179 # define SECP256K1_ARG_NONNULL(_x) 180 # endif 181 182 /* Attribute for marking functions, types, and variables as deprecated */ 183 #if !defined(SECP256K1_BUILD) && defined(__has_attribute) 184 # if __has_attribute(__deprecated__) 185 # define SECP256K1_DEPRECATED(_msg) __attribute__ ((__deprecated__(_msg))) 186 # else 187 # define SECP256K1_DEPRECATED(_msg) 188 # endif 189 #else 190 # define SECP256K1_DEPRECATED(_msg) 191 #endif 192 193 /* All flags' lower 8 bits indicate what they're for. Do not use directly. */ 194 #define SECP256K1_FLAGS_TYPE_MASK ((1 << 8) - 1) 195 #define SECP256K1_FLAGS_TYPE_CONTEXT (1 << 0) 196 #define SECP256K1_FLAGS_TYPE_COMPRESSION (1 << 1) 197 /* The higher bits contain the actual data. Do not use directly. */ 198 #define SECP256K1_FLAGS_BIT_CONTEXT_VERIFY (1 << 8) 199 #define SECP256K1_FLAGS_BIT_CONTEXT_SIGN (1 << 9) 200 #define SECP256K1_FLAGS_BIT_CONTEXT_DECLASSIFY (1 << 10) 201 #define SECP256K1_FLAGS_BIT_COMPRESSION (1 << 8) 202 203 /** Context flags to pass to secp256k1_context_create, secp256k1_context_preallocated_size, and 204 * secp256k1_context_preallocated_create. */ 205 #define SECP256K1_CONTEXT_NONE (SECP256K1_FLAGS_TYPE_CONTEXT) 206 207 /** Deprecated context flags. These flags are treated equivalent to SECP256K1_CONTEXT_NONE. */ 208 #define SECP256K1_CONTEXT_VERIFY (SECP256K1_FLAGS_TYPE_CONTEXT | SECP256K1_FLAGS_BIT_CONTEXT_VERIFY) 209 #define SECP256K1_CONTEXT_SIGN (SECP256K1_FLAGS_TYPE_CONTEXT | SECP256K1_FLAGS_BIT_CONTEXT_SIGN) 210 211 /* Testing flag. Do not use. */ 212 #define SECP256K1_CONTEXT_DECLASSIFY (SECP256K1_FLAGS_TYPE_CONTEXT | SECP256K1_FLAGS_BIT_CONTEXT_DECLASSIFY) 213 214 /** Flag to pass to secp256k1_ec_pubkey_serialize. */ 215 #define SECP256K1_EC_COMPRESSED (SECP256K1_FLAGS_TYPE_COMPRESSION | SECP256K1_FLAGS_BIT_COMPRESSION) 216 #define SECP256K1_EC_UNCOMPRESSED (SECP256K1_FLAGS_TYPE_COMPRESSION) 217 218 /** Prefix byte used to tag various encoded curvepoints for specific purposes */ 219 #define SECP256K1_TAG_PUBKEY_EVEN 0x02 220 #define SECP256K1_TAG_PUBKEY_ODD 0x03 221 #define SECP256K1_TAG_PUBKEY_UNCOMPRESSED 0x04 222 #define SECP256K1_TAG_PUBKEY_HYBRID_EVEN 0x06 223 #define SECP256K1_TAG_PUBKEY_HYBRID_ODD 0x07 224 225 /** A built-in constant secp256k1 context object with static storage duration, to be 226 * used in conjunction with secp256k1_selftest. 227 * 228 * This context object offers *only limited functionality* , i.e., it cannot be used 229 * for API functions that perform computations involving secret keys, e.g., signing 230 * and public key generation. If this restriction applies to a specific API function, 231 * it is mentioned in its documentation. See secp256k1_context_create if you need a 232 * full context object that supports all functionality offered by the library. 233 * 234 * It is highly recommended to call secp256k1_selftest before using this context. 235 */ 236 SECP256K1_API const secp256k1_context *secp256k1_context_static; 237 238 /** Deprecated alias for secp256k1_context_static. */ 239 SECP256K1_API const secp256k1_context *secp256k1_context_no_precomp 240 SECP256K1_DEPRECATED("Use secp256k1_context_static instead"); 241 242 /** Perform basic self tests (to be used in conjunction with secp256k1_context_static) 243 * 244 * This function performs self tests that detect some serious usage errors and 245 * similar conditions, e.g., when the library is compiled for the wrong endianness. 246 * This is a last resort measure to be used in production. The performed tests are 247 * very rudimentary and are not intended as a replacement for running the test 248 * binaries. 249 * 250 * It is highly recommended to call this before using secp256k1_context_static. 251 * It is not necessary to call this function before using a context created with 252 * secp256k1_context_create (or secp256k1_context_preallocated_create), which will 253 * take care of performing the self tests. 254 * 255 * If the tests fail, this function will call the default error handler to abort the 256 * program (see secp256k1_context_set_error_callback). 257 */ 258 SECP256K1_API void secp256k1_selftest(void); 259 260 261 /** Create a secp256k1 context object (in dynamically allocated memory). 262 * 263 * This function uses malloc to allocate memory. It is guaranteed that malloc is 264 * called at most once for every call of this function. If you need to avoid dynamic 265 * memory allocation entirely, see secp256k1_context_static and the functions in 266 * secp256k1_preallocated.h. 267 * 268 * Returns: a newly created context object. 269 * In: flags: Always set to SECP256K1_CONTEXT_NONE (see below). 270 * 271 * The only valid non-deprecated flag in recent library versions is 272 * SECP256K1_CONTEXT_NONE, which will create a context sufficient for all functionality 273 * offered by the library. All other (deprecated) flags will be treated as equivalent 274 * to the SECP256K1_CONTEXT_NONE flag. Though the flags parameter primarily exists for 275 * historical reasons, future versions of the library may introduce new flags. 276 * 277 * If the context is intended to be used for API functions that perform computations 278 * involving secret keys, e.g., signing and public key generation, then it is highly 279 * recommended to call secp256k1_context_randomize on the context before calling 280 * those API functions. This will provide enhanced protection against side-channel 281 * leakage, see secp256k1_context_randomize for details. 282 * 283 * Do not create a new context object for each operation, as construction and 284 * randomization can take non-negligible time. 285 */ 286 SECP256K1_API secp256k1_context *secp256k1_context_create( 287 unsigned int flags 288 ) SECP256K1_WARN_UNUSED_RESULT; 289 290 /** Copy a secp256k1 context object (into dynamically allocated memory). 291 * 292 * This function uses malloc to allocate memory. It is guaranteed that malloc is 293 * called at most once for every call of this function. If you need to avoid dynamic 294 * memory allocation entirely, see the functions in secp256k1_preallocated.h. 295 * 296 * Cloning secp256k1_context_static is not possible, and should not be emulated by 297 * the caller (e.g., using memcpy). Create a new context instead. 298 * 299 * Returns: a newly created context object. 300 * Args: ctx: an existing context to copy (not secp256k1_context_static) 301 */ 302 SECP256K1_API secp256k1_context *secp256k1_context_clone( 303 const secp256k1_context *ctx 304 ) SECP256K1_ARG_NONNULL(1) SECP256K1_WARN_UNUSED_RESULT; 305 306 /** Destroy a secp256k1 context object (created in dynamically allocated memory). 307 * 308 * The context pointer may not be used afterwards. 309 * 310 * The context to destroy must have been created using secp256k1_context_create 311 * or secp256k1_context_clone. If the context has instead been created using 312 * secp256k1_context_preallocated_create or secp256k1_context_preallocated_clone, the 313 * behaviour is undefined. In that case, secp256k1_context_preallocated_destroy must 314 * be used instead. 315 * 316 * Args: ctx: an existing context to destroy, constructed using 317 * secp256k1_context_create or secp256k1_context_clone 318 * (i.e., not secp256k1_context_static). 319 */ 320 SECP256K1_API void secp256k1_context_destroy( 321 secp256k1_context *ctx 322 ) SECP256K1_ARG_NONNULL(1); 323 324 /** Set a callback function to be called when an illegal argument is passed to 325 * an API call. It will only trigger for violations that are mentioned 326 * explicitly in the header. 327 * 328 * The philosophy is that these shouldn't be dealt with through a 329 * specific return value, as calling code should not have branches to deal with 330 * the case that this code itself is broken. 331 * 332 * On the other hand, during debug stage, one would want to be informed about 333 * such mistakes, and the default (crashing) may be inadvisable. 334 * When this callback is triggered, the API function called is guaranteed not 335 * to cause a crash, though its return value and output arguments are 336 * undefined. 337 * 338 * When this function has not been called (or called with fn==NULL), then the 339 * default handler will be used. The library provides a default handler which 340 * writes the message to stderr and calls abort. This default handler can be 341 * replaced at link time if the preprocessor macro 342 * USE_EXTERNAL_DEFAULT_CALLBACKS is defined, which is the case if the build 343 * has been configured with --enable-external-default-callbacks. Then the 344 * following two symbols must be provided to link against: 345 * - void secp256k1_default_illegal_callback_fn(const char *message, void *data); 346 * - void secp256k1_default_error_callback_fn(const char *message, void *data); 347 * The library can call these default handlers even before a proper callback data 348 * pointer could have been set using secp256k1_context_set_illegal_callback or 349 * secp256k1_context_set_error_callback, e.g., when the creation of a context 350 * fails. In this case, the corresponding default handler will be called with 351 * the data pointer argument set to NULL. 352 * 353 * Args: ctx: an existing context object. 354 * In: fun: a pointer to a function to call when an illegal argument is 355 * passed to the API, taking a message and an opaque pointer. 356 * (NULL restores the default handler.) 357 * data: the opaque pointer to pass to fun above, must be NULL for the default handler. 358 * 359 * See also secp256k1_context_set_error_callback. 360 */ 361 SECP256K1_API void secp256k1_context_set_illegal_callback( 362 secp256k1_context *ctx, 363 void (*fun)(const char *message, void *data), 364 const void *data 365 ) SECP256K1_ARG_NONNULL(1); 366 367 /** Set a callback function to be called when an internal consistency check 368 * fails. 369 * 370 * The default callback writes an error message to stderr and calls abort 371 * to abort the program. 372 * 373 * This can only trigger in case of a hardware failure, miscompilation, 374 * memory corruption, serious bug in the library, or other error would can 375 * otherwise result in undefined behaviour. It will not trigger due to mere 376 * incorrect usage of the API (see secp256k1_context_set_illegal_callback 377 * for that). After this callback returns, anything may happen, including 378 * crashing. 379 * 380 * Args: ctx: an existing context object. 381 * In: fun: a pointer to a function to call when an internal error occurs, 382 * taking a message and an opaque pointer (NULL restores the 383 * default handler, see secp256k1_context_set_illegal_callback 384 * for details). 385 * data: the opaque pointer to pass to fun above, must be NULL for the default handler. 386 * 387 * See also secp256k1_context_set_illegal_callback. 388 */ 389 SECP256K1_API void secp256k1_context_set_error_callback( 390 secp256k1_context *ctx, 391 void (*fun)(const char *message, void *data), 392 const void *data 393 ) SECP256K1_ARG_NONNULL(1); 394 395 /** Create a secp256k1 scratch space object. 396 * 397 * Returns: a newly created scratch space. 398 * Args: ctx: an existing context object. 399 * In: size: amount of memory to be available as scratch space. Some extra 400 * (<100 bytes) will be allocated for extra accounting. 401 */ 402 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT secp256k1_scratch_space *secp256k1_scratch_space_create( 403 const secp256k1_context *ctx, 404 size_t size 405 ) SECP256K1_ARG_NONNULL(1); 406 407 /** Destroy a secp256k1 scratch space. 408 * 409 * The pointer may not be used afterwards. 410 * Args: ctx: a secp256k1 context object. 411 * scratch: space to destroy 412 */ 413 SECP256K1_API void secp256k1_scratch_space_destroy( 414 const secp256k1_context *ctx, 415 secp256k1_scratch_space *scratch 416 ) SECP256K1_ARG_NONNULL(1); 417 418 /** Parse a variable-length public key into the pubkey object. 419 * 420 * Returns: 1 if the public key was fully valid. 421 * 0 if the public key could not be parsed or is invalid. 422 * Args: ctx: a secp256k1 context object. 423 * Out: pubkey: pointer to a pubkey object. If 1 is returned, it is set to a 424 * parsed version of input. If not, its value is undefined. 425 * In: input: pointer to a serialized public key 426 * inputlen: length of the array pointed to by input 427 * 428 * This function supports parsing compressed (33 bytes, header byte 0x02 or 429 * 0x03), uncompressed (65 bytes, header byte 0x04), or hybrid (65 bytes, header 430 * byte 0x06 or 0x07) format public keys. 431 */ 432 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_parse( 433 const secp256k1_context *ctx, 434 secp256k1_pubkey *pubkey, 435 const unsigned char *input, 436 size_t inputlen 437 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); 438 439 /** Serialize a pubkey object into a serialized byte sequence. 440 * 441 * Returns: 1 always. 442 * Args: ctx: a secp256k1 context object. 443 * Out: output: a pointer to a 65-byte (if compressed==0) or 33-byte (if 444 * compressed==1) byte array to place the serialized key 445 * in. 446 * In/Out: outputlen: a pointer to an integer which is initially set to the 447 * size of output, and is overwritten with the written 448 * size. 449 * In: pubkey: a pointer to a secp256k1_pubkey containing an 450 * initialized public key. 451 * flags: SECP256K1_EC_COMPRESSED if serialization should be in 452 * compressed format, otherwise SECP256K1_EC_UNCOMPRESSED. 453 */ 454 SECP256K1_API int secp256k1_ec_pubkey_serialize( 455 const secp256k1_context *ctx, 456 unsigned char *output, 457 size_t *outputlen, 458 const secp256k1_pubkey *pubkey, 459 unsigned int flags 460 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4); 461 462 /** Compare two public keys using lexicographic (of compressed serialization) order 463 * 464 * Returns: <0 if the first public key is less than the second 465 * >0 if the first public key is greater than the second 466 * 0 if the two public keys are equal 467 * Args: ctx: a secp256k1 context object. 468 * In: pubkey1: first public key to compare 469 * pubkey2: second public key to compare 470 */ 471 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_cmp( 472 const secp256k1_context *ctx, 473 const secp256k1_pubkey *pubkey1, 474 const secp256k1_pubkey *pubkey2 475 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); 476 477 /** Parse an ECDSA signature in compact (64 bytes) format. 478 * 479 * Returns: 1 when the signature could be parsed, 0 otherwise. 480 * Args: ctx: a secp256k1 context object 481 * Out: sig: a pointer to a signature object 482 * In: input64: a pointer to the 64-byte array to parse 483 * 484 * The signature must consist of a 32-byte big endian R value, followed by a 485 * 32-byte big endian S value. If R or S fall outside of [0..order-1], the 486 * encoding is invalid. R and S with value 0 are allowed in the encoding. 487 * 488 * After the call, sig will always be initialized. If parsing failed or R or 489 * S are zero, the resulting sig value is guaranteed to fail verification for 490 * any message and public key. 491 */ 492 SECP256K1_API int secp256k1_ecdsa_signature_parse_compact( 493 const secp256k1_context *ctx, 494 secp256k1_ecdsa_signature *sig, 495 const unsigned char *input64 496 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); 497 498 /** Parse a DER ECDSA signature. 499 * 500 * Returns: 1 when the signature could be parsed, 0 otherwise. 501 * Args: ctx: a secp256k1 context object 502 * Out: sig: a pointer to a signature object 503 * In: input: a pointer to the signature to be parsed 504 * inputlen: the length of the array pointed to be input 505 * 506 * This function will accept any valid DER encoded signature, even if the 507 * encoded numbers are out of range. 508 * 509 * After the call, sig will always be initialized. If parsing failed or the 510 * encoded numbers are out of range, signature verification with it is 511 * guaranteed to fail for every message and public key. 512 */ 513 SECP256K1_API int secp256k1_ecdsa_signature_parse_der( 514 const secp256k1_context *ctx, 515 secp256k1_ecdsa_signature *sig, 516 const unsigned char *input, 517 size_t inputlen 518 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); 519 520 /** Serialize an ECDSA signature in DER format. 521 * 522 * Returns: 1 if enough space was available to serialize, 0 otherwise 523 * Args: ctx: a secp256k1 context object 524 * Out: output: a pointer to an array to store the DER serialization 525 * In/Out: outputlen: a pointer to a length integer. Initially, this integer 526 * should be set to the length of output. After the call 527 * it will be set to the length of the serialization (even 528 * if 0 was returned). 529 * In: sig: a pointer to an initialized signature object 530 */ 531 SECP256K1_API int secp256k1_ecdsa_signature_serialize_der( 532 const secp256k1_context *ctx, 533 unsigned char *output, 534 size_t *outputlen, 535 const secp256k1_ecdsa_signature *sig 536 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4); 537 538 /** Serialize an ECDSA signature in compact (64 byte) format. 539 * 540 * Returns: 1 541 * Args: ctx: a secp256k1 context object 542 * Out: output64: a pointer to a 64-byte array to store the compact serialization 543 * In: sig: a pointer to an initialized signature object 544 * 545 * See secp256k1_ecdsa_signature_parse_compact for details about the encoding. 546 */ 547 SECP256K1_API int secp256k1_ecdsa_signature_serialize_compact( 548 const secp256k1_context *ctx, 549 unsigned char *output64, 550 const secp256k1_ecdsa_signature *sig 551 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); 552 553 /** Verify an ECDSA signature. 554 * 555 * Returns: 1: correct signature 556 * 0: incorrect or unparseable signature 557 * Args: ctx: a secp256k1 context object. 558 * In: sig: the signature being verified. 559 * msghash32: the 32-byte message hash being verified. 560 * The verifier must make sure to apply a cryptographic 561 * hash function to the message by itself and not accept an 562 * msghash32 value directly. Otherwise, it would be easy to 563 * create a "valid" signature without knowledge of the 564 * secret key. See also 565 * https://bitcoin.stackexchange.com/a/81116/35586 for more 566 * background on this topic. 567 * pubkey: pointer to an initialized public key to verify with. 568 * 569 * To avoid accepting malleable signatures, only ECDSA signatures in lower-S 570 * form are accepted. 571 * 572 * If you need to accept ECDSA signatures from sources that do not obey this 573 * rule, apply secp256k1_ecdsa_signature_normalize to the signature prior to 574 * verification, but be aware that doing so results in malleable signatures. 575 * 576 * For details, see the comments for that function. 577 */ 578 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_verify( 579 const secp256k1_context *ctx, 580 const secp256k1_ecdsa_signature *sig, 581 const unsigned char *msghash32, 582 const secp256k1_pubkey *pubkey 583 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4); 584 585 /** Convert a signature to a normalized lower-S form. 586 * 587 * Returns: 1 if sigin was not normalized, 0 if it already was. 588 * Args: ctx: a secp256k1 context object 589 * Out: sigout: a pointer to a signature to fill with the normalized form, 590 * or copy if the input was already normalized. (can be NULL if 591 * you're only interested in whether the input was already 592 * normalized). 593 * In: sigin: a pointer to a signature to check/normalize (can be identical to sigout) 594 * 595 * With ECDSA a third-party can forge a second distinct signature of the same 596 * message, given a single initial signature, but without knowing the key. This 597 * is done by negating the S value modulo the order of the curve, 'flipping' 598 * the sign of the random point R which is not included in the signature. 599 * 600 * Forgery of the same message isn't universally problematic, but in systems 601 * where message malleability or uniqueness of signatures is important this can 602 * cause issues. This forgery can be blocked by all verifiers forcing signers 603 * to use a normalized form. 604 * 605 * The lower-S form reduces the size of signatures slightly on average when 606 * variable length encodings (such as DER) are used and is cheap to verify, 607 * making it a good choice. Security of always using lower-S is assured because 608 * anyone can trivially modify a signature after the fact to enforce this 609 * property anyway. 610 * 611 * The lower S value is always between 0x1 and 612 * 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0, 613 * inclusive. 614 * 615 * No other forms of ECDSA malleability are known and none seem likely, but 616 * there is no formal proof that ECDSA, even with this additional restriction, 617 * is free of other malleability. Commonly used serialization schemes will also 618 * accept various non-unique encodings, so care should be taken when this 619 * property is required for an application. 620 * 621 * The secp256k1_ecdsa_sign function will by default create signatures in the 622 * lower-S form, and secp256k1_ecdsa_verify will not accept others. In case 623 * signatures come from a system that cannot enforce this property, 624 * secp256k1_ecdsa_signature_normalize must be called before verification. 625 */ 626 SECP256K1_API int secp256k1_ecdsa_signature_normalize( 627 const secp256k1_context *ctx, 628 secp256k1_ecdsa_signature *sigout, 629 const secp256k1_ecdsa_signature *sigin 630 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(3); 631 632 /** An implementation of RFC6979 (using HMAC-SHA256) as nonce generation function. 633 * If a data pointer is passed, it is assumed to be a pointer to 32 bytes of 634 * extra entropy. 635 */ 636 SECP256K1_API const secp256k1_nonce_function secp256k1_nonce_function_rfc6979; 637 638 /** A default safe nonce generation function (currently equal to secp256k1_nonce_function_rfc6979). */ 639 SECP256K1_API const secp256k1_nonce_function secp256k1_nonce_function_default; 640 641 /** Create an ECDSA signature. 642 * 643 * Returns: 1: signature created 644 * 0: the nonce generation function failed, or the secret key was invalid. 645 * Args: ctx: pointer to a context object (not secp256k1_context_static). 646 * Out: sig: pointer to an array where the signature will be placed. 647 * In: msghash32: the 32-byte message hash being signed. 648 * seckey: pointer to a 32-byte secret key. 649 * noncefp: pointer to a nonce generation function. If NULL, 650 * secp256k1_nonce_function_default is used. 651 * ndata: pointer to arbitrary data used by the nonce generation function 652 * (can be NULL). If it is non-NULL and 653 * secp256k1_nonce_function_default is used, then ndata must be a 654 * pointer to 32-bytes of additional data. 655 * 656 * The created signature is always in lower-S form. See 657 * secp256k1_ecdsa_signature_normalize for more details. 658 */ 659 SECP256K1_API int secp256k1_ecdsa_sign( 660 const secp256k1_context *ctx, 661 secp256k1_ecdsa_signature *sig, 662 const unsigned char *msghash32, 663 const unsigned char *seckey, 664 secp256k1_nonce_function noncefp, 665 const void *ndata 666 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4); 667 668 /** Verify an ECDSA secret key. 669 * 670 * A secret key is valid if it is not 0 and less than the secp256k1 curve order 671 * when interpreted as an integer (most significant byte first). The 672 * probability of choosing a 32-byte string uniformly at random which is an 673 * invalid secret key is negligible. 674 * 675 * Returns: 1: secret key is valid 676 * 0: secret key is invalid 677 * Args: ctx: pointer to a context object. 678 * In: seckey: pointer to a 32-byte secret key. 679 */ 680 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_verify( 681 const secp256k1_context *ctx, 682 const unsigned char *seckey 683 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2); 684 685 /** Compute the public key for a secret key. 686 * 687 * Returns: 1: secret was valid, public key stores. 688 * 0: secret was invalid, try again. 689 * Args: ctx: pointer to a context object (not secp256k1_context_static). 690 * Out: pubkey: pointer to the created public key. 691 * In: seckey: pointer to a 32-byte secret key. 692 */ 693 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_create( 694 const secp256k1_context *ctx, 695 secp256k1_pubkey *pubkey, 696 const unsigned char *seckey 697 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); 698 699 /** Negates a secret key in place. 700 * 701 * Returns: 0 if the given secret key is invalid according to 702 * secp256k1_ec_seckey_verify. 1 otherwise 703 * Args: ctx: pointer to a context object 704 * In/Out: seckey: pointer to the 32-byte secret key to be negated. If the 705 * secret key is invalid according to 706 * secp256k1_ec_seckey_verify, this function returns 0 and 707 * seckey will be set to some unspecified value. 708 */ 709 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_negate( 710 const secp256k1_context *ctx, 711 unsigned char *seckey 712 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2); 713 714 /** Same as secp256k1_ec_seckey_negate, but DEPRECATED. Will be removed in 715 * future versions. */ 716 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_negate( 717 const secp256k1_context *ctx, 718 unsigned char *seckey 719 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) 720 SECP256K1_DEPRECATED("Use secp256k1_ec_seckey_negate instead"); 721 722 /** Negates a public key in place. 723 * 724 * Returns: 1 always 725 * Args: ctx: pointer to a context object 726 * In/Out: pubkey: pointer to the public key to be negated. 727 */ 728 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_negate( 729 const secp256k1_context *ctx, 730 secp256k1_pubkey *pubkey 731 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2); 732 733 /** Tweak a secret key by adding tweak to it. 734 * 735 * Returns: 0 if the arguments are invalid or the resulting secret key would be 736 * invalid (only when the tweak is the negation of the secret key). 1 737 * otherwise. 738 * Args: ctx: pointer to a context object. 739 * In/Out: seckey: pointer to a 32-byte secret key. If the secret key is 740 * invalid according to secp256k1_ec_seckey_verify, this 741 * function returns 0. seckey will be set to some unspecified 742 * value if this function returns 0. 743 * In: tweak32: pointer to a 32-byte tweak, which must be valid according to 744 * secp256k1_ec_seckey_verify or 32 zero bytes. For uniformly 745 * random 32-byte tweaks, the chance of being invalid is 746 * negligible (around 1 in 2^128). 747 */ 748 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_add( 749 const secp256k1_context *ctx, 750 unsigned char *seckey, 751 const unsigned char *tweak32 752 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); 753 754 /** Same as secp256k1_ec_seckey_tweak_add, but DEPRECATED. Will be removed in 755 * future versions. */ 756 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_add( 757 const secp256k1_context *ctx, 758 unsigned char *seckey, 759 const unsigned char *tweak32 760 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) 761 SECP256K1_DEPRECATED("Use secp256k1_ec_seckey_tweak_add instead"); 762 763 /** Tweak a public key by adding tweak times the generator to it. 764 * 765 * Returns: 0 if the arguments are invalid or the resulting public key would be 766 * invalid (only when the tweak is the negation of the corresponding 767 * secret key). 1 otherwise. 768 * Args: ctx: pointer to a context object. 769 * In/Out: pubkey: pointer to a public key object. pubkey will be set to an 770 * invalid value if this function returns 0. 771 * In: tweak32: pointer to a 32-byte tweak, which must be valid according to 772 * secp256k1_ec_seckey_verify or 32 zero bytes. For uniformly 773 * random 32-byte tweaks, the chance of being invalid is 774 * negligible (around 1 in 2^128). 775 */ 776 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_add( 777 const secp256k1_context *ctx, 778 secp256k1_pubkey *pubkey, 779 const unsigned char *tweak32 780 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); 781 782 /** Tweak a secret key by multiplying it by a tweak. 783 * 784 * Returns: 0 if the arguments are invalid. 1 otherwise. 785 * Args: ctx: pointer to a context object. 786 * In/Out: seckey: pointer to a 32-byte secret key. If the secret key is 787 * invalid according to secp256k1_ec_seckey_verify, this 788 * function returns 0. seckey will be set to some unspecified 789 * value if this function returns 0. 790 * In: tweak32: pointer to a 32-byte tweak. If the tweak is invalid according to 791 * secp256k1_ec_seckey_verify, this function returns 0. For 792 * uniformly random 32-byte arrays the chance of being invalid 793 * is negligible (around 1 in 2^128). 794 */ 795 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_mul( 796 const secp256k1_context *ctx, 797 unsigned char *seckey, 798 const unsigned char *tweak32 799 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); 800 801 /** Same as secp256k1_ec_seckey_tweak_mul, but DEPRECATED. Will be removed in 802 * future versions. */ 803 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_mul( 804 const secp256k1_context *ctx, 805 unsigned char *seckey, 806 const unsigned char *tweak32 807 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) 808 SECP256K1_DEPRECATED("Use secp256k1_ec_seckey_tweak_mul instead"); 809 810 /** Tweak a public key by multiplying it by a tweak value. 811 * 812 * Returns: 0 if the arguments are invalid. 1 otherwise. 813 * Args: ctx: pointer to a context object. 814 * In/Out: pubkey: pointer to a public key object. pubkey will be set to an 815 * invalid value if this function returns 0. 816 * In: tweak32: pointer to a 32-byte tweak. If the tweak is invalid according to 817 * secp256k1_ec_seckey_verify, this function returns 0. For 818 * uniformly random 32-byte arrays the chance of being invalid 819 * is negligible (around 1 in 2^128). 820 */ 821 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_mul( 822 const secp256k1_context *ctx, 823 secp256k1_pubkey *pubkey, 824 const unsigned char *tweak32 825 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); 826 827 /** Randomizes the context to provide enhanced protection against side-channel leakage. 828 * 829 * Returns: 1: randomization successful 830 * 0: error 831 * Args: ctx: pointer to a context object (not secp256k1_context_static). 832 * In: seed32: pointer to a 32-byte random seed (NULL resets to initial state). 833 * 834 * While secp256k1 code is written and tested to be constant-time no matter what 835 * secret values are, it is possible that a compiler may output code which is not, 836 * and also that the CPU may not emit the same radio frequencies or draw the same 837 * amount of power for all values. Randomization of the context shields against 838 * side-channel observations which aim to exploit secret-dependent behaviour in 839 * certain computations which involve secret keys. 840 * 841 * It is highly recommended to call this function on contexts returned from 842 * secp256k1_context_create or secp256k1_context_clone (or from the corresponding 843 * functions in secp256k1_preallocated.h) before using these contexts to call API 844 * functions that perform computations involving secret keys, e.g., signing and 845 * public key generation. It is possible to call this function more than once on 846 * the same context, and doing so before every few computations involving secret 847 * keys is recommended as a defense-in-depth measure. Randomization of the static 848 * context secp256k1_context_static is not supported. 849 * 850 * Currently, the random seed is mainly used for blinding multiplications of a 851 * secret scalar with the elliptic curve base point. Multiplications of this 852 * kind are performed by exactly those API functions which are documented to 853 * require a context that is not secp256k1_context_static. As a rule of thumb, 854 * these are all functions which take a secret key (or a keypair) as an input. 855 * A notable exception to that rule is the ECDH module, which relies on a different 856 * kind of elliptic curve point multiplication and thus does not benefit from 857 * enhanced protection against side-channel leakage currently. 858 */ 859 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_context_randomize( 860 secp256k1_context *ctx, 861 const unsigned char *seed32 862 ) SECP256K1_ARG_NONNULL(1); 863 864 /** Add a number of public keys together. 865 * 866 * Returns: 1: the sum of the public keys is valid. 867 * 0: the sum of the public keys is not valid. 868 * Args: ctx: pointer to a context object. 869 * Out: out: pointer to a public key object for placing the resulting public key. 870 * In: ins: pointer to array of pointers to public keys. 871 * n: the number of public keys to add together (must be at least 1). 872 */ 873 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_combine( 874 const secp256k1_context *ctx, 875 secp256k1_pubkey *out, 876 const secp256k1_pubkey * const *ins, 877 size_t n 878 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3); 879 880 /** Compute a tagged hash as defined in BIP-340. 881 * 882 * This is useful for creating a message hash and achieving domain separation 883 * through an application-specific tag. This function returns 884 * SHA256(SHA256(tag)||SHA256(tag)||msg). Therefore, tagged hash 885 * implementations optimized for a specific tag can precompute the SHA256 state 886 * after hashing the tag hashes. 887 * 888 * Returns: 1 always. 889 * Args: ctx: pointer to a context object 890 * Out: hash32: pointer to a 32-byte array to store the resulting hash 891 * In: tag: pointer to an array containing the tag 892 * taglen: length of the tag array 893 * msg: pointer to an array containing the message 894 * msglen: length of the message array 895 */ 896 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_tagged_sha256( 897 const secp256k1_context *ctx, 898 unsigned char *hash32, 899 const unsigned char *tag, 900 size_t taglen, 901 const unsigned char *msg, 902 size_t msglen 903 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(5); 904 905 #ifdef __cplusplus 906 } 907 #endif 908 909 #endif /* SECP256K1_H */