Inside Bitcoin

251 *
252 *  If the tests fail, this function will call the default error callback to abort the
253 *  program (see secp256k1_context_set_error_callback).
254 */
255SECP256K1_API void secp256k1_selftest(void);
256
257
258/** Create a secp256k1 context object (in dynamically allocated memory).
259 *
260 *  This function uses malloc to allocate memory. It is guaranteed that malloc is
261 *  called at most once for every call of this function. If you need to avoid dynamic
262 *  memory allocation entirely, see secp256k1_context_static and the functions in
263 *  secp256k1_preallocated.h.
264 *
265 *  Returns: pointer to a newly created context object.
266 *  In:      flags: Always set to SECP256K1_CONTEXT_NONE (see below).
267 *
268 *  The only valid non-deprecated flag in recent library versions is
269 *  SECP256K1_CONTEXT_NONE, which will create a context sufficient for all functionality
270 *  offered by the library. All other (deprecated) flags will be treated as equivalent
271 *  to the SECP256K1_CONTEXT_NONE flag. Though the flags parameter primarily exists for
272 *  historical reasons, future versions of the library may introduce new flags.
273 *
274 *  If the context is intended to be used for API functions that perform computations
275 *  involving secret keys, e.g., signing and public key generation, then it is highly
276 *  recommended to call secp256k1_context_randomize on the context before calling
277 *  those API functions. This will provide enhanced protection against side-channel
278 *  leakage, see secp256k1_context_randomize for details.
279 *
280 *  Do not create a new context object for each operation, as construction and
281 *  randomization can take non-negligible time.
282 */
283SECP256K1_API secp256k1_context *secp256k1_context_create(
284    unsigned int flags
285) SECP256K1_WARN_UNUSED_RESULT;
286
287/** Copy a secp256k1 context object (into dynamically allocated memory).
288 *
289 *  This function uses malloc to allocate memory. It is guaranteed that malloc is
290 *  called at most once for every call of this function. If you need to avoid dynamic
291 *  memory allocation entirely, see the functions in secp256k1_preallocated.h.
292 *
293 *  Cloning secp256k1_context_static is not possible, and should not be emulated by
294 *  the caller (e.g., using memcpy). Create a new context instead.
295 *
296 *  Returns: pointer to a newly created context object.
297 *  Args:    ctx: pointer to a context to copy (not secp256k1_context_static).
298 */
299SECP256K1_API secp256k1_context *secp256k1_context_clone(
300    const secp256k1_context *ctx
301) SECP256K1_ARG_NONNULL(1) SECP256K1_WARN_UNUSED_RESULT;
302
303/** Destroy a secp256k1 context object (created in dynamically allocated memory).
304 *
305 *  The context pointer may not be used afterwards.
306 *
307 *  The context to destroy must have been created using secp256k1_context_create
308 *  or secp256k1_context_clone. If the context has instead been created using
309 *  secp256k1_context_preallocated_create or secp256k1_context_preallocated_clone, the
310 *  behaviour is undefined. In that case, secp256k1_context_preallocated_destroy must
311 *  be used instead.
312 *
313 *  Args:   ctx: pointer to a context to destroy, constructed using
314 *               secp256k1_context_create or secp256k1_context_clone
315 *               (i.e., not secp256k1_context_static).
316 */
317SECP256K1_API void secp256k1_context_destroy(
318    secp256k1_context *ctx
319) SECP256K1_ARG_NONNULL(1);
320
321/** Set a callback function to be called when an illegal argument is passed to
322 *  an API call. It will only trigger for violations that are mentioned
323 *  explicitly in the header.
324 *
325 *  The philosophy is that these shouldn't be dealt with through a specific
326 *  return value, as calling code should not have branches to deal with the case
327 *  that this code itself is broken.
328 *
329 *  On the other hand, during debug stage, one would want to be informed about
330 *  such mistakes, and the default (crashing) may be inadvisable. Should this
331 *  callback return instead of crashing, the return value and output arguments
332 *  of the API function call are undefined. Moreover, the same API call may
333 *  trigger the callback again in this case.
334 *
335 *  When this function has not been called (or called with fun==NULL), then the
336 *  default callback will be used. The library provides a default callback which
337 *  writes the message to stderr and calls abort. This default callback can be
338 *  replaced at link time if the preprocessor macro
339 *  USE_EXTERNAL_DEFAULT_CALLBACKS is defined, which is the case if the build
340 *  has been configured with --enable-external-default-callbacks (GNU Autotools) or
341 *  -DSECP256K1_USE_EXTERNAL_DEFAULT_CALLBACKS=ON (CMake). Then the
342 *  following two symbols must be provided to link against:
343 *   - void secp256k1_default_illegal_callback_fn(const char *message, void *data);
344 *   - void secp256k1_default_error_callback_fn(const char *message, void *data);
345 *  The library may call a default callback even before a proper callback data
346 *  pointer could have been set using secp256k1_context_set_illegal_callback or
347 *  secp256k1_context_set_error_callback, e.g., when the creation of a context
348 *  fails. In this case, the corresponding default callback will be called with
349 *  the data pointer argument set to NULL.
350 *
351 *  Args: ctx:  pointer to a context object.
352 *  In:   fun:  pointer to a function to call when an illegal argument is
353 *              passed to the API, taking a message and an opaque pointer.
354 *              (NULL restores the default callback.)
355 *        data: the opaque pointer to pass to fun above, must be NULL for the
356 *              default callback.
357 *
358 *  See also secp256k1_context_set_error_callback.
359 */
360SECP256K1_API void secp256k1_context_set_illegal_callback(
361    secp256k1_context *ctx,
362    void (*fun)(const char *message, void *data),
363    const void *data
364) SECP256K1_ARG_NONNULL(1);
365
366/** Set a callback function to be called when an internal consistency check
367 *  fails.
368 *
369 *  The default callback writes an error message to stderr and calls abort
370 *  to abort the program.
371 *
372 *  This can only trigger in case of a hardware failure, miscompilation,
373 *  memory corruption, serious bug in the library, or other error that would
374 *  result in undefined behaviour. It will not trigger due to mere
375 *  incorrect usage of the API (see secp256k1_context_set_illegal_callback
376 *  for that). After this callback returns, anything may happen, including
377 *  crashing.
378 *
379 *  Args: ctx:  pointer to a context object.
380 *  In:   fun:  pointer to a function to call when an internal error occurs,
381 *              taking a message and an opaque pointer (NULL restores the
382 *              default callback, see secp256k1_context_set_illegal_callback
383 *              for details).
384 *        data: the opaque pointer to pass to fun above, must be NULL for the
385 *              default callback.
386 *
387 *  See also secp256k1_context_set_illegal_callback.
388 */
389SECP256K1_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/** A pointer to a function implementing SHA256's internal compression function.
396 *
397 * This function processes one or more contiguous 64-byte message blocks and
398 * updates the internal SHA256 state accordingly. The function is not responsible
399 * for counting consumed blocks or bytes, nor for performing padding.
400 *
401 * In/Out:  state:     pointer to eight 32-bit words representing the current internal state;
402 *                     the state is updated in place.
403 * In:      blocks64:  pointer to concatenation of n_blocks blocks, of 64 bytes each.
404 *                     no alignment guarantees are made for this pointer.
405 *          n_blocks:  number of contiguous 64-byte blocks to process.
406 */
407typedef void (*secp256k1_sha256_compression_function)(
408    uint32_t *state,
409    const unsigned char *blocks64,
410    size_t n_blocks
411);
412
413/**
414 * Set a callback function to override the internal SHA256 compression function.
415 *
416 * This installs a callback to replace the built-in block-compression
417 * step used by the library's internal SHA256 implementation.
418 * The provided callback must exactly implement the effect of n_blocks
419 * repeated applications of the SHA256 compression function.
420 *
421 * This API exists to support environments that wish to route the
422 * SHA256 compression step through a hardware-accelerated or otherwise
423 * specialized implementation. It is NOT meant for replacing SHA256
424 * with a different hash function.
425 *
426 * Since auxiliary functions exposed by the library via a function
427 * pointer such as secp256k1_nonce_function_default do not take a
428 * context object, they will not use the callback when called directly
429 * from user code. (But they will use the callback when called from
430 * other library functions that do take a context object, e.g., when
431 * noncefp==NULL or noncefp==secp256k1_nonce_function_default is passed
432 * as an argument to secp256k1_ecdsa_sign.)
433 *
434 * Note: The provided function is tested against a set of known SHA256
435 * digests; invokes the context's illegal callback on any mismatch
436 * (which aborts by default), in order to catch basic misbehavior early.
437 * It takes well under 2.5 ms on a desktop machine.
438 * This is NOT a substitute for having proper test coverage of the
439 * supplied function outside this library.
440 *
441 * Args:    ctx:             pointer to a context object.
442 * In:      fn_compression:  pointer to a function implementing the compression function;
443 *                           passing NULL restores the default implementation.
444 */
445SECP256K1_API void secp256k1_context_set_sha256_compression(
446        secp256k1_context *ctx,
447        secp256k1_sha256_compression_function fn_compression
448) SECP256K1_ARG_NONNULL(1);
449
450/** Parse a variable-length public key into the pubkey object.
451 *
452 *  Returns: 1 if the public key was fully valid.
453 *           0 if the public key could not be parsed or is invalid.
454 *  Args: ctx:      pointer to a context object.
455 *  Out:  pubkey:   pointer to a pubkey object. If 1 is returned, it is set to a
456 *                  parsed version of input. If not, its value is undefined.
457 *  In:   input:    pointer to a serialized public key
458 *        inputlen: length of the array pointed to by input
459 *
460 *  This function supports parsing compressed (33 bytes, header byte 0x02 or
461 *  0x03), uncompressed (65 bytes, header byte 0x04), or hybrid (65 bytes, header
462 *  byte 0x06 or 0x07) format public keys.
463 */
464SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_parse(
465    const secp256k1_context *ctx,
466    secp256k1_pubkey *pubkey,
467    const unsigned char *input,
468    size_t inputlen
469) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
470
471/** Serialize a pubkey object into a serialized byte sequence.
472 *
473 *  Returns: 1 always.
474 *  Args:   ctx:        pointer to a context object.
475 *  Out:    output:     pointer to a 65-byte (if compressed==0) or 33-byte (if
476 *                      compressed==1) byte array to place the serialized key
477 *                      in.
478 *  In/Out: outputlen:  pointer to an integer which is initially set to the
479 *                      size of output, and is overwritten with the written
480 *                      size.
481 *  In:     pubkey:     pointer to a secp256k1_pubkey containing an
482 *                      initialized public key.
483 *          flags:      SECP256K1_EC_COMPRESSED if serialization should be in
484 *                      compressed format, otherwise SECP256K1_EC_UNCOMPRESSED.
485 */
486SECP256K1_API int secp256k1_ec_pubkey_serialize(
487    const secp256k1_context *ctx,
488    unsigned char *output,
489    size_t *outputlen,
490    const secp256k1_pubkey *pubkey,
491    unsigned int flags
492) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
493
494/** Compare two public keys using lexicographic (of compressed serialization) order
495 *
496 *  Returns: <0 if the first public key is less than the second
497 *           >0 if the first public key is greater than the second
498 *           0 if the two public keys are equal
499 *  Args: ctx:      pointer to a context object
500 *  In:   pubkey1:  first public key to compare