Updates the context randomization to protect against side-channel leakage.

While secp256k1 code is written to be constant-time no matter what secret values are, it's possible that a future compiler may output code which isn't, and also that the CPU may not emit the same radio frequencies or draw the same amount power for all values.

This function provides a seed which is combined into the blinding value: that blinding value is added before each multiplication (and removed afterwards) so that it does not affect function results, but shields against attacks which rely on any input-dependent behaviour.

This function has currently an effect only on contexts initialized for signing because randomization is currently used only for signing. However, this is not guaranteed and may change in the future. It is safe to call this function on contexts not initialized for signing; then it will have no effect and return 1.

You should call this after contextCreate or contextClone (and contextPreallocatedCreate or contextClone, resp.), and you may call this repeatedly afterwards.

Copy a secp256k1 context object (into dynamically allocated memory).

This function uses malloc to allocate memory. It is guaranteed that malloc is called at most once for every call of this function. If you need to avoid dynamic memory allocation entirely, see the functions in the Preallocated section.

Create a secp256k1 context object (in dynamically allocated memory).

This function uses malloc to allocate memory. It is guaranteed that malloc is called at most once for every call of this function. If you need to avoid dynamic memory allocation entirely, see the functions in secp256k1_preallocated.h.

See also contextRandomize.

Destroy a secp256k1 context object (created in dynamically allocated memory).

The context pointer may not be used afterwards.

The context to destroy must have been created using contextCreate or contextClone. If the context has instead been created using contextPreallocatedCreate or contextPreallocatedClone, the behaviour is undefined. In that case, contextPreallocatedDestroy must be used instead.

A simple secp256k1 context object with no precomputed tables. These are useful for type serialization/parsing functions which require a context object to maintain API consistency, but currently do not require expensive precomputations or dynamic allocations.

Copy a secp256k1 context object into caller-provided memory.

The caller must provide a pointer to a rewritable contiguous block of memory of size at least contextPreallocatedSize (flags) bytes, suitably aligned to hold an object of any type.

The block of memory is exclusively owned by the created context object during the lifetime of this context object, see the description of contextPreallocatedCreate for details.

Determine the memory size of a secp256k1 context object to be copied into caller-provided memory.

Create a secp256k1 context object in caller-provided memory.

The caller must provide a pointer to a rewritable contiguous block of memory of size at least contextPreallocatedSize (flags) bytes, suitably aligned to hold an object of any type.

The block of memory is exclusively owned by the created context object during the lifetime of this context object, which begins with the call to this function and ends when a call to contextPreallocatedDestroy (which destroys the context object again) returns. During the lifetime of the context object, the caller is obligated not to access this block of memory, i.e., the caller may not read or write the memory, e.g., by copying the memory contents to a different location or trying to create a second context object in the memory. In simpler words, the prealloc pointer (or any pointer derived from it) should not be used during the lifetime of the context object.

See also contextRandomize and contextPreallocatedDestroy.

Destroy a secp256k1 context object that has been created in caller-provided memory.

The context pointer may not be used afterwards.

The context to destroy must have been created using contextPreallocatedCreate or contextPreallocatedClone. If the context has instead been created using contextCreate or contextClone, the behaviour is undefined. In that case, contextDestroy must be used instead.

If required, it is the responsibility of the caller to deallocate the block of memory properly after this function returns, e.g., by calling free on the preallocated pointer given to contextPreallocatedCreate or contextPreallocatedClone.

Determine the memory size of a secp256k1 context object to be created in caller-provided memory.

The purpose of this function is to determine how much memory must be provided to contextPreallocatedCreate.

Set a callback function to be called when an internal consistency check fails. The default is crashing.

This can only trigger in case of a hardware failure, miscompilation, memory corruption, serious bug in the library, or other error would can otherwise result in undefined behaviour. It will not trigger due to mere incorrect usage of the API (see contextSetIllegalCallback for that). After this callback returns, anything may happen, including crashing.

See also contextSetIllegalCallback.

Set a callback function to be called when an illegal argument is passed to an API call. It will only trigger for violations that are mentioned explicitly in the header.

The philosophy is that these shouldn't be dealt with through a specific return value, as calling code should not have branches to deal with the case that this code itself is broken.

On the other hand, during debug stage, one would want to be informed about such mistakes, and the default (crashing) may be inadvisable. When this callback is triggered, the API function called is guaranteed not to cause a crash, though its return value and output arguments are undefined.

