The purpose of context structures is to cache large precomputed data tables that are expensive to construct, and also to maintain the randomization data for blinding.

Do not create a new context object for each operation, as construction is far slower than all other API calls (~100 times slower than an ECDSA verification).

A constructed context can safely be used from multiple threads simultaneously, but API calls that take a non-const pointer to a context need exclusive access to it. In particular this is the case for contextDestroy, contextPreallocatedDestroy, and contextRandomize.

Regarding randomization, either do it once at creation time (in which case you do not need any locking for the other calls), or use a read-write lock.

contextRandomize Source #

Arguments

:: Ctx	Mutated: pointer to a context object (cannot be NULL)
-> Ptr Seed32	Input: pointer to a 32-byte random seed (NULL resets to initial state)
-> IO Ret	Returns: 1 if randomization successfully updated or nothing to randomize OR 0 if there was an error

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.

Allocating

contextClone Source #

Arguments

:: Ctx	Input: an existing context to copy (cannot be NULL)
-> IO Ctx	Returns: a newly created context object.

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.

contextCreate Source #

Arguments

:: ContextFlags	Input: which parts of the context to initialize.
-> IO Ctx	Returns: a newly created context object.

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.

Preallocated

Functions in this secion are intended for settings in which it is not possible or desirable to rely on dynamic memory allocation. It provides functions for creating, cloning, and destroying secp256k1 context objects in a contiguous fixed-size block of memory provided by the caller.

Context objects created by functions in this section can be used like contexts objects created by functions in secp256k1.h, i.e., they can be passed to any API function that expects a context object (see secp256k1.h for details). The only exception is that context objects created by functions in this module must be destroyed using contextPreallocatedDestroy (in this section) instead of contextDestroy

It is guaranteed that functions in this module will not call malloc or its friends realloc, calloc, and free.

contextNoPrecomp :: Ctx Source #

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.

contextPreallocatedClone Source #

Arguments

:: Ctx	Mutated: an existing context to copy (cannot be NULL)
-> Ptr (Bytes n)	Input: a pointer to a rewritable contiguous block of memory of size at least `contextPreallocatedSize` (flags) bytes, as detailed above (cannot be NULL)
-> IO Ctx	Returns: a newly created context object.

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.

contextPreallocatedCloneSize Source #

Arguments

:: Ctx	Input: an existing context to copy (cannot be NULL)
-> IO CSize	Returns: the required size of the caller-provided memory block.

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

contextPreallocatedCreate Source #

Arguments

:: Ptr (Bytes n)	Mutated: a pointer to a rewritable contiguous block of memory of size at least `contextPreallocatedSize` (flags) bytes, as detailed above (cannot be NULL)
-> CUInt	Input: which parts of the context to initialize.
-> IO Ctx	Returns: a newly created context object.

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.

contextPreallocatedDestroy Source #

Arguments

:: Ctx	an existing context to destroy, constructed using `contextPreallocatedCreate` or `contextPreallocatedClone` (cannot be NULL)
-> IO ()

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.

contextPreallocatedSize Source #

Arguments

:: CUInt	Input: which parts of the context to initialize.
-> IO CSize	Returns: the required size of the caller-provided memory block

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.

Callbacks

contextSetErrorCallback Source #

Arguments

:: Ctx	an existing context object (cannot be NULL)
-> FunPtr (CString -> Ptr a -> IO ())	Input: a pointer to a function to call when an internal error occurs, taking a message and an opaque pointer (NULL restores the default handler, see contextSetIllegalCallback for details).
-> Ptr a	Input: the opaque pointer to pass to fun above.
-> IO ()

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.

ECDH Operations

ecdh Source #

Arguments

