Differential D5031 Diff 15739 src/secp256k1/include/secp256k1.h

Changeset View

Standalone View

src/secp256k1/include/secp256k1.h

	Show All 27 Lines
	* that are expensive to construct, and also to maintain the randomization data			* that are expensive to construct, and also to maintain the randomization data
	* for blinding.			* for blinding.
	*			*
	* Do not create a new context object for each operation, as construction is			* 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			* far slower than all other API calls (~100 times slower than an ECDSA
	* verification).			* verification).
	*			*
	* A constructed context can safely be used from multiple threads			* A constructed context can safely be used from multiple threads
	* simultaneously, but API call that take a non-const pointer to a context			* 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			* need exclusive access to it. In particular this is the case for
	* secp256k1_context_destroy and secp256k1_context_randomize.			* secp256k1_context_destroy, secp256k1_context_preallocated_destroy,
				* and secp256k1_context_randomize.
	*			*
	* Regarding randomization, either do it once at creation time (in which case			* 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.			* you do not need any locking for the other calls), or use a read-write lock.
	*/			*/
	typedef struct secp256k1_context_struct secp256k1_context;			typedef struct secp256k1_context_struct secp256k1_context;

	/** Opaque data structure that holds rewriteable "scratch space"			/** Opaque data structure that holds rewriteable "scratch space"
	*			*
	▲ Show 20 Lines • Show All 111 Lines • ▼ Show 20 Lines
	#define SECP256K1_FLAGS_TYPE_MASK ((1 << 8) - 1)			#define SECP256K1_FLAGS_TYPE_MASK ((1 << 8) - 1)
	#define SECP256K1_FLAGS_TYPE_CONTEXT (1 << 0)			#define SECP256K1_FLAGS_TYPE_CONTEXT (1 << 0)
	#define SECP256K1_FLAGS_TYPE_COMPRESSION (1 << 1)			#define SECP256K1_FLAGS_TYPE_COMPRESSION (1 << 1)
	/** The higher bits contain the actual data. Do not use directly. */			/** The higher bits contain the actual data. Do not use directly. */
	#define SECP256K1_FLAGS_BIT_CONTEXT_VERIFY (1 << 8)			#define SECP256K1_FLAGS_BIT_CONTEXT_VERIFY (1 << 8)
	#define SECP256K1_FLAGS_BIT_CONTEXT_SIGN (1 << 9)			#define SECP256K1_FLAGS_BIT_CONTEXT_SIGN (1 << 9)
	#define SECP256K1_FLAGS_BIT_COMPRESSION (1 << 8)			#define SECP256K1_FLAGS_BIT_COMPRESSION (1 << 8)

	/** Flags to pass to secp256k1_context_create. */			/** Flags to pass to secp256k1_context_create, secp256k1_context_preallocated_size, and
				* secp256k1_context_preallocated_create. */
	#define SECP256K1_CONTEXT_VERIFY (SECP256K1_FLAGS_TYPE_CONTEXT \| SECP256K1_FLAGS_BIT_CONTEXT_VERIFY)			#define SECP256K1_CONTEXT_VERIFY (SECP256K1_FLAGS_TYPE_CONTEXT \| SECP256K1_FLAGS_BIT_CONTEXT_VERIFY)
	#define SECP256K1_CONTEXT_SIGN (SECP256K1_FLAGS_TYPE_CONTEXT \| SECP256K1_FLAGS_BIT_CONTEXT_SIGN)			#define SECP256K1_CONTEXT_SIGN (SECP256K1_FLAGS_TYPE_CONTEXT \| SECP256K1_FLAGS_BIT_CONTEXT_SIGN)
	#define SECP256K1_CONTEXT_NONE (SECP256K1_FLAGS_TYPE_CONTEXT)			#define SECP256K1_CONTEXT_NONE (SECP256K1_FLAGS_TYPE_CONTEXT)

	/** Flag to pass to secp256k1_ec_pubkey_serialize and secp256k1_ec_privkey_export. */			/** Flag to pass to secp256k1_ec_pubkey_serialize and secp256k1_ec_privkey_export. */
	#define SECP256K1_EC_COMPRESSED (SECP256K1_FLAGS_TYPE_COMPRESSION \| SECP256K1_FLAGS_BIT_COMPRESSION)			#define SECP256K1_EC_COMPRESSED (SECP256K1_FLAGS_TYPE_COMPRESSION \| SECP256K1_FLAGS_BIT_COMPRESSION)
	#define SECP256K1_EC_UNCOMPRESSED (SECP256K1_FLAGS_TYPE_COMPRESSION)			#define SECP256K1_EC_UNCOMPRESSED (SECP256K1_FLAGS_TYPE_COMPRESSION)

	/** Prefix byte used to tag various encoded curvepoints for specific purposes */			/** Prefix byte used to tag various encoded curvepoints for specific purposes */
	#define SECP256K1_TAG_PUBKEY_EVEN 0x02			#define SECP256K1_TAG_PUBKEY_EVEN 0x02
	#define SECP256K1_TAG_PUBKEY_ODD 0x03			#define SECP256K1_TAG_PUBKEY_ODD 0x03
	#define SECP256K1_TAG_PUBKEY_UNCOMPRESSED 0x04			#define SECP256K1_TAG_PUBKEY_UNCOMPRESSED 0x04
	#define SECP256K1_TAG_PUBKEY_HYBRID_EVEN 0x06			#define SECP256K1_TAG_PUBKEY_HYBRID_EVEN 0x06
	#define SECP256K1_TAG_PUBKEY_HYBRID_ODD 0x07			#define SECP256K1_TAG_PUBKEY_HYBRID_ODD 0x07

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

	/** Create a secp256k1 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.
	*			*
	* Returns: a newly created context object.			* Returns: a newly created context object.
	* In: flags: which parts of the context to initialize.			* In: flags: which parts of the context to initialize.
	*			*
	* See also secp256k1_context_randomize.			* See also secp256k1_context_randomize.
	*/			*/
	SECP256K1_API secp256k1_context* secp256k1_context_create(			SECP256K1_API secp256k1_context* secp256k1_context_create(
	unsigned int flags			unsigned int flags
	) SECP256K1_WARN_UNUSED_RESULT;			) SECP256K1_WARN_UNUSED_RESULT;

	/** Copies a secp256k1 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 secp256k1_preallocated.h.
	*			*
	* Returns: a newly created context object.			* Returns: a newly created context object.
	* Args: ctx: an existing context to copy (cannot be NULL)			* Args: ctx: an existing context to copy (cannot be NULL)
	*/			*/
	SECP256K1_API secp256k1_context* secp256k1_context_clone(			SECP256K1_API secp256k1_context* secp256k1_context_clone(
	const secp256k1_context* ctx			const secp256k1_context* ctx
	) SECP256K1_ARG_NONNULL(1) SECP256K1_WARN_UNUSED_RESULT;			) SECP256K1_ARG_NONNULL(1) SECP256K1_WARN_UNUSED_RESULT;

	/** Destroy a secp256k1 context object.			/** Destroy a secp256k1 context object (created in dynamically allocated memory).
	*			*
	* The context pointer may not be used afterwards.			* The context pointer may not be used afterwards.
	* Args: ctx: an existing context to destroy (cannot be NULL)			*
				* The context to destroy must have been created using secp256k1_context_create
				* or secp256k1_context_clone. If the context has instead been created using
				* secp256k1_context_preallocated_create or secp256k1_context_preallocated_clone, the
				* behaviour is undefined. In that case, secp256k1_context_preallocated_destroy must
				* be used instead.
				*
				* Args: ctx: an existing context to destroy, constructed using
				* secp256k1_context_create or secp256k1_context_clone
	*/			*/
	SECP256K1_API void secp256k1_context_destroy(			SECP256K1_API void secp256k1_context_destroy(
	secp256k1_context* ctx			secp256k1_context* ctx
	);			);

	/** Set a callback function to be called when an illegal argument is passed to			/** 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			* an API call. It will only trigger for violations that are mentioned
	* explicitly in the header.			* explicitly in the header.
	▲ Show 20 Lines • Show All 410 Lines • ▼ Show 20 Lines
	* rely on any input-dependent behaviour.			* rely on any input-dependent behaviour.
	*			*
	* This function has currently an effect only on contexts initialized for signing			* This function has currently an effect only on contexts initialized for signing
	* because randomization is currently used only for signing. However, this is not			* 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			* 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.			* contexts not initialized for signing; then it will have no effect and return 1.
	*			*
	* You should call this after secp256k1_context_create or			* You should call this after secp256k1_context_create or
	* secp256k1_context_clone, and may call this repeatedly afterwards.			* secp256k1_context_clone (and secp256k1_context_preallocated_create or
				* secp256k1_context_clone, resp.), and you may call this repeatedly afterwards.
	*/			*/
	SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_context_randomize(			SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_context_randomize(
	secp256k1_context* ctx,			secp256k1_context* ctx,
	const unsigned char *seed32			const unsigned char *seed32
	) SECP256K1_ARG_NONNULL(1);			) SECP256K1_ARG_NONNULL(1);

	/** Add a number of public keys together.			/** Add a number of public keys together.
	* Returns: 1: the sum of the public keys is valid.			* Returns: 1: the sum of the public keys is valid.
	Show All 19 Lines