Branch data Line data Source code
# 1 : : #ifndef SECP256K1_H
# 2 : : #define SECP256K1_H
# 3 : :
# 4 : : #ifdef __cplusplus
# 5 : : extern "C" {
# 6 : : #endif
# 7 : :
# 8 : : #include <stddef.h>
# 9 : :
# 10 : : /* These rules specify the order of arguments in API calls:
# 11 : : *
# 12 : : * 1. Context pointers go first, followed by output arguments, combined
# 13 : : * output/input arguments, and finally input-only arguments.
# 14 : : * 2. Array lengths always immediately the follow the argument whose length
# 15 : : * they describe, even if this violates rule 1.
# 16 : : * 3. Within the OUT/OUTIN/IN groups, pointers to data that is typically generated
# 17 : : * later go first. This means: signatures, public nonces, secret nonces,
# 18 : : * messages, public keys, secret keys, tweaks.
# 19 : : * 4. Arguments that are not data pointers go last, from more complex to less
# 20 : : * complex: function pointers, algorithm names, messages, void pointers,
# 21 : : * counts, flags, booleans.
# 22 : : * 5. Opaque data pointers follow the function pointer they are to be passed to.
# 23 : : */
# 24 : :
# 25 : : /** Opaque data structure that holds context information (precomputed tables etc.).
# 26 : : *
# 27 : : * The purpose of context structures is to cache large precomputed data tables
# 28 : : * that are expensive to construct, and also to maintain the randomization data
# 29 : : * for blinding.
# 30 : : *
# 31 : : * Do not create a new context object for each operation, as construction is
# 32 : : * far slower than all other API calls (~100 times slower than an ECDSA
# 33 : : * verification).
# 34 : : *
# 35 : : * A constructed context can safely be used from multiple threads
# 36 : : * simultaneously, but API calls that take a non-const pointer to a context
# 37 : : * need exclusive access to it. In particular this is the case for
# 38 : : * secp256k1_context_destroy, secp256k1_context_preallocated_destroy,
# 39 : : * and secp256k1_context_randomize.
# 40 : : *
# 41 : : * Regarding randomization, either do it once at creation time (in which case
# 42 : : * you do not need any locking for the other calls), or use a read-write lock.
# 43 : : */
# 44 : : typedef struct secp256k1_context_struct secp256k1_context;
# 45 : :
# 46 : : /** Opaque data structure that holds rewriteable "scratch space"
# 47 : : *
# 48 : : * The purpose of this structure is to replace dynamic memory allocations,
# 49 : : * because we target architectures where this may not be available. It is
# 50 : : * essentially a resizable (within specified parameters) block of bytes,
# 51 : : * which is initially created either by memory allocation or TODO as a pointer
# 52 : : * into some fixed rewritable space.
# 53 : : *
# 54 : : * Unlike the context object, this cannot safely be shared between threads
# 55 : : * without additional synchronization logic.
# 56 : : */
# 57 : : typedef struct secp256k1_scratch_space_struct secp256k1_scratch_space;
# 58 : :
# 59 : : /** Opaque data structure that holds a parsed and valid public key.
# 60 : : *
# 61 : : * The exact representation of data inside is implementation defined and not
# 62 : : * guaranteed to be portable between different platforms or versions. It is
# 63 : : * however guaranteed to be 64 bytes in size, and can be safely copied/moved.
# 64 : : * If you need to convert to a format suitable for storage, transmission, or
# 65 : : * comparison, use secp256k1_ec_pubkey_serialize and secp256k1_ec_pubkey_parse.
# 66 : : */
# 67 : : typedef struct {
# 68 : : unsigned char data[64];
# 69 : : } secp256k1_pubkey;
# 70 : :
# 71 : : /** Opaque data structured that holds a parsed ECDSA signature.
# 72 : : *
# 73 : : * The exact representation of data inside is implementation defined and not
# 74 : : * guaranteed to be portable between different platforms or versions. It is
# 75 : : * however guaranteed to be 64 bytes in size, and can be safely copied/moved.
# 76 : : * If you need to convert to a format suitable for storage, transmission, or
# 77 : : * comparison, use the secp256k1_ecdsa_signature_serialize_* and
# 78 : : * secp256k1_ecdsa_signature_parse_* functions.
# 79 : : */
# 80 : : typedef struct {
# 81 : : unsigned char data[64];
# 82 : : } secp256k1_ecdsa_signature;
# 83 : :
# 84 : : /** A pointer to a function to deterministically generate a nonce.
# 85 : : *
# 86 : : * Returns: 1 if a nonce was successfully generated. 0 will cause signing to fail.
# 87 : : * Out: nonce32: pointer to a 32-byte array to be filled by the function.
# 88 : : * In: msg32: the 32-byte message hash being verified (will not be NULL)
# 89 : : * key32: pointer to a 32-byte secret key (will not be NULL)
# 90 : : * algo16: pointer to a 16-byte array describing the signature
# 91 : : * algorithm (will be NULL for ECDSA for compatibility).
# 92 : : * data: Arbitrary data pointer that is passed through.
# 93 : : * attempt: how many iterations we have tried to find a nonce.
# 94 : : * This will almost always be 0, but different attempt values
# 95 : : * are required to result in a different nonce.
# 96 : : *
# 97 : : * Except for test cases, this function should compute some cryptographic hash of
# 98 : : * the message, the algorithm, the key and the attempt.
# 99 : : */
# 100 : : typedef int (*secp256k1_nonce_function)(
# 101 : : unsigned char *nonce32,
# 102 : : const unsigned char *msg32,
# 103 : : const unsigned char *key32,
# 104 : : const unsigned char *algo16,
# 105 : : void *data,
# 106 : : unsigned int attempt
# 107 : : );
# 108 : :
# 109 : : # if !defined(SECP256K1_GNUC_PREREQ)
# 110 : : # if defined(__GNUC__)&&defined(__GNUC_MINOR__)
# 111 : : # define SECP256K1_GNUC_PREREQ(_maj,_min) \
# 112 : : ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min))
# 113 : : # else
# 114 : : # define SECP256K1_GNUC_PREREQ(_maj,_min) 0
# 115 : : # endif
# 116 : : # endif
# 117 : :
# 118 : : # if (!defined(__STDC_VERSION__) || (__STDC_VERSION__ < 199901L) )
# 119 : : # if SECP256K1_GNUC_PREREQ(2,7)
# 120 : : # define SECP256K1_INLINE __inline__
# 121 : : # elif (defined(_MSC_VER))
# 122 : : # define SECP256K1_INLINE __inline
# 123 : : # else
# 124 : : # define SECP256K1_INLINE
# 125 : : # endif
# 126 : : # else
# 127 : : # define SECP256K1_INLINE inline
# 128 : : # endif
# 129 : :
# 130 : : #ifndef SECP256K1_API
# 131 : : # if defined(_WIN32)
# 132 : : # ifdef SECP256K1_BUILD
# 133 : : # define SECP256K1_API __declspec(dllexport)
# 134 : : # else
# 135 : : # define SECP256K1_API
# 136 : : # endif
# 137 : : # elif defined(__GNUC__) && (__GNUC__ >= 4) && defined(SECP256K1_BUILD)
# 138 : : # define SECP256K1_API __attribute__ ((visibility ("default")))
# 139 : : # else
# 140 : : # define SECP256K1_API
# 141 : : # endif
# 142 : : #endif
# 143 : :
# 144 : : /**Warning attributes
# 145 : : * NONNULL is not used if SECP256K1_BUILD is set to avoid the compiler optimizing out
# 146 : : * some paranoid null checks. */
# 147 : : # if defined(__GNUC__) && SECP256K1_GNUC_PREREQ(3, 4)
# 148 : : # define SECP256K1_WARN_UNUSED_RESULT __attribute__ ((__warn_unused_result__))
# 149 : : # else
# 150 : : # define SECP256K1_WARN_UNUSED_RESULT
# 151 : : # endif
# 152 : : # if !defined(SECP256K1_BUILD) && defined(__GNUC__) && SECP256K1_GNUC_PREREQ(3, 4)
# 153 : : # define SECP256K1_ARG_NONNULL(_x) __attribute__ ((__nonnull__(_x)))
# 154 : : # else
# 155 : : # define SECP256K1_ARG_NONNULL(_x)
# 156 : : # endif
# 157 : :
# 158 : : /** All flags' lower 8 bits indicate what they're for. Do not use directly. */
# 159 : : #define SECP256K1_FLAGS_TYPE_MASK ((1 << 8) - 1)
# 160 : 2284 : #define SECP256K1_FLAGS_TYPE_CONTEXT (1 << 0)
# 161 : 1813452 : #define SECP256K1_FLAGS_TYPE_COMPRESSION (1 << 1)
# 162 : : /** The higher bits contain the actual data. Do not use directly. */
# 163 : 719 : #define SECP256K1_FLAGS_BIT_CONTEXT_VERIFY (1 << 8)
# 164 : 1565 : #define SECP256K1_FLAGS_BIT_CONTEXT_SIGN (1 << 9)
# 165 : : #define SECP256K1_FLAGS_BIT_CONTEXT_DECLASSIFY (1 << 10)
# 166 : 1808263 : #define SECP256K1_FLAGS_BIT_COMPRESSION (1 << 8)
# 167 : :
# 168 : : /** Flags to pass to secp256k1_context_create, secp256k1_context_preallocated_size, and
# 169 : : * secp256k1_context_preallocated_create. */
# 170 : 719 : #define SECP256K1_CONTEXT_VERIFY (SECP256K1_FLAGS_TYPE_CONTEXT | SECP256K1_FLAGS_BIT_CONTEXT_VERIFY)
# 171 : 1565 : #define SECP256K1_CONTEXT_SIGN (SECP256K1_FLAGS_TYPE_CONTEXT | SECP256K1_FLAGS_BIT_CONTEXT_SIGN)
# 172 : : #define SECP256K1_CONTEXT_DECLASSIFY (SECP256K1_FLAGS_TYPE_CONTEXT | SECP256K1_FLAGS_BIT_CONTEXT_DECLASSIFY)
# 173 : : #define SECP256K1_CONTEXT_NONE (SECP256K1_FLAGS_TYPE_CONTEXT)
# 174 : :
# 175 : : /** Flag to pass to secp256k1_ec_pubkey_serialize. */
# 176 : 1808263 : #define SECP256K1_EC_COMPRESSED (SECP256K1_FLAGS_TYPE_COMPRESSION | SECP256K1_FLAGS_BIT_COMPRESSION)
# 177 : 1448355 : #define SECP256K1_EC_UNCOMPRESSED (SECP256K1_FLAGS_TYPE_COMPRESSION)
# 178 : :
# 179 : : /** Prefix byte used to tag various encoded curvepoints for specific purposes */
# 180 : : #define SECP256K1_TAG_PUBKEY_EVEN 0x02
# 181 : : #define SECP256K1_TAG_PUBKEY_ODD 0x03
# 182 : : #define SECP256K1_TAG_PUBKEY_UNCOMPRESSED 0x04
# 183 : : #define SECP256K1_TAG_PUBKEY_HYBRID_EVEN 0x06
# 184 : : #define SECP256K1_TAG_PUBKEY_HYBRID_ODD 0x07
# 185 : :
# 186 : : /** A simple secp256k1 context object with no precomputed tables. These are useful for
# 187 : : * type serialization/parsing functions which require a context object to maintain
# 188 : : * API consistency, but currently do not require expensive precomputations or dynamic
# 189 : : * allocations.
# 190 : : */
# 191 : : SECP256K1_API extern const secp256k1_context *secp256k1_context_no_precomp;
# 192 : :
# 193 : : /** Create a secp256k1 context object (in dynamically allocated memory).
# 194 : : *
# 195 : : * This function uses malloc to allocate memory. It is guaranteed that malloc is
# 196 : : * called at most once for every call of this function. If you need to avoid dynamic
# 197 : : * memory allocation entirely, see the functions in secp256k1_preallocated.h.
# 198 : : *
# 199 : : * Returns: a newly created context object.
# 200 : : * In: flags: which parts of the context to initialize.
# 201 : : *
# 202 : : * See also secp256k1_context_randomize.
# 203 : : */
# 204 : : SECP256K1_API secp256k1_context* secp256k1_context_create(
# 205 : : unsigned int flags
# 206 : : ) SECP256K1_WARN_UNUSED_RESULT;
# 207 : :
# 208 : : /** Copy a secp256k1 context object (into dynamically allocated memory).
# 209 : : *
# 210 : : * This function uses malloc to allocate memory. It is guaranteed that malloc is
# 211 : : * called at most once for every call of this function. If you need to avoid dynamic
# 212 : : * memory allocation entirely, see the functions in secp256k1_preallocated.h.
# 213 : : *
# 214 : : * Returns: a newly created context object.
# 215 : : * Args: ctx: an existing context to copy (cannot be NULL)
# 216 : : */
# 217 : : SECP256K1_API secp256k1_context* secp256k1_context_clone(
# 218 : : const secp256k1_context* ctx
# 219 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_WARN_UNUSED_RESULT;
# 220 : :
# 221 : : /** Destroy a secp256k1 context object (created in dynamically allocated memory).
# 222 : : *
# 223 : : * The context pointer may not be used afterwards.
# 224 : : *
# 225 : : * The context to destroy must have been created using secp256k1_context_create
# 226 : : * or secp256k1_context_clone. If the context has instead been created using
# 227 : : * secp256k1_context_preallocated_create or secp256k1_context_preallocated_clone, the
# 228 : : * behaviour is undefined. In that case, secp256k1_context_preallocated_destroy must
# 229 : : * be used instead.
# 230 : : *
# 231 : : * Args: ctx: an existing context to destroy, constructed using
# 232 : : * secp256k1_context_create or secp256k1_context_clone
# 233 : : */
# 234 : : SECP256K1_API void secp256k1_context_destroy(
# 235 : : secp256k1_context* ctx
# 236 : : );
# 237 : :
# 238 : : /** Set a callback function to be called when an illegal argument is passed to
# 239 : : * an API call. It will only trigger for violations that are mentioned
# 240 : : * explicitly in the header.
# 241 : : *
# 242 : : * The philosophy is that these shouldn't be dealt with through a
# 243 : : * specific return value, as calling code should not have branches to deal with
# 244 : : * the case that this code itself is broken.
# 245 : : *
# 246 : : * On the other hand, during debug stage, one would want to be informed about
# 247 : : * such mistakes, and the default (crashing) may be inadvisable.
# 248 : : * When this callback is triggered, the API function called is guaranteed not
# 249 : : * to cause a crash, though its return value and output arguments are
# 250 : : * undefined.
# 251 : : *
# 252 : : * When this function has not been called (or called with fn==NULL), then the
# 253 : : * default handler will be used. The library provides a default handler which
# 254 : : * writes the message to stderr and calls abort. This default handler can be
# 255 : : * replaced at link time if the preprocessor macro
# 256 : : * USE_EXTERNAL_DEFAULT_CALLBACKS is defined, which is the case if the build
# 257 : : * has been configured with --enable-external-default-callbacks. Then the
# 258 : : * following two symbols must be provided to link against:
# 259 : : * - void secp256k1_default_illegal_callback_fn(const char* message, void* data);
# 260 : : * - void secp256k1_default_error_callback_fn(const char* message, void* data);
# 261 : : * The library can call these default handlers even before a proper callback data
# 262 : : * pointer could have been set using secp256k1_context_set_illegal_callback or
# 263 : : * secp256k1_context_set_error_callback, e.g., when the creation of a context
# 264 : : * fails. In this case, the corresponding default handler will be called with
# 265 : : * the data pointer argument set to NULL.
# 266 : : *
# 267 : : * Args: ctx: an existing context object (cannot be NULL)
# 268 : : * In: fun: a pointer to a function to call when an illegal argument is
# 269 : : * passed to the API, taking a message and an opaque pointer.
# 270 : : * (NULL restores the default handler.)
# 271 : : * data: the opaque pointer to pass to fun above.
# 272 : : *
# 273 : : * See also secp256k1_context_set_error_callback.
# 274 : : */
# 275 : : SECP256K1_API void secp256k1_context_set_illegal_callback(
# 276 : : secp256k1_context* ctx,
# 277 : : void (*fun)(const char* message, void* data),
# 278 : : const void* data
# 279 : : ) SECP256K1_ARG_NONNULL(1);
# 280 : :
# 281 : : /** Set a callback function to be called when an internal consistency check
# 282 : : * fails. The default is crashing.
# 283 : : *
# 284 : : * This can only trigger in case of a hardware failure, miscompilation,
# 285 : : * memory corruption, serious bug in the library, or other error would can
# 286 : : * otherwise result in undefined behaviour. It will not trigger due to mere
# 287 : : * incorrect usage of the API (see secp256k1_context_set_illegal_callback
# 288 : : * for that). After this callback returns, anything may happen, including
# 289 : : * crashing.
# 290 : : *
# 291 : : * Args: ctx: an existing context object (cannot be NULL)
# 292 : : * In: fun: a pointer to a function to call when an internal error occurs,
# 293 : : * taking a message and an opaque pointer (NULL restores the
# 294 : : * default handler, see secp256k1_context_set_illegal_callback
# 295 : : * for details).
# 296 : : * data: the opaque pointer to pass to fun above.
# 297 : : *
# 298 : : * See also secp256k1_context_set_illegal_callback.
# 299 : : */
# 300 : : SECP256K1_API void secp256k1_context_set_error_callback(
# 301 : : secp256k1_context* ctx,
# 302 : : void (*fun)(const char* message, void* data),
# 303 : : const void* data
# 304 : : ) SECP256K1_ARG_NONNULL(1);
# 305 : :
# 306 : : /** Create a secp256k1 scratch space object.
# 307 : : *
# 308 : : * Returns: a newly created scratch space.
# 309 : : * Args: ctx: an existing context object (cannot be NULL)
# 310 : : * In: size: amount of memory to be available as scratch space. Some extra
# 311 : : * (<100 bytes) will be allocated for extra accounting.
# 312 : : */
# 313 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT secp256k1_scratch_space* secp256k1_scratch_space_create(
# 314 : : const secp256k1_context* ctx,
# 315 : : size_t size
# 316 : : ) SECP256K1_ARG_NONNULL(1);
# 317 : :
# 318 : : /** Destroy a secp256k1 scratch space.
# 319 : : *
# 320 : : * The pointer may not be used afterwards.
# 321 : : * Args: ctx: a secp256k1 context object.
# 322 : : * scratch: space to destroy
# 323 : : */
# 324 : : SECP256K1_API void secp256k1_scratch_space_destroy(
# 325 : : const secp256k1_context* ctx,
# 326 : : secp256k1_scratch_space* scratch
# 327 : : ) SECP256K1_ARG_NONNULL(1);
# 328 : :
# 329 : : /** Parse a variable-length public key into the pubkey object.
# 330 : : *
# 331 : : * Returns: 1 if the public key was fully valid.
# 332 : : * 0 if the public key could not be parsed or is invalid.
# 333 : : * Args: ctx: a secp256k1 context object.
# 334 : : * Out: pubkey: pointer to a pubkey object. If 1 is returned, it is set to a
# 335 : : * parsed version of input. If not, its value is undefined.
# 336 : : * In: input: pointer to a serialized public key
# 337 : : * inputlen: length of the array pointed to by input
# 338 : : *
# 339 : : * This function supports parsing compressed (33 bytes, header byte 0x02 or
# 340 : : * 0x03), uncompressed (65 bytes, header byte 0x04), or hybrid (65 bytes, header
# 341 : : * byte 0x06 or 0x07) format public keys.
# 342 : : */
# 343 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_parse(
# 344 : : const secp256k1_context* ctx,
# 345 : : secp256k1_pubkey* pubkey,
# 346 : : const unsigned char *input,
# 347 : : size_t inputlen
# 348 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
# 349 : :
# 350 : : /** Serialize a pubkey object into a serialized byte sequence.
# 351 : : *
# 352 : : * Returns: 1 always.
# 353 : : * Args: ctx: a secp256k1 context object.
# 354 : : * Out: output: a pointer to a 65-byte (if compressed==0) or 33-byte (if
# 355 : : * compressed==1) byte array to place the serialized key
# 356 : : * in.
# 357 : : * In/Out: outputlen: a pointer to an integer which is initially set to the
# 358 : : * size of output, and is overwritten with the written
# 359 : : * size.
# 360 : : * In: pubkey: a pointer to a secp256k1_pubkey containing an
# 361 : : * initialized public key.
# 362 : : * flags: SECP256K1_EC_COMPRESSED if serialization should be in
# 363 : : * compressed format, otherwise SECP256K1_EC_UNCOMPRESSED.
# 364 : : */
# 365 : : SECP256K1_API int secp256k1_ec_pubkey_serialize(
# 366 : : const secp256k1_context* ctx,
# 367 : : unsigned char *output,
# 368 : : size_t *outputlen,
# 369 : : const secp256k1_pubkey* pubkey,
# 370 : : unsigned int flags
# 371 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
# 372 : :
# 373 : : /** Parse an ECDSA signature in compact (64 bytes) format.
# 374 : : *
# 375 : : * Returns: 1 when the signature could be parsed, 0 otherwise.
# 376 : : * Args: ctx: a secp256k1 context object
# 377 : : * Out: sig: a pointer to a signature object
# 378 : : * In: input64: a pointer to the 64-byte array to parse
# 379 : : *
# 380 : : * The signature must consist of a 32-byte big endian R value, followed by a
# 381 : : * 32-byte big endian S value. If R or S fall outside of [0..order-1], the
# 382 : : * encoding is invalid. R and S with value 0 are allowed in the encoding.
# 383 : : *
# 384 : : * After the call, sig will always be initialized. If parsing failed or R or
# 385 : : * S are zero, the resulting sig value is guaranteed to fail validation for any
# 386 : : * message and public key.
# 387 : : */
# 388 : : SECP256K1_API int secp256k1_ecdsa_signature_parse_compact(
# 389 : : const secp256k1_context* ctx,
# 390 : : secp256k1_ecdsa_signature* sig,
# 391 : : const unsigned char *input64
# 392 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
# 393 : :
# 394 : : /** Parse a DER ECDSA signature.
# 395 : : *
# 396 : : * Returns: 1 when the signature could be parsed, 0 otherwise.
# 397 : : * Args: ctx: a secp256k1 context object
# 398 : : * Out: sig: a pointer to a signature object
# 399 : : * In: input: a pointer to the signature to be parsed
# 400 : : * inputlen: the length of the array pointed to be input
# 401 : : *
# 402 : : * This function will accept any valid DER encoded signature, even if the
# 403 : : * encoded numbers are out of range.
# 404 : : *
# 405 : : * After the call, sig will always be initialized. If parsing failed or the
# 406 : : * encoded numbers are out of range, signature validation with it is
# 407 : : * guaranteed to fail for every message and public key.
# 408 : : */
# 409 : : SECP256K1_API int secp256k1_ecdsa_signature_parse_der(
# 410 : : const secp256k1_context* ctx,
# 411 : : secp256k1_ecdsa_signature* sig,
# 412 : : const unsigned char *input,
# 413 : : size_t inputlen
# 414 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
# 415 : :
# 416 : : /** Serialize an ECDSA signature in DER format.
# 417 : : *
# 418 : : * Returns: 1 if enough space was available to serialize, 0 otherwise
# 419 : : * Args: ctx: a secp256k1 context object
# 420 : : * Out: output: a pointer to an array to store the DER serialization
# 421 : : * In/Out: outputlen: a pointer to a length integer. Initially, this integer
# 422 : : * should be set to the length of output. After the call
# 423 : : * it will be set to the length of the serialization (even
# 424 : : * if 0 was returned).
# 425 : : * In: sig: a pointer to an initialized signature object
# 426 : : */
# 427 : : SECP256K1_API int secp256k1_ecdsa_signature_serialize_der(
# 428 : : const secp256k1_context* ctx,
# 429 : : unsigned char *output,
# 430 : : size_t *outputlen,
# 431 : : const secp256k1_ecdsa_signature* sig
# 432 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
# 433 : :
# 434 : : /** Serialize an ECDSA signature in compact (64 byte) format.
# 435 : : *
# 436 : : * Returns: 1
# 437 : : * Args: ctx: a secp256k1 context object
# 438 : : * Out: output64: a pointer to a 64-byte array to store the compact serialization
# 439 : : * In: sig: a pointer to an initialized signature object
# 440 : : *
# 441 : : * See secp256k1_ecdsa_signature_parse_compact for details about the encoding.
# 442 : : */
# 443 : : SECP256K1_API int secp256k1_ecdsa_signature_serialize_compact(
# 444 : : const secp256k1_context* ctx,
# 445 : : unsigned char *output64,
# 446 : : const secp256k1_ecdsa_signature* sig
# 447 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
# 448 : :
# 449 : : /** Verify an ECDSA signature.
# 450 : : *
# 451 : : * Returns: 1: correct signature
# 452 : : * 0: incorrect or unparseable signature
# 453 : : * Args: ctx: a secp256k1 context object, initialized for verification.
# 454 : : * In: sig: the signature being verified (cannot be NULL)
# 455 : : * msg32: the 32-byte message hash being verified (cannot be NULL)
# 456 : : * pubkey: pointer to an initialized public key to verify with (cannot be NULL)
# 457 : : *
# 458 : : * To avoid accepting malleable signatures, only ECDSA signatures in lower-S
# 459 : : * form are accepted.
# 460 : : *
# 461 : : * If you need to accept ECDSA signatures from sources that do not obey this
# 462 : : * rule, apply secp256k1_ecdsa_signature_normalize to the signature prior to
# 463 : : * validation, but be aware that doing so results in malleable signatures.
# 464 : : *
# 465 : : * For details, see the comments for that function.
# 466 : : */
# 467 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdsa_verify(
# 468 : : const secp256k1_context* ctx,
# 469 : : const secp256k1_ecdsa_signature *sig,
# 470 : : const unsigned char *msg32,
# 471 : : const secp256k1_pubkey *pubkey
# 472 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
# 473 : :
# 474 : : /** Convert a signature to a normalized lower-S form.
# 475 : : *
# 476 : : * Returns: 1 if sigin was not normalized, 0 if it already was.
# 477 : : * Args: ctx: a secp256k1 context object
# 478 : : * Out: sigout: a pointer to a signature to fill with the normalized form,
# 479 : : * or copy if the input was already normalized. (can be NULL if
# 480 : : * you're only interested in whether the input was already
# 481 : : * normalized).
# 482 : : * In: sigin: a pointer to a signature to check/normalize (cannot be NULL,
# 483 : : * can be identical to sigout)
# 484 : : *
# 485 : : * With ECDSA a third-party can forge a second distinct signature of the same
# 486 : : * message, given a single initial signature, but without knowing the key. This
# 487 : : * is done by negating the S value modulo the order of the curve, 'flipping'
# 488 : : * the sign of the random point R which is not included in the signature.
# 489 : : *
# 490 : : * Forgery of the same message isn't universally problematic, but in systems
# 491 : : * where message malleability or uniqueness of signatures is important this can
# 492 : : * cause issues. This forgery can be blocked by all verifiers forcing signers
# 493 : : * to use a normalized form.
# 494 : : *
# 495 : : * The lower-S form reduces the size of signatures slightly on average when
# 496 : : * variable length encodings (such as DER) are used and is cheap to verify,
# 497 : : * making it a good choice. Security of always using lower-S is assured because
# 498 : : * anyone can trivially modify a signature after the fact to enforce this
# 499 : : * property anyway.
# 500 : : *
# 501 : : * The lower S value is always between 0x1 and
# 502 : : * 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0,
# 503 : : * inclusive.
# 504 : : *
# 505 : : * No other forms of ECDSA malleability are known and none seem likely, but
# 506 : : * there is no formal proof that ECDSA, even with this additional restriction,
# 507 : : * is free of other malleability. Commonly used serialization schemes will also
# 508 : : * accept various non-unique encodings, so care should be taken when this
# 509 : : * property is required for an application.
# 510 : : *
# 511 : : * The secp256k1_ecdsa_sign function will by default create signatures in the
# 512 : : * lower-S form, and secp256k1_ecdsa_verify will not accept others. In case
# 513 : : * signatures come from a system that cannot enforce this property,
# 514 : : * secp256k1_ecdsa_signature_normalize must be called before verification.
# 515 : : */
# 516 : : SECP256K1_API int secp256k1_ecdsa_signature_normalize(
# 517 : : const secp256k1_context* ctx,
# 518 : : secp256k1_ecdsa_signature *sigout,
# 519 : : const secp256k1_ecdsa_signature *sigin
# 520 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(3);
# 521 : :
# 522 : : /** An implementation of RFC6979 (using HMAC-SHA256) as nonce generation function.
# 523 : : * If a data pointer is passed, it is assumed to be a pointer to 32 bytes of
# 524 : : * extra entropy.
# 525 : : */
# 526 : : SECP256K1_API extern const secp256k1_nonce_function secp256k1_nonce_function_rfc6979;
# 527 : :
# 528 : : /** A default safe nonce generation function (currently equal to secp256k1_nonce_function_rfc6979). */
# 529 : : SECP256K1_API extern const secp256k1_nonce_function secp256k1_nonce_function_default;
# 530 : :
# 531 : : /** Create an ECDSA signature.
# 532 : : *
# 533 : : * Returns: 1: signature created
# 534 : : * 0: the nonce generation function failed, or the secret key was invalid.
# 535 : : * Args: ctx: pointer to a context object, initialized for signing (cannot be NULL)
# 536 : : * Out: sig: pointer to an array where the signature will be placed (cannot be NULL)
# 537 : : * In: msg32: the 32-byte message hash being signed (cannot be NULL)
# 538 : : * seckey: pointer to a 32-byte secret key (cannot be NULL)
# 539 : : * noncefp:pointer to a nonce generation function. If NULL, secp256k1_nonce_function_default is used
# 540 : : * ndata: pointer to arbitrary data used by the nonce generation function (can be NULL)
# 541 : : *
# 542 : : * The created signature is always in lower-S form. See
# 543 : : * secp256k1_ecdsa_signature_normalize for more details.
# 544 : : */
# 545 : : SECP256K1_API int secp256k1_ecdsa_sign(
# 546 : : const secp256k1_context* ctx,
# 547 : : secp256k1_ecdsa_signature *sig,
# 548 : : const unsigned char *msg32,
# 549 : : const unsigned char *seckey,
# 550 : : secp256k1_nonce_function noncefp,
# 551 : : const void *ndata
# 552 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
# 553 : :
# 554 : : /** Verify an ECDSA secret key.
# 555 : : *
# 556 : : * A secret key is valid if it is not 0 and less than the secp256k1 curve order
# 557 : : * when interpreted as an integer (most significant byte first). The
# 558 : : * probability of choosing a 32-byte string uniformly at random which is an
# 559 : : * invalid secret key is negligible.
# 560 : : *
# 561 : : * Returns: 1: secret key is valid
# 562 : : * 0: secret key is invalid
# 563 : : * Args: ctx: pointer to a context object (cannot be NULL)
# 564 : : * In: seckey: pointer to a 32-byte secret key (cannot be NULL)
# 565 : : */
# 566 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_verify(
# 567 : : const secp256k1_context* ctx,
# 568 : : const unsigned char *seckey
# 569 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
# 570 : :
# 571 : : /** Compute the public key for a secret key.
# 572 : : *
# 573 : : * Returns: 1: secret was valid, public key stores
# 574 : : * 0: secret was invalid, try again
# 575 : : * Args: ctx: pointer to a context object, initialized for signing (cannot be NULL)
# 576 : : * Out: pubkey: pointer to the created public key (cannot be NULL)
# 577 : : * In: seckey: pointer to a 32-byte secret key (cannot be NULL)
# 578 : : */
# 579 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_create(
# 580 : : const secp256k1_context* ctx,
# 581 : : secp256k1_pubkey *pubkey,
# 582 : : const unsigned char *seckey
# 583 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
# 584 : :
# 585 : : /** Negates a secret key in place.
# 586 : : *
# 587 : : * Returns: 0 if the given secret key is invalid according to
# 588 : : * secp256k1_ec_seckey_verify. 1 otherwise
# 589 : : * Args: ctx: pointer to a context object
# 590 : : * In/Out: seckey: pointer to the 32-byte secret key to be negated. If the
# 591 : : * secret key is invalid according to
# 592 : : * secp256k1_ec_seckey_verify, this function returns 0 and
# 593 : : * seckey will be set to some unspecified value. (cannot be
# 594 : : * NULL)
# 595 : : */
# 596 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_negate(
# 597 : : const secp256k1_context* ctx,
# 598 : : unsigned char *seckey
# 599 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
# 600 : :
# 601 : : /** Same as secp256k1_ec_seckey_negate, but DEPRECATED. Will be removed in
# 602 : : * future versions. */
# 603 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_negate(
# 604 : : const secp256k1_context* ctx,
# 605 : : unsigned char *seckey
# 606 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
# 607 : :
# 608 : : /** Negates a public key in place.
# 609 : : *
# 610 : : * Returns: 1 always
# 611 : : * Args: ctx: pointer to a context object
# 612 : : * In/Out: pubkey: pointer to the public key to be negated (cannot be NULL)
# 613 : : */
# 614 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_negate(
# 615 : : const secp256k1_context* ctx,
# 616 : : secp256k1_pubkey *pubkey
# 617 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
# 618 : :
# 619 : : /** Tweak a secret key by adding tweak to it.
# 620 : : *
# 621 : : * Returns: 0 if the arguments are invalid or the resulting secret key would be
# 622 : : * invalid (only when the tweak is the negation of the secret key). 1
# 623 : : * otherwise.
# 624 : : * Args: ctx: pointer to a context object (cannot be NULL).
# 625 : : * In/Out: seckey: pointer to a 32-byte secret key. If the secret key is
# 626 : : * invalid according to secp256k1_ec_seckey_verify, this
# 627 : : * function returns 0. seckey will be set to some unspecified
# 628 : : * value if this function returns 0. (cannot be NULL)
# 629 : : * In: tweak: pointer to a 32-byte tweak. If the tweak is invalid according to
# 630 : : * secp256k1_ec_seckey_verify, this function returns 0. For
# 631 : : * uniformly random 32-byte arrays the chance of being invalid
# 632 : : * is negligible (around 1 in 2^128) (cannot be NULL).
# 633 : : */
# 634 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_add(
# 635 : : const secp256k1_context* ctx,
# 636 : : unsigned char *seckey,
# 637 : : const unsigned char *tweak
# 638 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
# 639 : :
# 640 : : /** Same as secp256k1_ec_seckey_tweak_add, but DEPRECATED. Will be removed in
# 641 : : * future versions. */
# 642 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_add(
# 643 : : const secp256k1_context* ctx,
# 644 : : unsigned char *seckey,
# 645 : : const unsigned char *tweak
# 646 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
# 647 : :
# 648 : : /** Tweak a public key by adding tweak times the generator to it.
# 649 : : *
# 650 : : * Returns: 0 if the arguments are invalid or the resulting public key would be
# 651 : : * invalid (only when the tweak is the negation of the corresponding
# 652 : : * secret key). 1 otherwise.
# 653 : : * Args: ctx: pointer to a context object initialized for validation
# 654 : : * (cannot be NULL).
# 655 : : * In/Out: pubkey: pointer to a public key object. pubkey will be set to an
# 656 : : * invalid value if this function returns 0 (cannot be NULL).
# 657 : : * In: tweak: pointer to a 32-byte tweak. If the tweak is invalid according to
# 658 : : * secp256k1_ec_seckey_verify, this function returns 0. For
# 659 : : * uniformly random 32-byte arrays the chance of being invalid
# 660 : : * is negligible (around 1 in 2^128) (cannot be NULL).
# 661 : : */
# 662 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_add(
# 663 : : const secp256k1_context* ctx,
# 664 : : secp256k1_pubkey *pubkey,
# 665 : : const unsigned char *tweak
# 666 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
# 667 : :
# 668 : : /** Tweak a secret key by multiplying it by a tweak.
# 669 : : *
# 670 : : * Returns: 0 if the arguments are invalid. 1 otherwise.
# 671 : : * Args: ctx: pointer to a context object (cannot be NULL).
# 672 : : * In/Out: seckey: pointer to a 32-byte secret key. If the secret key is
# 673 : : * invalid according to secp256k1_ec_seckey_verify, this
# 674 : : * function returns 0. seckey will be set to some unspecified
# 675 : : * value if this function returns 0. (cannot be NULL)
# 676 : : * In: tweak: pointer to a 32-byte tweak. If the tweak is invalid according to
# 677 : : * secp256k1_ec_seckey_verify, this function returns 0. For
# 678 : : * uniformly random 32-byte arrays the chance of being invalid
# 679 : : * is negligible (around 1 in 2^128) (cannot be NULL).
# 680 : : */
# 681 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_seckey_tweak_mul(
# 682 : : const secp256k1_context* ctx,
# 683 : : unsigned char *seckey,
# 684 : : const unsigned char *tweak
# 685 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
# 686 : :
# 687 : : /** Same as secp256k1_ec_seckey_tweak_mul, but DEPRECATED. Will be removed in
# 688 : : * future versions. */
# 689 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_privkey_tweak_mul(
# 690 : : const secp256k1_context* ctx,
# 691 : : unsigned char *seckey,
# 692 : : const unsigned char *tweak
# 693 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
# 694 : :
# 695 : : /** Tweak a public key by multiplying it by a tweak value.
# 696 : : *
# 697 : : * Returns: 0 if the arguments are invalid. 1 otherwise.
# 698 : : * Args: ctx: pointer to a context object initialized for validation
# 699 : : * (cannot be NULL).
# 700 : : * In/Out: pubkey: pointer to a public key object. pubkey will be set to an
# 701 : : * invalid value if this function returns 0 (cannot be NULL).
# 702 : : * In: tweak: pointer to a 32-byte tweak. If the tweak is invalid according to
# 703 : : * secp256k1_ec_seckey_verify, this function returns 0. For
# 704 : : * uniformly random 32-byte arrays the chance of being invalid
# 705 : : * is negligible (around 1 in 2^128) (cannot be NULL).
# 706 : : */
# 707 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_tweak_mul(
# 708 : : const secp256k1_context* ctx,
# 709 : : secp256k1_pubkey *pubkey,
# 710 : : const unsigned char *tweak
# 711 : : ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
# 712 : :
# 713 : : /** Updates the context randomization to protect against side-channel leakage.
# 714 : : * Returns: 1: randomization successfully updated or nothing to randomize
# 715 : : * 0: error
# 716 : : * Args: ctx: pointer to a context object (cannot be NULL)
# 717 : : * In: seed32: pointer to a 32-byte random seed (NULL resets to initial state)
# 718 : : *
# 719 : : * While secp256k1 code is written to be constant-time no matter what secret
# 720 : : * values are, it's possible that a future compiler may output code which isn't,
# 721 : : * and also that the CPU may not emit the same radio frequencies or draw the same
# 722 : : * amount power for all values.
# 723 : : *
# 724 : : * This function provides a seed which is combined into the blinding value: that
# 725 : : * blinding value is added before each multiplication (and removed afterwards) so
# 726 : : * that it does not affect function results, but shields against attacks which
# 727 : : * rely on any input-dependent behaviour.
# 728 : : *
# 729 : : * This function has currently an effect only on contexts initialized for signing
# 730 : : * because randomization is currently used only for signing. However, this is not
# 731 : : * guaranteed and may change in the future. It is safe to call this function on
# 732 : : * contexts not initialized for signing; then it will have no effect and return 1.
# 733 : : *
# 734 : : * You should call this after secp256k1_context_create or
# 735 : : * secp256k1_context_clone (and secp256k1_context_preallocated_create or
# 736 : : * secp256k1_context_clone, resp.), and you may call this repeatedly afterwards.
# 737 : : */
# 738 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_context_randomize(
# 739 : : secp256k1_context* ctx,
# 740 : : const unsigned char *seed32
# 741 : : ) SECP256K1_ARG_NONNULL(1);
# 742 : :
# 743 : : /** Add a number of public keys together.
# 744 : : *
# 745 : : * Returns: 1: the sum of the public keys is valid.
# 746 : : * 0: the sum of the public keys is not valid.
# 747 : : * Args: ctx: pointer to a context object
# 748 : : * Out: out: pointer to a public key object for placing the resulting public key
# 749 : : * (cannot be NULL)
# 750 : : * In: ins: pointer to array of pointers to public keys (cannot be NULL)
# 751 : : * n: the number of public keys to add together (must be at least 1)
# 752 : : */
# 753 : : SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_combine(
# 754 : : const secp256k1_context* ctx,
# 755 : : secp256k1_pubkey *out,
# 756 : : const secp256k1_pubkey * const * ins,
# 757 : : size_t n
# 758 : : ) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
# 759 : :
# 760 : : #ifdef __cplusplus
# 761 : : }
# 762 : : #endif
# 763 : :
# 764 : : #endif /* SECP256K1_H */
|