:: Ctx	pointer to a context object (cannot be NULL)
-> Ptr (Bytes n)	Output: pointer to an array to be filled by hashfp
-> Ptr Pubkey64	Input: a pointer to a `Pubkey64` containing an initialized public key
-> Ptr Seckey32	Input: a 32-byte scalar with which to multiply the point
-> FunPtr (EcdhHashFun a)	Input: pointer to a hash function. If NULL, `ecdhHashFunctionSha256` is used (in which case, 32 bytes will be written to output)
-> Ptr a	Input: arbitrary data pointer that is passed through to hashfp
-> IO Ret	Returns: 1 if exponentiation was successful, 0 if scalar was invalid (zero or overflow) or hashfp returned 0

Compute an EC Diffie-Hellman secret in constant time

ecdhHashFunctionDefault :: FunPtr (EcdhHashFun a) Source #

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

ecdhHashFunctionSha256 :: FunPtr (EcdhHashFun a) Source #

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

ECDSA

nonceFunctionDefault :: FunPtr (NonceFun a) Source #

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

nonceFunctionRfc6979 :: FunPtr (NonceFun a) Source #

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.

Recoverable

ecdsaRecover Source #

Arguments

:: Ctx	pointer to a context object, initialized for verification (cannot be NULL)
-> Ptr Pubkey64	Output: pointer to the recovered public key (cannot be NULL)
-> Ptr RecSig65	Input: pointer to initialized signature that supports pubkey recovery (cannot be NULL)
-> Ptr Msg32	Input: the 32-byte message hash assumed to be signed (cannot be NULL)
-> IO Ret	Returns: 1: public key successfully recovered (which guarantees a correct signature). 0: otherwise.

Recover an ECDSA public key from a signature.

ecdsaRecoverableSignatureConvert Source #

Arguments

:: Ctx	a secp256k1 context object
-> Ptr Sig64	Output: pointer to a normal signature (cannot be NULL).
-> Ptr RecSig65	Input: a pointer to a recoverable signature (cannot be NULL).
-> IO Ret	Returns: 1

Convert a recoverable signature into a normal signature.

ecdsaRecoverableSignatureParseCompact Source #

Arguments

:: Ctx	a secp256k1 context object
-> Ptr RecSig65	Output: a pointer to a signature object
-> Ptr (Bytes 64)	Input: a pointer to a 64-byte compact signature
-> CInt	Input: the recovery id (0, 1, 2 or 3)
-> IO Ret	Returns: 1 when the signature could be parsed, 0 otherwise

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

ecdsaRecoverableSignatureSerializeCompact Source #

Arguments

:: Ctx	a secp256k1 context object
-> Ptr (Bytes 64)	Output: a pointer to a 64-byte array of the compact signature (cannot be NULL)
-> Ptr CInt	Output: a pointer to an integer to hold the recovery id (can be NULL).
-> Ptr RecSig65	Input: a pointer to an initialized signature object (cannot be NULL)
-> IO Ret	Returns: 1

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

ecdsaSignRecoverable Source #

Arguments

:: Ctx	pointer to a context object, initialized for signing (cannot be NULL)
-> Ptr RecSig65	Output: pointer to an array where the signature will be placed (cannot be NULL)
-> Ptr Msg32	Input: the 32-byte message hash being signed (cannot be NULL)
-> Ptr Seckey32	Input: pointer to a 32-byte secret key (cannot be NULL)
-> FunPtr (NonceFun a)	Input: pointer to a nonce generation function. If NULL, `nonceFunctionDefault` is used
-> Ptr a	Input: pointer to arbitrary data used by the nonce generation function (can be NULL)
-> IO Ret	Returns: 1: signature created 0: the nonce generation function failed, or the secret key was invalid.

Create a recoverable ECDSA signature.

Non-Recoverable

ecdsaSign Source #

Arguments

:: Ctx	pointer to a context object, initialized for signing (cannot be NULL)
-> Ptr Sig64	Output: pointer to an array where the signature will be placed (cannot be NULL)
-> Ptr Msg32	Input: the 32-byte message hash being signed (cannot be NULL)
-> Ptr Seckey32	Input: pointer to a 32-byte secret key (cannot be NULL)
-> FunPtr (NonceFun a)	Input: pointer to a nonce generation function. If NULL, `nonceFunctionDefault` is used
-> Ptr a	Input: pointer to arbitrary data used by the nonce generation function (can be NULL)
-> IO Ret	Returns: 1: signature created 0: the nonce generation function failed, or the secret key was invalid.

