Inside Bitcoin

1#ifndef SECP256K1_RECOVERY_H
2#define SECP256K1_RECOVERY_H
3
4#include "secp256k1.h"
5
6#ifdef __cplusplus
7extern "C" {
8#endif
9
10/** Opaque data structure that holds a parsed ECDSA signature,
11 *  supporting pubkey recovery.
12 *
13 *  The exact representation of data inside is implementation defined and not
14 *  guaranteed to be portable between different platforms or versions. It is
15 *  however guaranteed to be 65 bytes in size, and can be safely copied/moved.
16 *  If you need to convert to a format suitable for storage or transmission, use
17 *  the secp256k1_ecdsa_signature_serialize_* and
18 *  secp256k1_ecdsa_signature_parse_* functions.
19 *
20 *  Furthermore, it is guaranteed that identical signatures (including their
21 *  recoverability) will have identical representation, so they can be
22 *  memcmp'ed.
23 */
24typedef struct secp256k1_ecdsa_recoverable_signature {
25    unsigned char data[65];
26} secp256k1_ecdsa_recoverable_signature;
27
28/** Parse a compact ECDSA signature (64 bytes + recovery id).
29 *
30 *  Returns: 1 when the signature could be parsed, 0 otherwise
31 *  Args: ctx:     pointer to a context object
32 *  Out:  sig:     pointer to a signature object
33 *  In:   input64: pointer to a 64-byte compact signature
34 *        recid:   the recovery id (0, 1, 2 or 3)
35 */
36SECP256K1_API int secp256k1_ecdsa_recoverable_signature_parse_compact(
37    const secp256k1_context *ctx,
38    secp256k1_ecdsa_recoverable_signature *sig,
39    const unsigned char *input64,
40    int recid
41) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
42
43/** Convert a recoverable signature into a normal signature.
44 *
45 *  Returns: 1
46 *  Args: ctx:    pointer to a context object.
47 *  Out:  sig:    pointer to a normal signature.
48 *  In:   sigin:  pointer to a recoverable signature.
49 */
50SECP256K1_API int secp256k1_ecdsa_recoverable_signature_convert(
51    const secp256k1_context *ctx,
52    secp256k1_ecdsa_signature *sig,
53    const secp256k1_ecdsa_recoverable_signature *sigin
54) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
55
56/** Serialize an ECDSA signature in compact format (64 bytes + recovery id).
57 *
58 *  Returns: 1
59 *  Args: ctx:      pointer to a context object.
60 *  Out:  output64: pointer to a 64-byte array of the compact signature.
61 *        recid:    pointer to an integer to hold the recovery id.
62 *  In:   sig:      pointer to an initialized signature object.
63 */
64SECP256K1_API int secp256k1_ecdsa_recoverable_signature_serialize_compact(
65    const secp256k1_context *ctx,
66    unsigned char *output64,
67    int *recid,
68    const secp256k1_ecdsa_recoverable_signature *sig
69) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
70
71/** Create a recoverable ECDSA signature.
72 *
73 *  Returns: 1: signature created
74 *           0: the nonce generation function failed, or the secret key was invalid.
75 *  Args:    ctx:       pointer to a context object (not secp256k1_context_static).
76 *  Out:     sig:       pointer to a signature object.
77 *  In:      msghash32: the 32-byte message hash being signed.
78 *           seckey:    pointer to a 32-byte secret key.
79 *           noncefp:   pointer to a nonce generation function. If NULL,
80 *                      secp256k1_nonce_function_default is used.
81 *           ndata:     pointer to arbitrary data used by the nonce generation function
82 *                      (can be NULL for secp256k1_nonce_function_default).
83 */
84SECP256K1_API int secp256k1_ecdsa_sign_recoverable(
85    const secp256k1_context *ctx,
86    secp256k1_ecdsa_recoverable_signature *sig,
87    const unsigned char *msghash32,
88    const unsigned char *seckey,
89    secp256k1_nonce_function noncefp,
90    const void *ndata
91) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
92
93/** Recover an ECDSA public key from a signature.
94 *
95 *  Successful public key recovery guarantees that the signature, after normalization,
96 *  passes `secp256k1_ecdsa_verify`. Thus, explicit verification is not necessary.
97 *
98 *  However, a recoverable signature that successfully passes `secp256k1_ecdsa_recover`,
99 *  when converted to a non-recoverable signature (using
100 *  `secp256k1_ecdsa_recoverable_signature_convert`), is not guaranteed to be
101 *  normalized and thus not guaranteed to pass `secp256k1_ecdsa_verify`. If a
102 *  normalized signature is required, call `secp256k1_ecdsa_signature_normalize`
103 *  after `secp256k1_ecdsa_recoverable_signature_convert`.
104 *
105 *  Returns: 1: public key successfully recovered
106 *           0: otherwise.
107 *  Args:    ctx:       pointer to a context object.
108 *  Out:     pubkey:    pointer to the recovered public key.
109 *  In:      sig:       pointer to initialized signature that supports pubkey recovery.
110 *           msghash32: the 32-byte message hash assumed to be signed.
111 */
112SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_recover(
113    const secp256k1_context *ctx,
114    secp256k1_pubkey *pubkey,
115    const secp256k1_ecdsa_recoverable_signature *sig,
116    const unsigned char *msghash32
117) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
118
119#ifdef __cplusplus
120}
121#endif
122
123#endif /* SECP256K1_RECOVERY_H */
124