include/secp256k1.h

   1 #ifndef _SECP256K1_
   2 # define _SECP256K1_
   3
   4 # ifdef __cplusplus
   5 extern "C" {
   6 # endif
   7
   8 # if !defined(SECP256K1_GNUC_PREREQ)
   9 #  if defined(__GNUC__)&&defined(__GNUC_MINOR__)
  10 #   define SECP256K1_GNUC_PREREQ(_maj,_min) \
  11  ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min))
  12 #  else
  13 #   define SECP256K1_GNUC_PREREQ(_maj,_min) 0
  14 #  endif
  15 # endif
  16
  17 # if (!defined(__STDC_VERSION__) || (__STDC_VERSION__ < 199901L) )
  18 #  if SECP256K1_GNUC_PREREQ(2,7)
  19 #   define SECP256K1_INLINE __inline__
  20 #  elif (defined(_MSC_VER))
  21 #   define SECP256K1_INLINE __inline
  22 #  else
  23 #   define SECP256K1_INLINE
  24 #  endif
  25 # else
  26 #  define SECP256K1_INLINE inline
  27 # endif
  28
  29 /**Warning attributes
  30   * NONNULL is not used if SECP256K1_BUILD is set to avoid the compiler optimizing out
  31   * some paranoid null checks. */
  32 # if defined(__GNUC__) && SECP256K1_GNUC_PREREQ(3, 4)
  33 #  define SECP256K1_WARN_UNUSED_RESULT __attribute__ ((__warn_unused_result__))
  34 # else
  35 #  define SECP256K1_WARN_UNUSED_RESULT
  36 # endif
  37 # if !defined(SECP256K1_BUILD) && defined(__GNUC__) && SECP256K1_GNUC_PREREQ(3, 4)
  38 #  define SECP256K1_ARG_NONNULL(_x)  __attribute__ ((__nonnull__(_x)))
  39 # else
  40 #  define SECP256K1_ARG_NONNULL(_x)
  41 # endif
  42
  43 /** Opaque data structure that holds context information (precomputed tables etc.).
  44  *  Only functions that take a pointer to a non-const context require exclusive
  45  *  access to it. Multiple functions that take a pointer to a const context may
  46  *  run simultaneously.
  47  */
  48 typedef struct secp256k1_context_struct secp256k1_context_t;
  49
  50 /** Flags to pass to secp256k1_context_create. */
  51 # define SECP256K1_CONTEXT_VERIFY (1 << 0)
  52 # define SECP256K1_CONTEXT_SIGN   (1 << 1)
  53
  54 /** Create a secp256k1 context object.
  55  *  Returns: a newly created context object.
  56  *  In:      flags: which parts of the context to initialize.
  57  */
  58 secp256k1_context_t* secp256k1_context_create(
  59   int flags
  60 ) SECP256K1_WARN_UNUSED_RESULT;
  61
  62 /** Copies a secp256k1 context object.
  63  *  Returns: a newly created context object.
  64  *  In:      ctx: an existing context to copy
  65  */
  66 secp256k1_context_t* secp256k1_context_clone(
  67   const secp256k1_context_t* ctx
  68 ) SECP256K1_WARN_UNUSED_RESULT;
  69
  70 /** Destroy a secp256k1 context object.
  71  *  The context pointer may not be used afterwards.
  72  */
  73 void secp256k1_context_destroy(
  74   secp256k1_context_t* ctx
  75 ) SECP256K1_ARG_NONNULL(1);
  76
  77 /** Set a callback function to be called when an illegal argument is passed to
  78  *  an API call. The philosophy is that these shouldn't be dealt with through a
  79  *  specific return value, as calling code should not have branches to deal with
  80  *  the case that this code itself is broken.
  81  *  On the other hand, during debug stage, one would want to be informed about
  82  *  such mistakes, and the default (crashing) may be inadvisable.
  83  *  When this callback is triggered, the API function called is guaranteed not
  84  *  to cause a crash, though its return value and output arguments are
  85  *  undefined.
  86  */
  87 void secp256k1_context_set_illegal_callback(
  88   secp256k1_context_t* ctx,
  89   void (*fun)(const char* message, void* data),
  90   void* data
  91 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
  92
  93 /** Set a callback function to be called when an internal consistency check
  94  *  fails. The default is crashing.
  95  *  This can only trigger in case of a hardware failure, miscompilation,
  96  *  memory corruption, serious bug in the library, or other error would can
  97  *  otherwise result in undefined behaviour. It will not trigger due to mere
  98  *  incorrect usage of the API (see secp256k1_context_set_illegal_callback
  99  *  for that). After this callback returns, anything may happen, including
 100  *  crashing.
 101  */
 102 void secp256k1_context_set_error_callback(
 103   secp256k1_context_t* ctx,
 104   void (*fun)(const char* message, void* data),
 105   void* data
 106 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
 107
 108 /** Data type to hold a parsed and valid public key.
 109     This data type should be considered opaque to the user, and only created
 110     through API functions. It is not guaranteed to be compatible between
 111     different implementations. If you need to convert to a format suitable
 112     for storage or transmission, use secp256k1_ec_pubkey_serialize and
 113     secp256k1_ec_pubkey_parse.
 114  */
 115 typedef struct {
 116   unsigned char data[64];
 117 } secp256k1_pubkey_t;
 118
 119 /** Parse a variable-length public key into the pubkey object.
 120  *  Returns: 1 if the public key was fully valid.
 121  *           0 if the public key could not be parsed or is invalid.
 122  *  In:  ctx:      a secp256k1 context object.
 123  *       input:    pointer to a serialized public key
 124  *       inputlen: length of the array pointed to by input
 125  *  Out: pubkey:   pointer to a pubkey object. If 1 is returned, it is set to a
 126  *                 parsed version of input. If not, its value is undefined.
 127  *  This function supports parsing compressed (33 bytes, header byte 0x02 or
 128  *  0x03), uncompressed (65 bytes, header byte 0x04), or hybrid (65 bytes, header
 129  *  byte 0x06 or 0x07) format public keys.
 130  */
 131 SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_parse(
 132   const secp256k1_context_t* ctx,
 133   secp256k1_pubkey_t* pubkey,
 134   const unsigned char *input,
 135   int inputlen
 136 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 137
 138 /** Serialize a pubkey object into a serialized byte sequence.
 139  *  Returns: 1 always.
 140  *  In:   ctx:        a secp256k1 context object.
 141  *        pubkey:     a pointer to a secp256k1_pubkey_t containing an initialized
 142  *                    public key.
 143  *        compressed: whether to serialize in compressed format.
 144  *  Out:  output:     a pointer to a 65-byte (if compressed==0) or 33-byte (if
 145  *                    compressed==1) byte array to place the serialized key in.
 146  *        outputlen:  a pointer to an integer which will contain the serialized
 147  *                    size.
 148  */
 149 int secp256k1_ec_pubkey_serialize(
 150   const secp256k1_context_t* ctx,
 151   unsigned char *output,
 152   int *outputlen,
 153   const secp256k1_pubkey_t* pubkey,
 154   int compressed
 155 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 156
 157 /** Data type to hold a parsed ECDSA signature, optionally supporting pubkey
 158  *  recovery.
 159     This data type should be considered opaque to the user, and only created
 160     through API functions. It is not guaranteed to be compatible between
 161     different implementations. If you need to convert to a format suitable
 162     for storage or transmission, use secp256k1_ecdsa_signature_serialize_* and
 163     secp256k1_ecdsa_signature_parse_* functions. */
 164 typedef struct {
 165   unsigned char data[65];
 166 } secp256k1_ecdsa_signature_t;
 167
 168 /** Parse a DER ECDSA signature.
 169  *  Returns: 1 when the signature could be parsed, 0 otherwise.
 170  *  In:  ctx:      a secp256k1 context object
 171  *       input:    a pointer to the signature to be parsed
 172  *       inputlen: the length of the array pointed to be input
 173  *  Out: sig:      a pointer to a signature object
 174  *
 175  *  Note that this function also supports some violations of DER.
 176  *
 177  *  The resulting signature object will not support pubkey recovery.
 178  */
 179 int secp256k1_ecdsa_signature_parse_der(
 180   const secp256k1_context_t* ctx,
 181   secp256k1_ecdsa_signature_t* sig,
 182   const unsigned char *input,
 183   int inputlen
 184 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 185
 186 /** Parse a compact ECDSA signature (64 bytes + recovery id).
 187  *  Returns: 1 when the signature could be parsed, 0 otherwise
 188  *  In:  ctx:     a secp256k1 context object
 189  *       input64: a pointer to a 64-byte compact signature
 190  *       recid:   the recovery id (0, 1, 2 or 3, or -1 for unknown)
 191  *  Out: sig:     a pointer to a signature object
 192  *
 193  *  If recid is not -1, the resulting signature object will support pubkey
 194  *  recovery.
 195  */
 196 int secp256k1_ecdsa_signature_parse_compact(
 197   const secp256k1_context_t* ctx,
 198   secp256k1_ecdsa_signature_t* sig,
 199   const unsigned char *input64,
 200   int recid
 201 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 202
 203 /** Serialize an ECDSA signature in DER format.
 204  *  Returns: 1 if enough space was available to serialize, 0 otherwise
 205  *  In:     ctx:       a secp256k1 context object
 206  *          sig:       a pointer to an initialized signature object
 207  *  Out:    output:    a pointer to an array to store the DER serialization
 208  *  In/Out: outputlen: a pointer to a length integer. Initially, this integer
 209  *                     should be set to the length of output. After the call
 210  *                     it will be set to the length of the serialization (even
 211  *                     if 0 was returned).
 212  */
 213 int secp256k1_ecdsa_signature_serialize_der(
 214   const secp256k1_context_t* ctx,
 215   unsigned char *output,
 216   int *outputlen,
 217   const secp256k1_ecdsa_signature_t* sig
 218 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 219
 220 /** Serialize an ECDSA signature in compact format (64 bytes + recovery id).
 221  *  Returns: 1
 222  *  In: ctx:       a secp256k1 context object
 223  *      sig:       a pointer to an initialized signature object (cannot be NULL)
 224  *  Out: output64: a pointer to a 64-byte array of the compact signature (cannot be NULL)
 225  *       recid:    a pointer to an integer to hold the recovery id (can be NULL).
 226  *
 227  *  If recid is not NULL, the signature must support pubkey recovery.
 228  */
 229 int secp256k1_ecdsa_signature_serialize_compact(
 230   const secp256k1_context_t* ctx,
 231   unsigned char *output64,
 232   int *recid,
 233   const secp256k1_ecdsa_signature_t* sig
 234 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(4);
 235
 236 /** Verify an ECDSA signature.
 237  *  Returns: 1: correct signature
 238  *           0: incorrect or unparseable signature
 239  * In:       ctx:       a secp256k1 context object, initialized for verification.
 240  *           msg32:     the 32-byte message hash being verified (cannot be NULL)
 241  *           sig:       the signature being verified (cannot be NULL)
 242  *           pubkey:    pointer to an initialized public key to verify with (cannot be NULL)
 243  */
 244 SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_verify(
 245   const secp256k1_context_t* ctx,
 246   const unsigned char *msg32,
 247   const secp256k1_ecdsa_signature_t *sig,
 248   const secp256k1_pubkey_t *pubkey
 249 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 250
 251 /** A pointer to a function to deterministically generate a nonce.
 252  * Returns: 1 if a nonce was successfully generated. 0 will cause signing to fail.
 253  * In:      msg32:     the 32-byte message hash being verified (will not be NULL)
 254  *          key32:     pointer to a 32-byte secret key (will not be NULL)
 255  *          attempt:   how many iterations we have tried to find a nonce.
 256  *                     This will almost always be 0, but different attempt values
 257  *                     are required to result in a different nonce.
 258  *          data:      Arbitrary data pointer that is passed through.
 259  * Out:     nonce32:   pointer to a 32-byte array to be filled by the function.
 260  * Except for test cases, this function should compute some cryptographic hash of
 261  * the message, the key and the attempt.
 262  */
 263 typedef int (*secp256k1_nonce_function_t)(
 264   unsigned char *nonce32,
 265   const unsigned char *msg32,
 266   const unsigned char *key32,
 267   unsigned int attempt,
 268   const void *data
 269 );
 270
 271 /** An implementation of RFC6979 (using HMAC-SHA256) as nonce generation function.
 272  * If a data pointer is passed, it is assumed to be a pointer to 32 bytes of
 273  * extra entropy.
 274  */
 275 extern const secp256k1_nonce_function_t secp256k1_nonce_function_rfc6979;
 276
 277 /** A default safe nonce generation function (currently equal to secp256k1_nonce_function_rfc6979). */
 278 extern const secp256k1_nonce_function_t secp256k1_nonce_function_default;
 279
 280 /** Create an ECDSA signature.
 281  *  Returns: 1: signature created
 282  *           0: the nonce generation function failed, or the private key was invalid.
 283  *  In:      ctx:    pointer to a context object, initialized for signing (cannot be NULL)
 284  *           msg32:  the 32-byte message hash being signed (cannot be NULL)
 285  *           seckey: pointer to a 32-byte secret key (cannot be NULL)
 286  *           noncefp:pointer to a nonce generation function. If NULL, secp256k1_nonce_function_default is used
 287  *           ndata:  pointer to arbitrary data used by the nonce generation function (can be NULL)
 288  *  Out:     sig:    pointer to an array where the signature will be placed (cannot be NULL)
 289  *
 290  * The resulting signature will support pubkey recovery.
 291  *
 292  * The sig always has an s value in the lower half of the range (From 0x1
 293  * to 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0,
 294  * inclusive), unlike many other implementations.
 295  * With ECDSA a third-party can can forge a second distinct signature
 296  * of the same message given a single initial signature without knowing
 297  * the key by setting s to its additive inverse mod-order, 'flipping' the
 298  * sign of the random point R which is not included in the signature.
 299  * Since the forgery is of the same message this isn't universally
 300  * problematic, but in systems where message malleability or uniqueness
 301  * of signatures is important this can cause issues.  This forgery can be
 302  * blocked by all verifiers forcing signers to use a canonical form. The
 303  * lower-S form reduces the size of signatures slightly on average when
 304  * variable length encodings (such as DER) are used and is cheap to
 305  * verify, making it a good choice. Security of always using lower-S is
 306  * assured because anyone can trivially modify a signature after the
 307  * fact to enforce this property.  Adjusting it inside the signing
 308  * function avoids the need to re-serialize or have curve specific
 309  * constants outside of the library.  By always using a canonical form
 310  * even in applications where it isn't needed it becomes possible to
 311  * impose a requirement later if a need is discovered.
 312  * No other forms of ECDSA malleability are known and none seem likely,
 313  * but there is no formal proof that ECDSA, even with this additional
 314  * restriction, is free of other malleability.  Commonly used serialization
 315  * schemes will also accept various non-unique encodings, so care should
 316  * be taken when this property is required for an application.
 317  */
 318 int secp256k1_ecdsa_sign(
 319   const secp256k1_context_t* ctx,
 320   const unsigned char *msg32,
 321   secp256k1_ecdsa_signature_t *sig,
 322   const unsigned char *seckey,
 323   secp256k1_nonce_function_t noncefp,
 324   const void *ndata
 325 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 326
 327 /** Recover an ECDSA public key from a signature.
 328  *  Returns: 1: public key successfully recovered (which guarantees a correct signature).
 329  *           0: otherwise.
 330  *  In:      ctx:        pointer to a context object, initialized for verification (cannot be NULL)
 331  *           msg32:      the 32-byte message hash assumed to be signed (cannot be NULL)
 332  *           sig64:      pointer to initialized signature that supports pubkey recovery (cannot be NULL)
 333  *  Out:     pubkey:     pointer to the recoved public key (cannot be NULL)
 334  */
 335 SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_recover(
 336   const secp256k1_context_t* ctx,
 337   const unsigned char *msg32,
 338   const secp256k1_ecdsa_signature_t *sig,
 339   secp256k1_pubkey_t *pubkey
 340 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 341
 342 /** Verify an ECDSA secret key.
 343  *  Returns: 1: secret key is valid
 344  *           0: secret key is invalid
 345  *  In:      ctx: pointer to a context object (cannot be NULL)
 346  *           seckey: pointer to a 32-byte secret key (cannot be NULL)
 347  */
 348 SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_verify(
 349   const secp256k1_context_t* ctx,
 350   const unsigned char *seckey
 351 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
 352
 353 /** Compute the public key for a secret key.
 354  *  In:     ctx:        pointer to a context object, initialized for signing (cannot be NULL)
 355  *          seckey:     pointer to a 32-byte private key (cannot be NULL)
 356  *  Out:    pubkey:     pointer to the created public key (cannot be NULL)
 357  *  Returns: 1: secret was valid, public key stores
 358  *           0: secret was invalid, try again
 359  */
 360 SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_create(
 361   const secp256k1_context_t* ctx,
 362   secp256k1_pubkey_t *pubkey,
 363   const unsigned char *seckey
 364 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 365
 366 /** Export a private key in DER format.
 367  * In: ctx: pointer to a context object, initialized for signing (cannot be NULL)
 368  */
 369 SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_export(
 370   const secp256k1_context_t* ctx,
 371   const unsigned char *seckey,
 372   unsigned char *privkey,
 373   int *privkeylen,
 374   int compressed
 375 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 376
 377 /** Import a private key in DER format. */
 378 SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_import(
 379   const secp256k1_context_t* ctx,
 380   unsigned char *seckey,
 381   const unsigned char *privkey,
 382   int privkeylen
 383 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 384
 385 /** Tweak a private key by adding tweak to it. */
 386 SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_add(
 387   const secp256k1_context_t* ctx,
 388   unsigned char *seckey,
 389   const unsigned char *tweak
 390 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 391
 392 /** Tweak a public key by adding tweak times the generator to it.
 393  * In: ctx: pointer to a context object, initialized for verification (cannot be NULL)
 394  */
 395 SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_add(
 396   const secp256k1_context_t* ctx,
 397   secp256k1_pubkey_t *pubkey,
 398   const unsigned char *tweak
 399 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 400
 401 /** Tweak a private key by multiplying it with tweak. */
 402 SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_mul(
 403   const secp256k1_context_t* ctx,
 404   unsigned char *seckey,
 405   const unsigned char *tweak
 406 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 407
 408 /** Tweak a public key by multiplying it with tweak.
 409  * In: ctx: pointer to a context object, initialized for verification (cannot be NULL)
 410  */
 411 SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_mul(
 412   const secp256k1_context_t* ctx,
 413   secp256k1_pubkey_t *pubkey,
 414   const unsigned char *tweak
 415 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 416
 417 /** Updates the context randomization.
 418  *  Returns: 1: randomization successfully updated
 419  *           0: error
 420  *  In:      ctx:       pointer to a context object (cannot be NULL)
 421  *           seed32:    pointer to a 32-byte random seed (NULL resets to initial state)
 422  */
 423 SECP256K1_WARN_UNUSED_RESULT int secp256k1_context_randomize(
 424   secp256k1_context_t* ctx,
 425   const unsigned char *seed32
 426 ) SECP256K1_ARG_NONNULL(1);
 427
 428
 429 # ifdef __cplusplus
 430 }
 431 # endif
 432
 433 #endif