Create an ECDSA signature.

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

ecdsaVerify Source #

Arguments

:: Ctx	a secp256k1 context object, initialized for verification.
-> Ptr Sig64	Input: the signature being verified (cannot be NULL)
-> Ptr Msg32	Input: the 32-byte message hash being verified (cannot be NULL). The verifier must make sure to apply a cryptographic hash function to the message by itself and not accept an msghash32 value directly. Otherwise, it would be easy to create a "valid" signature without knowledge of the secret key. See also https://bitcoin.stackexchange.com/a/81116/35586 for more background on this topic.
-> Ptr Pubkey64	Input: pointer to an initialized public key to verify with (cannot be NULL)
-> IO Ret	Returns: 1 if correct signature, 0 if incorrect or unparseable signature

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.

ecdsaSignatureNormalize Source #

Arguments

:: Ctx	a secp256k1 context object
-> Ptr Sig64	Output: a pointer to a signature to fill with the normalized form, or copy if the input was already normalized. (can be NULL if you're only interested in whether the input was already normalized).
-> Ptr Sig64	Input: a pointer to a signature to check/normalize (cannot be NULL, can be identical to sigout)
-> IO Ret	Returns: 1 if sigin was not normalized, 0 if it already was.

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.

Parsing / Serialization

ecdsaSignatureParseCompact Source #

Arguments

:: Ctx	Input: a secp256k1 context object
-> Ptr Sig64	Output: a pointer to a signature object
-> Ptr (Bytes 64)	Input: a pointer to the 64-byte array to parse
-> IO Ret	Returns: 1 when the signature could be parsed, 0 otherwise.

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.

ecdsaSignatureParseDer Source #

Arguments

:: Ctx	Input: a secp256k1 context object
-> Ptr Sig64	Output: a pointer to a signature object
-> Ptr (Bytes n)	Input: a pointer to the signature to be parsed
-> CSize	Input: the length of the array pointed to be input
-> IO Ret	Returns: 1 when the signature could be parsed, 0 otherwise.

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.

ecdsaSignatureSerializeCompact Source #

Arguments

:: Ctx	Input: a secp256k1 context object
-> Ptr (Bytes 64)	Output: a pointer to a 64-byte array to store the compact serialization
-> Ptr Sig64	Input: a pointer to an initialized signature object
-> IO Ret	Returns: 1

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

See ecdsaSignatureParseCompact for details about the encoding.

ecdsaSignatureSerializeDer Source #

Arguments

:: Ctx	Input: a secp256k1 context object
-> Ptr (Bytes n)	Output: a pointer to an array to store the DER serialization
-> Ptr CSize	Mutates: a pointer to a length integer. Initially, this integer should be set to the length of output. After the call it will be set to the length of the serialization (even if 0 was returned).
-> Ptr Sig64	Input: a pointer to an initialized signature object
-> IO Ret	Returns: 1 if enough space was available to serialize, 0 otherwise

Serialize an ECDSA signature in DER format.

Pubkey Operations

ecPubkeyCmp Source #

Arguments

:: Ctx	Input: a secp256k1 context object.
-> Ptr Pubkey64	Input: first public key to compare
-> Ptr Pubkey64	Input: second public key to compare
-> IO Ret

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

ecPubkeyCombine Source #

Arguments

:: Ctx	pointer to a context object
-> Ptr Pubkey64	Output: pointer to a public key object for placing the resulting public key (cannot be NULL)
-> Ptr (Ptr Pubkey64)	Input: pointer to array of pointers to public keys (cannot be NULL)
-> CInt	Input: the number of public keys to add together (must be at least 1)
-> IO Ret	Returns: 1: the sum of the public keys is valid. 0: the sum of the public keys is not valid.

Add a number of public keys together.

ecPubkeyCreate Source #

Arguments

:: Ctx	pointer to a context object, initialized for signing (cannot be NULL)
-> Ptr Pubkey64	Output: pointer to the created public key (cannot be NULL)
-> Ptr Seckey32	Input: pointer to a 32-byte secret key (cannot be NULL)
-> IO Ret	Returns: 1: secret was valid, public key stores 0: secret was invalid, try again

Compute the public key for a secret key.

ecPubkeyNegate Source #

Arguments

:: Ctx	pointer to a context object
-> Ptr Pubkey64	Mutates: pointer to the public key to be negated (cannot be NULL)
-> IO Ret	Returns: 1 always

Negates a public key in place.

ecPubkeyParse Source #

Arguments

:: Ctx	a secp256k1 context object.
-> Ptr Pubkey64	Output: pointer to a pubkey object. If 1 is returned, it is set to a parsed version of input. If not, its value is undefined.
-> Ptr (Bytes n)	Input: pointer to a serialized public key
-> CSize	Input: length of the array pointed to by input
-> IO Ret	Returns: 1 if the public key was fully valid. 0 if the public key could not be parsed or is invalid.

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.

ecPubkeySerialize Source #

Arguments

:: Ctx	a secp256k1 context object.
-> Ptr (Bytes n)	Output: a pointer to a 65-byte (if compressed==0) or 33-byte (if compressed==1) byte array to place the serialized key in.
-> Ptr CSize	Mutates: a pointer to an integer which is initially set to the size of output, and is overwritten with the written size.
-> Ptr Pubkey64	Input: a pointer to a `Pubkey64` containing an initialized public key.
-> CompressionFlags	Input: `compressed` if serialization should be in compressed format, otherwise `uncompressed`.
-> IO Ret

Serialize a pubkey object into a serialized byte sequence.

ecPubkeyTweakAdd Source #

Arguments

:: Ctx	pointer to a context object initialized for validation (cannot be NULL).
-> Ptr Pubkey64	Mutates: pointer to a public key object. pubkey will be set to an invalid value if this function returns 0 (cannot be NULL).
-> Ptr Tweak32	Input: 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).
-> IO Ret	Returns: 0 if the arguments are invalid or the resulting public key would be invalid (only when the tweak is the negation of the corresponding secret key). 1 otherwise.

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

