Narrow C ABI exposing secp256k1 scalar and HMAC helpers to the C++ headers. More...

#include <stddef.h>
#include <stdint.h>
#include "purify/secp_context.h"

Data Structures
struct	purify_scalar
	Opaque scalar storage compatible with secp256k1-zkp internal scalar storage. More...

Typedefs
typedef struct purify_scalar	purify_scalar
	Opaque scalar storage compatible with secp256k1-zkp internal scalar storage.

Functions
void	purify_scalar_set_int (purify_scalar *out, unsigned int value)
	Initializes a scalar from an unsigned integer.

void	purify_scalar_set_u64 (purify_scalar *out, uint64_t value)
	Initializes a scalar from a 64-bit unsigned integer.

void	purify_scalar_set_b32 (purify_scalar out, const unsigned char input32[32], int overflow)
	Parses a big-endian 32-byte scalar.

void	purify_scalar_get_b32 (unsigned char output32[32], const purify_scalar *value)
	Serializes a scalar as 32 big-endian bytes.

int	purify_scalar_is_zero (const purify_scalar *value)
	Returns nonzero when the scalar is zero.

int	purify_scalar_is_one (const purify_scalar *value)
	Returns nonzero when the scalar is one.

int	purify_scalar_is_even (const purify_scalar *value)
	Returns nonzero when the scalar is even.

int	purify_scalar_eq (const purify_scalar lhs, const purify_scalar rhs)
	Returns nonzero when two scalars are equal.

void	purify_scalar_negate (purify_scalar out, const purify_scalar value)
	Computes the additive inverse of a scalar.

void	purify_scalar_inverse (purify_scalar out, const purify_scalar value)
	Computes the multiplicative inverse of a scalar in constant time.

void	purify_scalar_inverse_var (purify_scalar out, const purify_scalar value)
	Computes the multiplicative inverse of a scalar.

int	purify_scalar_add (purify_scalar out, const purify_scalar lhs, const purify_scalar *rhs)
	Adds two scalars modulo the backend field.

void	purify_scalar_mul (purify_scalar out, const purify_scalar lhs, const purify_scalar *rhs)
	Multiplies two scalars modulo the backend field.

void	purify_scalar_cmov (purify_scalar dst, const purify_scalar src, int flag)
	Conditionally assigns `src` into `dst` when `flag` is nonzero.

void	purify_sha256 (unsigned char output32[32], const unsigned char *data, size_t data_len)
	Computes SHA-256 over a byte string.

int	purify_sha256_many (unsigned char output32[32], const unsigned char const items, const size_t *item_lens, size_t items_count)
	Computes SHA-256 over a set of byte strings.

void	purify_hmac_sha256 (unsigned char output32[32], const unsigned char key, size_t key_len, const unsigned char data, size_t data_len)
	Computes HMAC-SHA256 over a byte string.

int	purify_bip340_key_from_seckey (purify_secp_context *context, unsigned char seckey32[32], unsigned char xonly_pubkey32[32])
	Canonicalizes a valid secp256k1 secret key for BIP340 and derives its x-only public key.

int	purify_bip340_nonce_from_scalar (purify_secp_context *context, unsigned char scalar32[32], unsigned char xonly_nonce32[32])
	Canonicalizes a valid secp256k1 nonce scalar for BIP340 and derives its x-only public nonce.

int	purify_bip340_xonly_from_point (purify_secp_context context, const unsigned char point33[33], unsigned char xonly32[32], int parity_out)
	Converts a compressed secp256k1 point into its x-only public key encoding.

int	purify_bip340_validate_xonly_pubkey (purify_secp_context *context, const unsigned char xonly_pubkey32[32])
	Returns nonzero when the x-only public key encoding parses successfully.

int	purify_bip340_validate_signature (purify_secp_context *context, const unsigned char sig64[64])
	Returns nonzero when the 64-byte BIP340 signature has a syntactically valid encoding.

int	purify_bip340_sign_with_fixed_nonce (purify_secp_context context, unsigned char sig64[64], const unsigned char msg, size_t msglen, const unsigned char seckey32[32], const unsigned char nonce32[32])
	Signs a message with a caller-supplied BIP340 nonce scalar.