When this function has not been called (or called with fn==NULL), then the default handler will be used. The library provides a default handler which writes the message to stderr and calls abort. This default handler can be replaced at link time if the preprocessor macro USE_EXTERNAL_DEFAULT_CALLBACKS is defined, which is the case if the build has been configured with --enable-external-default-callbacks. Then the following two symbols must be provided to link against: - void secp256k1_default_illegal_callback_fn(const char* message, void* data); - void secp256k1_default_error_callback_fn(const char* message, void* data); The library can call these default handlers even before a proper callback data pointer could have been set using contextSetIllegalCallback or contextSetErrorCallback, e.g., when the creation of a context fails. In this case, the corresponding default handler will be called with the data pointer argument set to NULL.

See also contextSetErrorCallback.

Compute an EC Diffie-Hellman secret in constant time

A default ECDH hash function (currently equal to ecdhHashFunctionSha256). Populates the output parameter with 32 bytes.

An implementation of SHA256 hash function that applies to compressed public key. Populates the output parameter with 32 bytes.

A default safe nonce generation function (currently equal to nonceFunctionRfc6979).

An implementation of RFC6979 (using HMAC-SHA256) as nonce generation function. If a data pointer is passed, it is assumed to be a pointer to 32 bytes of extra entropy.

Recover an ECDSA public key from a signature.

Convert a recoverable signature into a normal signature.

Parse a compact ECDSA signature (64 bytes + recovery id).

Serialize an ECDSA signature in compact format (64 bytes + recovery id).

Create a recoverable ECDSA signature.

Create an ECDSA signature.

The created signature is always in lower-S form. See ecdsaSignatureNormalize for more details.

Verify an ECDSA signature.

To avoid accepting malleable signatures, only ECDSA signatures in lower-S form are accepted.

If you need to accept ECDSA signatures from sources that do not obey this rule, apply ecdsaSignatureNormalize to the signature prior to validation, but be aware that doing so results in malleable signatures.

For details, see the comments for that function.

Convert a signature to a normalized lower-S form.

With ECDSA a third-party can forge a second distinct signature of the same message, given a single initial signature, but without knowing the key. This is done by negating the S value modulo the order of the curve, "flipping" the sign of the random point R which is not included in the signature.

Forgery of the same message isn't universally problematic, but in systems where message malleability or uniqueness of signatures is important this can cause issues. This forgery can be blocked by all verifiers forcing signers to use a normalized form.

The lower-S form reduces the size of signatures slightly on average when variable length encodings (such as DER) are used and is cheap to verify, making it a good choice. Security of always using lower-S is assured because anyone can trivially modify a signature after the fact to enforce this property anyway.

The lower S value is always between 0x1 and 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0, inclusive.

No other forms of ECDSA malleability are known and none seem likely, but there is no formal proof that ECDSA, even with this additional restriction, is free of other malleability. Commonly used serialization schemes will also accept various non-unique encodings, so care should be taken when this property is required for an application.

The ecdsaSign function will by default create signatures in the lower-S form, and ecdsaVerify will not accept others. In case signatures come from a system that cannot enforce this property, ecdsaSignatureNormalize must be called before verification.

Parse an ECDSA signature in compact (64 bytes) format.

The signature must consist of a 32-byte big endian R value, followed by a 32-byte big endian S value. If R or S fall outside of [0..order-1], the encoding is invalid. R and S with value 0 are allowed in the encoding.

After the call, sig will always be initialized. If parsing failed or R or S are zero, the resulting sig value is guaranteed to fail validation for any message and public key.

Parse a DER ECDSA signature.

This function will accept any valid DER encoded signature, even if the encoded numbers are out of range.

After the call, sig will always be initialized. If parsing failed or the encoded numbers are out of range, signature validation with it is guaranteed to fail for every message and public key.

Serialize an ECDSA signature in compact (64 byte) format.

See ecdsaSignatureParseCompact for details about the encoding.

Serialize an ECDSA signature in DER format.

Compare two public keys using lexicographic (of compressed serialization) order

Add a number of public keys together.

Compute the public key for a secret key.

Negates a public key in place.

Parse a variable-length public key into the pubkey object.

This function supports parsing compressed (33 bytes, header byte 0x02 or 0x03), uncompressed (65 bytes, header byte 0x04), or hybrid (65 bytes, header byte 0x06 or 0x07) format public keys.

Serialize a pubkey object into a serialized byte sequence.

Tweak a public key by adding tweak times the generator to it.

Tweak a public key by multiplying it by a tweak value.

Negates a secret key in place.

Tweak a secret key by adding tweak to it.

Tweak a secret key by multiplying it by a tweak.

Verify an ECDSA secret key.

A secret key is valid if it is not 0 and less than the secp256k1 curve order when interpreted as an integer (most significant byte first). The probability of choosing a 32-byte string uniformly at random which is an invalid secret key is negligible.

Compute the keypair for a secret key.

Get the public key from a keypair.

Get the secret key from a keypair.

Get the x-only public key from a keypair.

This is the same as calling keypairPub and then xonlyPubkeyFromPubkey.