ecPubkeyTweakMul Source #

Arguments

:: Ctx	pointer to a context object initialized for validation (cannot be NULL).
-> Ptr Pubkey64	Mutates: pointer to a public key object. pubkey will be set to an invalid value if this function returns 0 (cannot be NULL).
-> Ptr Tweak32	Input: 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).
-> IO Ret	Returns: 0 if the arguments are invalid. 1 otherwise.

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

ecSeckeyNegate Source #

Arguments

:: Ctx	pointer to a context object
-> Ptr Seckey32	Mutates: pointer to the 32-byte secret key to be negated. If the secret key is invalid according to ecSeckeyVerify, this function returns 0 and seckey will be set to some unspecified value. (cannot be NULL)
-> IO Ret	Returns: 0 if the given secret key is invalid according to `ecSeckeyVerify`. 1 otherwise

Negates a secret key in place.

ecSeckeyTweakAdd Source #

Arguments

:: Ctx	pointer to a context object (cannot be NULL).
-> Ptr Seckey32	Mutates: pointer to a 32-byte secret key. If the secret key is invalid according to `ecSeckeyVerify`, this function returns 0. seckey will be set to some unspecified value if this function returns 0. (cannot be NULL)
-> Ptr Tweak32	Input: 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).
-> IO Ret	Returns: 0 if the arguments are invalid or the resulting secret key would be invalid (only when the tweak is the negation of the secret key). 1 otherwise.

Tweak a secret key by adding tweak to it.

ecSeckeyTweakMul Source #

Arguments

:: Ctx	pointer to a context object (cannot be NULL).
-> Ptr Seckey32
-> Ptr Tweak32
-> IO Ret

Tweak a secret key by multiplying it by a tweak.

ecSecKeyVerify Source #