int	purify_bip340_verify (purify_secp_context context, const unsigned char sig64[64], const unsigned char msg, size_t msglen, const unsigned char xonly_pubkey32[32])
	Verifies a BIP340 signature against a serialized x-only public key.

Typedef Documentation

◆ purify_scalar

typedef struct purify_scalar purify_scalar

Function Documentation

◆ purify_bip340_key_from_seckey()

int purify_bip340_key_from_seckey	(	purify_secp_context *	context,
		unsigned char	seckey32[32],
		unsigned char	xonly_pubkey32[32]
	)

The input/output seckey32 buffer is rewritten in place to the even-Y canonical secret scalar corresponding to the returned x-only public key. Returns zero when the input scalar is invalid.

Definition at line 525 of file bppp_bridge.c.

References purify_bridge_secure_clear(), and purify_context_handle().

Referenced by purify_derive_bip340_key().

◆ purify_bip340_nonce_from_scalar()

int purify_bip340_nonce_from_scalar	(	purify_secp_context *	context,
		unsigned char	scalar32[32],
		unsigned char	xonly_nonce32[32]
	)

The input/output scalar32 buffer is rewritten in place to the even-Y representative corresponding to the returned x-only public nonce. Returns zero when the input scalar is invalid or zero.

Definition at line 564 of file bppp_bridge.c.

References purify_bridge_secure_clear(), and purify_context_handle().

Referenced by purify_bip340_sign_with_fixed_nonce().

◆ purify_bip340_sign_with_fixed_nonce()

int purify_bip340_sign_with_fixed_nonce	(	purify_secp_context *	context,
		unsigned char	sig64[64],
		const unsigned char *	msg,
		size_t	msglen,
		const unsigned char	seckey32[32],
		const unsigned char	nonce32[32]
	)

seckey32 must be a valid secp256k1 secret key. nonce32 must be a non-zero canonical nonce scalar whose public point has even Y, for example the output of purify_bip340_nonce_from_scalar. Returns zero when any input is invalid.

Definition at line 707 of file bppp_bridge.c.

References purify_bip340_nonce_from_scalar(), purify_bridge_secure_clear(), purify_context_handle(), and purify_fixed_nonce_function().

Referenced by purify::puresign_plusplus::PreparedNonce::sign_message(), purify::puresign::PreparedNonce::sign_message(), purify::puresign_plusplus::PreparedNonce::sign_topic_message(), and purify::puresign::PreparedNonce::sign_topic_message().

◆ purify_bip340_validate_signature()

int purify_bip340_validate_signature	(	purify_secp_context *	context,
		const unsigned char	sig64[64]
	)

This only checks the standalone encoding shape (r as a valid x-only point and s as a scalar below the curve order). It does not verify the signature against a message or public key.

Definition at line 662 of file bppp_bridge.c.

References purify_bridge_secure_clear(), and purify_context_handle().

Referenced by purify::puresign_plusplus::Signature::deserialize(), purify::puresign::Signature::deserialize(), purify::puresign_plusplus::api_impl::verify_signature(), and purify::puresign::api_impl::verify_signature().

◆ purify_bip340_validate_xonly_pubkey()

int purify_bip340_validate_xonly_pubkey	(	purify_secp_context *	context,
		const unsigned char	xonly_pubkey32[32]
	)

Definition at line 645 of file bppp_bridge.c.

References purify_bridge_secure_clear(), and purify_context_handle().

Referenced by purify::puresign_plusplus::PublicKey::deserialize(), purify::puresign_plusplus::Nonce::deserialize(), purify::puresign_plusplus::NonceProof::deserialize(), purify::puresign::PublicKey::deserialize(), purify::puresign::Nonce::deserialize(), purify::puresign_plusplus::api_impl::verify_signature(), and purify::puresign::api_impl::verify_signature().

◆ purify_bip340_verify()

int purify_bip340_verify	(	purify_secp_context *	context,
		const unsigned char	sig64[64],
		const unsigned char *	msg,
		size_t	msglen,
		const unsigned char	xonly_pubkey32[32]
	)

