Inside Bitcoin

501 *        pubkey2:  second public key to compare
502 */
503SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_cmp(
504    const secp256k1_context *ctx,
505    const secp256k1_pubkey *pubkey1,
506    const secp256k1_pubkey *pubkey2
507) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
508
509/** Sort public keys using lexicographic (of compressed serialization) order
510 *
511 *  Returns: 0 if the arguments are invalid. 1 otherwise.
512 *
513 *  Args:     ctx: pointer to a context object
514 *  In:   pubkeys: array of pointers to pubkeys to sort
515 *      n_pubkeys: number of elements in the pubkeys array
516 */
517SECP256K1_API int secp256k1_ec_pubkey_sort(
518    const secp256k1_context *ctx,
519    const secp256k1_pubkey **pubkeys,
520    size_t n_pubkeys
521) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
522
523/** Parse an ECDSA signature in compact (64 bytes) format.
524 *
525 *  Returns: 1 when the signature could be parsed, 0 otherwise.
526 *  Args: ctx:      pointer to a context object
527 *  Out:  sig:      pointer to a signature object
528 *  In:   input64:  pointer to the 64-byte array to parse
529 *
530 *  The signature must consist of a 32-byte big endian R value, followed by a
531 *  32-byte big endian S value. If R or S fall outside of [0..order-1], the
532 *  encoding is invalid. R and S with value 0 are allowed in the encoding.
533 *
534 *  After the call, sig will always be initialized. If parsing failed or R or
535 *  S are zero, the resulting sig value is guaranteed to fail verification for
536 *  any message and public key.
537 */
538SECP256K1_API int secp256k1_ecdsa_signature_parse_compact(
539    const secp256k1_context *ctx,
540    secp256k1_ecdsa_signature *sig,
541    const unsigned char *input64
542) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
543
544/** Parse a DER ECDSA signature.
545 *
546 *  Returns: 1 when the signature could be parsed, 0 otherwise.
547 *  Args: ctx:      pointer to a context object
548 *  Out:  sig:      pointer to a signature object
549 *  In:   input:    pointer to the signature to be parsed
550 *        inputlen: the length of the array pointed to be input
551 *
552 *  This function will accept any valid DER encoded signature, even if the
553 *  encoded numbers are out of range.
554 *
555 *  After the call, sig will always be initialized. If parsing failed or the
556 *  encoded numbers are out of range, signature verification with it is
557 *  guaranteed to fail for every message and public key.
558 */
559SECP256K1_API int secp256k1_ecdsa_signature_parse_der(
560    const secp256k1_context *ctx,
561    secp256k1_ecdsa_signature *sig,
562    const unsigned char *input,
563    size_t inputlen
564) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
565
566/** Serialize an ECDSA signature in DER format.
567 *
568 *  Returns: 1 if enough space was available to serialize, 0 otherwise
569 *  Args:   ctx:       pointer to a context object
570 *  Out:    output:    pointer to an array to store the DER serialization
571 *  In/Out: outputlen: pointer to a length integer. Initially, this integer
572 *                     should be set to the length of output. After the call
573 *                     it will be set to the length of the serialization (even
574 *                     if 0 was returned).
575 *  In:     sig:       pointer to an initialized signature object
576 */
577SECP256K1_API int secp256k1_ecdsa_signature_serialize_der(
578    const secp256k1_context *ctx,
579    unsigned char *output,
580    size_t *outputlen,
581    const secp256k1_ecdsa_signature *sig
582) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
583
584/** Serialize an ECDSA signature in compact (64 byte) format.
585 *
586 *  Returns: 1
587 *  Args:   ctx:       pointer to a context object
588 *  Out:    output64:  pointer to a 64-byte array to store the compact serialization
589 *  In:     sig:       pointer to an initialized signature object
590 *
591 *  See secp256k1_ecdsa_signature_parse_compact for details about the encoding.
592 */
593SECP256K1_API int secp256k1_ecdsa_signature_serialize_compact(
594    const secp256k1_context *ctx,
595    unsigned char *output64,
596    const secp256k1_ecdsa_signature *sig
597) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
598
599/** Verify an ECDSA signature.
600 *
601 *  Returns: 1: correct signature
602 *           0: incorrect or unparseable signature
603 *  Args:    ctx:       pointer to a context object
604 *  In:      sig:       the signature being verified.
605 *           msghash32: the 32-byte message hash being verified.
606 *                      The verifier must make sure to apply a cryptographic
607 *                      hash function to the message by itself and not accept an
608 *                      msghash32 value directly. Otherwise, it would be easy to
609 *                      create a "valid" signature without knowledge of the
610 *                      secret key. See also
611 *                      https://bitcoin.stackexchange.com/a/81116/35586 for more
612 *                      background on this topic.
613 *           pubkey:    pointer to an initialized public key to verify with.
614 *
615 * To avoid accepting malleable signatures, only ECDSA signatures in lower-S
616 * form are accepted.
617 *
618 * If you need to accept ECDSA signatures from sources that do not obey this
619 * rule, apply secp256k1_ecdsa_signature_normalize to the signature prior to
620 * verification, but be aware that doing so results in malleable signatures.
621 *
622 * For details, see the comments for that function.
623 */
624SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_verify(
625    const secp256k1_context *ctx,
626    const secp256k1_ecdsa_signature *sig,
627    const unsigned char *msghash32,
628    const secp256k1_pubkey *pubkey
629) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
630
631/** Convert a signature to a normalized lower-S form.
632 *
633 *  Returns: 1 if sigin was not normalized, 0 if it already was.
634 *  Args: ctx:    pointer to a context object
635 *  Out:  sigout: pointer to a signature to fill with the normalized form,
636 *                or copy if the input was already normalized. (can be NULL if
637 *                you're only interested in whether the input was already
638 *                normalized).
639 *  In:   sigin:  pointer to a signature to check/normalize (can be identical to sigout)
640 *
641 *  With ECDSA a third-party can forge a second distinct signature of the same
642 *  message, given a single initial signature, but without knowing the key. This
643 *  is done by negating the S value modulo the order of the curve, 'flipping'
644 *  the sign of the random point R which is not included in the signature.
645 *
646 *  Forgery of the same message isn't universally problematic, but in systems
647 *  where message malleability or uniqueness of signatures is important this can
648 *  cause issues. This forgery can be blocked by all verifiers forcing signers
649 *  to use a normalized form.
650 *
651 *  The lower-S form reduces the size of signatures slightly on average when
652 *  variable length encodings (such as DER) are used and is cheap to verify,
653 *  making it a good choice. Security of always using lower-S is assured because
654 *  anyone can trivially modify a signature after the fact to enforce this
655 *  property anyway.
656 *
657 *  The lower S value is always between 0x1 and
658 *  0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0,
659 *  inclusive.
660 *
661 *  No other forms of ECDSA malleability are known and none seem likely, but
662 *  there is no formal proof that ECDSA, even with this additional restriction,
663 *  is free of other malleability. Commonly used serialization schemes will also
664 *  accept various non-unique encodings, so care should be taken when this
665 *  property is required for an application.
666 *
667 *  The secp256k1_ecdsa_sign function will by default create signatures in the
668 *  lower-S form, and secp256k1_ecdsa_verify will not accept others. In case
669 *  signatures come from a system that cannot enforce this property,
670 *  secp256k1_ecdsa_signature_normalize must be called before verification.
671 */
672SECP256K1_API int secp256k1_ecdsa_signature_normalize(
673    const secp256k1_context *ctx,
674    secp256k1_ecdsa_signature *sigout,
675    const secp256k1_ecdsa_signature *sigin
676) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(3);
677
678/** An implementation of RFC6979 (using HMAC-SHA256) as nonce generation function.
679 * If a data pointer is passed, it is assumed to be a pointer to 32 bytes of
680 * extra entropy.
681 */
682SECP256K1_API const secp256k1_nonce_function secp256k1_nonce_function_rfc6979;
683
684/** A default safe nonce generation function (currently equal to secp256k1_nonce_function_rfc6979). */
685SECP256K1_API const secp256k1_nonce_function secp256k1_nonce_function_default;
686
687/** Create an ECDSA signature.
688 *
689 *  Returns: 1: signature created
690 *           0: the nonce generation function failed, or the secret key was invalid.
691 *  Args:    ctx:       pointer to a context object (not secp256k1_context_static).
692 *  Out:     sig:       pointer to a signature object.
693 *  In:      msghash32: the 32-byte message hash being signed.
694 *           seckey:    pointer to a 32-byte secret key.
695 *           noncefp:   pointer to a nonce generation function. If NULL,
696 *                      secp256k1_nonce_function_default is used.
697 *           ndata:     pointer to arbitrary data used by the nonce generation function
698 *                      (can be NULL). If it is non-NULL and
699 *                      secp256k1_nonce_function_default is used, then ndata must be a
700 *                      pointer to 32-bytes of additional data.
701 *
702 * The created signature is always in lower-S form. See
703 * secp256k1_ecdsa_signature_normalize for more details.
704 */
705SECP256K1_API int secp256k1_ecdsa_sign(
706    const secp256k1_context *ctx,
707    secp256k1_ecdsa_signature *sig,
708    const unsigned char *msghash32,
709    const unsigned char *seckey,
710    secp256k1_nonce_function noncefp,
711    const void *ndata
712) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
713
714/** Verify an elliptic curve secret key.
715 *
716 *  A secret key is valid if it is not 0 and less than the secp256k1 curve order
717 *  when interpreted as an integer (most significant byte first). The
718 *  probability of choosing a 32-byte string uniformly at random which is an
719 *  invalid secret key is negligible. However, if it does happen it should
720 *  be assumed that the randomness source is severely broken and there should
721 *  be no retry.
722 *
723 *  Returns: 1: secret key is valid
724 *           0: secret key is invalid
725 *  Args:    ctx: pointer to a context object.
726 *  In:      seckey: pointer to a 32-byte secret key.
727 */
728SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_verify(
729    const secp256k1_context *ctx,
730    const unsigned char *seckey
731) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
732
733/** Compute the public key for a secret key.
734 *
735 *  Returns: 1: secret was valid, public key stores.
736 *           0: secret was invalid, try again.
737 *  Args:    ctx:    pointer to a context object (not secp256k1_context_static).
738 *  Out:     pubkey: pointer to the created public key.
739 *  In:      seckey: pointer to a 32-byte secret key.
740 */
741SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_create(
742    const secp256k1_context *ctx,
743    secp256k1_pubkey *pubkey,
744    const unsigned char *seckey
745) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
746
747/** Negates a secret key in place.
748 *
749 *  Returns: 0 if the given secret key is invalid according to
750 *           secp256k1_ec_seckey_verify. 1 otherwise