Arguments

:: Ctx	pointer to a context object (cannot be NULL)
-> Ptr Seckey32	Input: pointer to a 32-byte secret key (cannot be NULL)
-> IO Ret	Returns: 1 if secret key is valid, 0 if secret key is invalid

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.

keypairCreate Source #

Arguments

:: Ctx	pointer to a context object, initialized for signing (cannot be NULL)
-> Ptr Keypair96	Output: pointer to the created keypair (cannot be NULL)
-> Ptr Seckey32	Input: pointer to a 32-byte secret key (cannot be NULL)
-> IO Ret	Returns: 1: secret was valid, keypair is ready to use 0: secret was invalid, try again with a different secret

Compute the keypair for a secret key.

keypairPub Source #

Arguments

:: Ctx	pointer to a context object (cannot be NULL)
-> Ptr Pubkey64	Output: pointer to a pubkey object. If 1 is returned, it is set to the keypair public key. If not, it's set to an invalid value. (cannot be NULL)
-> Ptr Keypair96	Input: pointer to a keypair (cannot be NULL)
-> IO Ret	Returns: 0 if the arguments are invalid. 1 otherwise.

Get the public key from a keypair.

keypairSec Source #

Arguments

:: Ctx	pointer to a context object (cannot be NULL)
-> Ptr Seckey32	Output: pointer to a 32-byte buffer for the secret key (cannot be NULL)
-> Ptr Keypair96	Input: pointer to a keypair (cannot be NULL)
-> IO Ret	Returns: 0 if the arguments are invalid. 1 otherwise.

Get the secret key from a keypair.

keypairXonlyPub Source #

Arguments

:: Ctx	pointer to a context object (cannot be NULL)
-> Ptr XonlyPubkey64	Output: 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).
-> Ptr CInt
-> Ptr Keypair96
-> IO Ret

Get the x-only public key from a keypair.

This is the same as calling keypairPub and then xonlyPubkeyFromPubkey.

keypairXonlyTweakAdd Source #

Arguments

:: Ctx	pointer to a context object initialized for verification (cannot be NULL)
-> Ptr Keypair96	Mutates: pointer to a keypair to apply the tweak to. Will be set to an invalid value if this function returns 0 (cannot be NULL).
-> Ptr Tweak32	Input: 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).
-> IO Ret	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.

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.

Schnorr Operations

nonceFunctionBip340 :: FunPtr (NonceFunHardened a) Source #

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.

schnorrsigSign Source #

Arguments

:: Ctx	pointer to a context object, initialized for signing (cannot be NULL)
-> Ptr Sig64	Output: pointer to a 64-byte array to store the serialized signature (cannot be NULL)
-> Ptr Msg32	Input: the 32-byte message being signed (cannot be NULL)
-> Ptr Keypair96	Input: pointer to an initialized keypair (cannot be NULL)
-> Ptr (Bytes 32)	Input: 32 bytes of fresh randomness. While recommended to provide this, it is only supplemental to security and can be NULL. See BIP-340 "Default Signing" for a full explanation of this argument and for guidance if randomness is expensive.
-> IO Ret	Returns: 1 on success, 0 on failure.

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.

schnorrsigSignCustom Source #

Arguments

:: Ctx	pointer to a context object, initialized for signing (cannot be NULL)
-> Ptr Sig64	Output: pointer to a 64-byte array to store the serialized signature (cannot be NULL)
-> Ptr (Bytes n)	Input: the message being signed. Can only be NULL if msglen is 0.
-> CSize	Input: length of the message
-> Ptr Keypair96	Input: pointer to an initialized keypair (cannot be NULL)
-> Ptr SchnorrExtra	Input: pointer to a extraparams object (can be NULL)
-> IO Ret	Returns: 1 on success, 0 on failure.

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.

schnorrsigSignVerify Source #

Arguments