Returns: Nonzero when the signature verifies.

Definition at line 758 of file bppp_bridge.c.

References purify_context_handle().

Referenced by purify::puresign_plusplus::PreparedNonce::sign_message(), purify::puresign::PreparedNonce::sign_message(), purify::puresign_plusplus::PreparedNonce::sign_topic_message(), purify::puresign::PreparedNonce::sign_topic_message(), purify::puresign_plusplus::api_impl::verify_signature(), and purify::puresign::api_impl::verify_signature().

◆ purify_bip340_xonly_from_point()

int purify_bip340_xonly_from_point	(	purify_secp_context *	context,
		const unsigned char	point33[33],
		unsigned char	xonly32[32],
		int *	parity_out
	)

Returns zero when the point encoding is invalid. When parity_out is not null it receives the original point parity as returned by secp256k1_xonly_pubkey_from_pubkey (0 for even Y, 1 for odd Y).

Definition at line 603 of file bppp_bridge.c.

References purify_bridge_secure_clear(), and purify_context_handle().

◆ purify_hmac_sha256()

void purify_hmac_sha256	(	unsigned char	output32[32],
		const unsigned char *	key,
		size_t	key_len,
		const unsigned char *	data,
		size_t	data_len
	)

Parameters

output32	Output MAC buffer.
key	Pointer to key bytes, or NULL when key_len is zero.
key_len	Key length in bytes.
data	Pointer to message bytes, or NULL when data_len is zero.
data_len	Message length in bytes.

Definition at line 504 of file bppp_bridge.c.

Referenced by purify::hmac_sha256(), and purify_core_hkdf_sha256().

◆ purify_scalar_add()

int purify_scalar_add	(	purify_scalar *	out,
		const purify_scalar *	lhs,
		const purify_scalar *	rhs
	)

Definition at line 442 of file bppp_bridge.c.

References purify_scalar_cast(), and purify_scalar_cast_const().

Referenced by purify_fe_add().

◆ purify_scalar_cmov()

void purify_scalar_cmov	(	purify_scalar *	dst,
		const purify_scalar *	src,
		int	flag
	)

Definition at line 450 of file bppp_bridge.c.

References purify_scalar_cast(), and purify_scalar_cast_const().

Referenced by purify::FieldElement::conditional_assign(), and purify_fe_cmov().

◆ purify_scalar_eq()

int purify_scalar_eq	(	const purify_scalar *	lhs,
		const purify_scalar *	rhs
	)

Definition at line 426 of file bppp_bridge.c.

References purify_scalar_cast_const().

Referenced by purify_fe_eq().

◆ purify_scalar_get_b32()

void purify_scalar_get_b32	(	unsigned char	output32[32],
		const purify_scalar *	value
	)

Definition at line 410 of file bppp_bridge.c.

References purify_scalar_cast_const().

Referenced by purify_fe_get_b32(), and purify::FieldElement::to_bytes_be().

◆ purify_scalar_inverse()

void purify_scalar_inverse	(	purify_scalar *	out,
		const purify_scalar *	value
	)

Definition at line 434 of file bppp_bridge.c.

References purify_scalar_cast(), and purify_scalar_cast_const().

Referenced by purify::FieldElement::inverse_consttime(), and purify_fe_inverse().

◆ purify_scalar_inverse_var()

void purify_scalar_inverse_var	(	purify_scalar *	out,
		const purify_scalar *	value
	)

Definition at line 438 of file bppp_bridge.c.

References purify_scalar_cast(), and purify_scalar_cast_const().

Referenced by purify::FieldElement::inverse(), and purify_fe_inverse_var().

◆ purify_scalar_is_even()

int purify_scalar_is_even ( const purify_scalar * value )

Definition at line 422 of file bppp_bridge.c.

References purify_scalar_cast_const().

Referenced by purify::FieldElement::is_odd(), and purify_fe_is_odd().

◆ purify_scalar_is_one()

int purify_scalar_is_one ( const purify_scalar * value )

Definition at line 418 of file bppp_bridge.c.

References purify_scalar_cast_const().