Returns: 0 if the arguments are invalid. 1 otherwise. Args: ctx: pointer to a context object (cannot be NULL) Out: pubkey: pointer to an xonly_pubkey object. If 1 is returned, it is set to the keypair public key after converting it to an xonly_pubkey. If not, it's set to an invalid value (cannot be NULL). pk_parity: pointer to an integer that will be set to the pk_parity argument of xonlyPubkeyFromPubkey (can be NULL). In: keypair: pointer to a keypair (cannot be NULL)

Tweak a keypair by adding tweak32 to the secret key and updating the public key accordingly.

Calling this function and then keypairPub results in the same public key as calling keypairXonlyPub and then xonlyPubkeyTweakAdd.

Returns: 0 if the arguments are invalid or the resulting keypair would be invalid (only when the tweak is the negation of the keypair's secret key). 1 otherwise.

Args: ctx: pointer to a context object initialized for verification (cannot be NULL) In/Out: keypair: pointer to a keypair to apply the tweak to. Will be set to an invalid value if this function returns 0 (cannot be NULL). In: tweak32: pointer to a 32-byte tweak. If the tweak is invalid according to ecSeckeyVerify, this function returns 0. For uniformly random 32-byte arrays the chance of being invalid is negligible (around 1 in 2^128) (cannot be NULL).

An implementation of the nonce generation function as defined in Bitcoin Improvement Proposal 340 "Schnorr Signatures for secp256k1" (https:/github.combitcoinbipsblobmasterbip-0340.mediawiki).

If a data pointer is passed, it is assumed to be a pointer to 32 bytes of auxiliary random data as defined in BIP-340. If the data pointer is NULL, the nonce derivation procedure follows BIP-340 by setting the auxiliary random data to zero. The algo argument must be non-NULL, otherwise the function will fail and return 0. The hash will be tagged with algo. Therefore, to create BIP-340 compliant signatures, algo must be set to "BIP0340/nonce" and algolen to 13.

Create a Schnorr signature.

Does _not_ strictly follow BIP-340 because it does not verify the resulting signature. Instead, you can manually use schnorrsigVerify and abort if it fails.

This function only signs 32-byte messages. If you have messages of a different size (or the same size but without a context-specific tag prefix), it is recommended to create a 32-byte message hash with taggedSha256 and then sign the hash. Tagged hashing allows providing an context-specific tag for domain separation. This prevents signatures from being valid in multiple contexts by accident.

Create a Schnorr signature with a more flexible API.

Same arguments as schnorrsigSign except that it allows signing variable length messages and accepts a pointer to an extraparams object that allows customizing signing by passing additional arguments.

Creates the same signatures as schnorrsig_sign if msglen is 32 and the extraparams.ndata is the same as aux_rand32.

Verify a Schnorr signature.

Compute a tagged hash as defined in BIP-340.

This is useful for creating a message hash and achieving domain separation through an application-specific tag. This function returns SHA256(SHA256(tag)||SHA256(tag)||msg). Therefore, tagged hash implementations optimized for a specific tag can precompute the SHA256 state after hashing the tag hashes.

Compare two x-only public keys using lexicographic order

Converts a Pubkey64 into a XonlyPubkey64.

Parse a 32-byte sequence into a XonlyPubkey64 object.

Serialize an XonlyPubkey64 object into a 32-byte sequence.

Tweak an x-only public key by adding the generator multiplied with tweak32 to it.

Note that the resulting point can not in general be represented by an x-only pubkey because it may have an odd Y coordinate. Instead, the output_pubkey is a normal Pubkey64.

Checks that a tweaked pubkey is the result of calling xonlyPubkeyTweakAdd with internal_pubkey and tweak32.

The tweaked pubkey is represented by its 32-byte x-only serialization and its pk_parity, which can both be obtained by converting the result of tweak_add to a XonlyPubkey64.

Note that this alone does _not_ verify that the tweaked pubkey is a commitment. If the tweak is not chosen in a specific way, the tweaked pubkey can easily be the result of a different internal_pubkey and tweak.

Create a secp256k1 scratch space object.

Destroy a secp256k1 scratch space.

The pointer may not be used afterwards.

A pointer to a function to deterministically generate a nonce. Except for test cases, this function should compute some cryptographic hash of the message, the algorithm, the key and the attempt.

A pointer to a function to deterministically generate a nonce.

Same as NonceFun with the exception of accepting an additional pubkey argument and not requiring an attempt argument. The pubkey argument can protect signature schemes with key-prefixed challenge hash inputs against reusing the nonce when signing with the wrong precomputed pubkey.

Except for test cases, this function should compute some cryptographic hash of the message, the key, the pubkey, the algorithm description, and data.

A pointer to a function that hashes an EC point to obtain an ECDH secret