:: Ctx	a secp256k1 context object, initialized for verification.
-> Ptr Sig64	Input: pointer to the 64-byte signature to verify (cannot be NULL)
-> Ptr (Bytes n)	Input: the message being verified. Can only be NULL if msglen is 0.
-> CSize	Input: length of the message
-> Ptr XonlyPubkey64	Input: pointer to an x-only public key to verify with (cannot be NULL)
-> IO Ret	Returns: 1 on correct signature, 0 on incorrect signature

Verify a Schnorr signature.

taggedSha256 Source #

Arguments

:: Ctx	pointer to a context object
-> Ptr (Bytes 32)	Output: pointer to a 32-byte array to store the resulting hash
-> Ptr (Bytes n)	Input: pointer to an array containing the tag
-> CSize	Input: length of the tag array
-> Ptr (Bytes n)	Input: pointer to an array containing the message
-> CSize	Input: length of the message array
-> IO Ret	Returns: 0 if the arguments are invalid and 1 otherwise.

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.

XOnly Operations

xonlyPubkeyCmp Source #

Arguments

:: Ctx	a secp256k1 context object.
-> Ptr XonlyPubkey64	Input: first public key to compare
-> Ptr XonlyPubkey64	Input: second public key to compare
-> IO Ret	Returns: <0 if the first public key is less than the second >0 if the first public key is greater than the second 0 if the two public keys are equal

Compare two x-only public keys using lexicographic order

xonlyPubkeyFromPubkey Source #

Arguments

:: Ctx	pointer to a context object (cannot be NULL)
-> Ptr XonlyPubkey64	Output: pointer to an x-only public key object for placing the converted public key (cannot be NULL)
-> Ptr CInt
-> Ptr Pubkey64	Input: pubkey: pointer to a public key that is converted (cannot be NULL)
-> IO Ret	Returns: 1 if the public key was successfully converted 0 otherwise

Converts a Pubkey64 into a XonlyPubkey64.

xonlyPubkeyParse Source #

Arguments

:: Ctx	a secp256k1 context object (cannot be NULL).
-> Ptr XonlyPubkey64	Output: pointer to a pubkey object. If 1 is returned, it is set to a parsed version of input. If not, it's set to an invalid value. (cannot be NULL).
-> Ptr (Bytes 32)	Input: pointer to a serialized xonly_pubkey (cannot be NULL)
-> IO Ret	Returns: 1 if the public key was fully valid. 0 if the public key could not be parsed or is invalid.

Parse a 32-byte sequence into a XonlyPubkey64 object.

xonlyPubkeySerialize Source #

Arguments

:: Ctx	a secp256k1 context object (cannot be NULL).
-> Ptr (Bytes 32)	Output: a pointer to a 32-byte array to place the serialized key in (cannot be NULL).
-> Ptr XonlyPubkey64	Input: a pointer to a `XonlyPubkey64` containing an initialized public key (cannot be NULL).
-> IO Ret	Returns: 1 always.

Serialize an XonlyPubkey64 object into a 32-byte sequence.

xonlyPubkeyTweakAdd Source #

Arguments

:: Ctx	pointer to a context object initialized for verification (cannot be NULL)
-> Ptr Pubkey64	Output: pointer to a public key to store the result. Will be set to an invalid value if this function returns 0 (cannot be NULL)
-> Ptr XonlyPubkey64	Input: internal_pubkey: pointer to an x-only pubkey to apply the tweak to. (cannot be NULL).
-> Ptr Tweak32	Input: 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).
-> IO Ret	Returns: 0 if the arguments are invalid or the resulting public key would be invalid (only when the tweak is the negation of the corresponding secret key). 1 otherwise.

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.

xonlyPubkeyTweakAddCheck Source #

Arguments

:: Ctx	pointer to a context object initialized for verification (cannot be NULL)
-> Ptr XonlyPubkey64	Input: pointer to a serialized xonly_pubkey (cannot be NULL)
-> CInt	Input: the parity of the tweaked pubkey (whose serialization is passed in as tweaked_pubkey32). This must match the pk_parity value that is returned when calling `xonlyPubkey` with the tweaked pubkey, or this function will fail.
-> Ptr XonlyPubkey64	Input pointer to an x-only public key object to apply the tweak to (cannot be NULL)
-> Ptr Tweak32	Input: pointer to a 32-byte tweak (cannot be NULL)
-> IO Ret	Returns: 0 if the arguments are invalid or the tweaked pubkey is not the result of tweaking the internal_pubkey with tweak32. 1 otherwise.

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

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.