Referenced by purify::FieldElement::is_one(), and purify_fe_is_one().

◆ purify_scalar_is_zero()

int purify_scalar_is_zero ( const purify_scalar * value )

Definition at line 414 of file bppp_bridge.c.

References purify_scalar_cast_const().

Referenced by purify::FieldElement::is_zero(), and purify_fe_is_zero().

◆ purify_scalar_mul()

void purify_scalar_mul	(	purify_scalar *	out,
		const purify_scalar *	lhs,
		const purify_scalar *	rhs
	)

Definition at line 446 of file bppp_bridge.c.

References purify_scalar_cast(), and purify_scalar_cast_const().

Referenced by purify_fe_mul().

◆ purify_scalar_negate()

void purify_scalar_negate	(	purify_scalar *	out,
		const purify_scalar *	value
	)

Definition at line 430 of file bppp_bridge.c.

References purify_scalar_cast(), and purify_scalar_cast_const().

Referenced by purify::FieldElement::negate(), and purify_fe_negate().

◆ purify_scalar_set_b32()

void purify_scalar_set_b32	(	purify_scalar *	out,
		const unsigned char	input32[32],
		int *	overflow
	)

Definition at line 406 of file bppp_bridge.c.

References purify_scalar_cast().

Referenced by purify_fe_set_b32(), and purify::FieldElement::try_from_bytes32().

◆ purify_scalar_set_int()

void purify_scalar_set_int	(	purify_scalar *	out,
		unsigned int	value
	)

Definition at line 398 of file bppp_bridge.c.

References purify_scalar_cast().

Referenced by purify::FieldElement::FieldElement(), and purify_fe_set_zero().

◆ purify_scalar_set_u64()

void purify_scalar_set_u64	(	purify_scalar *	out,
		uint64_t	value
	)

Definition at line 402 of file bppp_bridge.c.

References purify_scalar_cast().

Referenced by purify::FieldElement::from_u64(), and purify_fe_set_u64().

◆ purify_sha256()

void purify_sha256	(	unsigned char	output32[32],
		const unsigned char *	data,
		size_t	data_len
	)

Parameters

output32	Output digest buffer.
data	Pointer to message bytes, or NULL when data_len is zero.
data_len	Message length in bytes.

Definition at line 454 of file bppp_bridge.c.

Referenced by purify::bppp::generator_backend_cache_key(), purify_curve_tag_hash(), and purify::TaggedHash::TaggedHash().

◆ purify_sha256_many()

int purify_sha256_many	(	unsigned char	output32[32],
		const unsigned char const	items,
		const size_t *	item_lens,
		size_t	items_count
	)

Parameters

output32	Output digest buffer.
items	Array of item pointers. Each item may be NULL only when the corresponding length is zero.
item_lens	Array of item lengths in bytes.
items_count	Number of items in both arrays.

Returns: Nonzero on success, zero on invalid input.

Definition at line 471 of file bppp_bridge.c.

Referenced by purify::TaggedHash::digest_many(), and purify_curve_hash_to_int_tagged_u320().

Data Structures

Typedefs

Functions

Typedef Documentation

◆ purify_scalar

Function Documentation

◆ purify_bip340_key_from_seckey()

◆ purify_bip340_nonce_from_scalar()

◆ purify_bip340_sign_with_fixed_nonce()

◆ purify_bip340_validate_signature()

◆ purify_bip340_validate_xonly_pubkey()

◆ purify_bip340_verify()

◆ purify_bip340_xonly_from_point()

◆ purify_hmac_sha256()

◆ purify_scalar_add()

◆ purify_scalar_cmov()

◆ purify_scalar_eq()

◆ purify_scalar_get_b32()

◆ purify_scalar_inverse()

◆ purify_scalar_inverse_var()

◆ purify_scalar_is_even()

◆ purify_scalar_is_one()

◆ purify_scalar_is_zero()

◆ purify_scalar_mul()

◆ purify_scalar_negate()

◆ purify_scalar_set_b32()

◆ purify_scalar_set_int()

◆ purify_scalar_set_u64()

◆ purify_sha256()

◆ purify_sha256_many()