Scratch Space

scratchSpaceCreate Source #

Arguments

:: Ctx	an existing context object (cannot be NULL)
-> CSize	Input: amount of memory to be available as scratch space. Some extra (<100 bytes) will be allocated for extra accounting.
-> IO (Ptr Scratch)	Returns: a newly created scratch space.

Create a secp256k1 scratch space object.

scratchSpaceDestroy Source #

Arguments

:: Ctx	a secp256k1 context object.
-> Ptr Scratch	Input: space to destroy
-> IO ()

Destroy a secp256k1 scratch space.

The pointer may not be used afterwards.

Deprecated

ecPrivkeyNegate :: Ctx -> Ptr Tweak32 -> IO Ret Source #

Deprecated: use ecSeckeyNegate instead

ecPrivkeyTweakAdd :: Ctx -> Ptr Seckey32 -> Ptr Tweak32 -> IO Ret Source #

Deprecated: use ecSeckeyTweakAdd instead

ecPrivkeyTweakMul :: Ctx -> Ptr Seckey32 -> Ptr Tweak32 -> IO Ret Source #

Deprecated: use ecSeckeyTweakMul instead

Pointer Types

data LCtx Source #

data Pubkey64 Source #

data XonlyPubkey64 Source #

data Keypair96 Source #

data Msg32 Source #

data RecSig65 Source #

data Sig64 Source #

data Seed32 Source #

data Seckey32 Source #

data Tweak32 Source #

data SchnorrExtra Source #

data Scratch Source #

data Bytes (n :: Nat) Source #

Function Pointer Types

type NonceFun a Source #

Arguments

= Ptr CUChar	Output: pointer to a 32-byte array to be filled by the function.
-> Ptr CUChar	Input: the 32-byte message hash being verified (will not be NULL)
-> Ptr CUChar	Input: pointer to a 32-byte secret key (will not be NULL)
-> Ptr CUChar	Input: pointer to a 16-byte array describing the signature algorithm (will be NULL for ECDSA for compatibility).
-> Ptr a	Input: Arbitrary data pointer that is passed through.
-> CInt	Input: how many iterations we have tried to find a nonce. This will almost always be 0, but different attempt values are required to result in a different nonce.
-> IO CInt	Returns: 1 if a nonce was successfully generated. 0 will cause signing to fail.

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.

type NonceFunHardened a Source #

Arguments

= Ptr CUChar	Output: pointer to a 32-byte array to be filled by the function
-> Ptr CUChar	Input: the message being verified. Is NULL if and only if msglen is 0.
-> CSize	Input: the length of the message
-> Ptr CUChar	Input: pointer to a 32-byte secret key (will not be NULL)
-> Ptr CUChar	Input: the 32-byte serialized xonly pubkey corresponding to key32 (will not be NULL)
-> Ptr CUChar	Input: pointer to an array describing the signature algorithm (will not be NULL)
-> CSize	Input: the length of the algo array
-> Ptr a	Input: arbitrary data pointer that is passed through
-> IO CInt	Returns: 1 if a nonce was successfully generated. 0 will cause signing to return an error.

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.

type EcdhHashFun a Source #

Arguments

= Ptr CUChar	Output: pointer to an array to be filled by the function
-> Ptr CUChar	Input: pointer to a 32-byte x coordinate
-> Ptr CUChar	Input: pointer to a 32-byte y coordinate
-> Ptr a	Input: arbitrary data pointer that is passed through
-> IO CInt	Returns: 1 if the point was successfully hashed. 0 will cause `ecdh` to fail and return 0. Other return values are not allowed, and the behaviour of `ecdh` is undefined for other return values.

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