purify.h File Reference

Public C core for Purify key validation, key derivation, key generation, and evaluation. More...

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

Go to the source code of this file.

Data Structures
struct	purify_generated_key
	Seed/public-key bundle returned by the C core key-generation entry points. More...
struct	purify_bip340_key
	Canonical BIP340 keypair derived from one packed Purify secret. More...

Macros
#define	PURIFY_SECRET_KEY_BYTES   64u
#define	PURIFY_PUBLIC_KEY_BYTES   64u
#define	PURIFY_FIELD_ELEMENT_BYTES   32u
#define	PURIFY_BIP340_SECRET_KEY_BYTES   32u
#define	PURIFY_BIP340_XONLY_PUBKEY_BYTES   32u

Typedefs
typedef enum purify_error_code	purify_error_code
	Machine-readable status code returned by the Purify C core.
typedef struct purify_generated_key	purify_generated_key
	Seed/public-key bundle returned by the C core key-generation entry points.
typedef struct purify_bip340_key	purify_bip340_key
	Canonical BIP340 keypair derived from one packed Purify secret.

Enumerations
enum	purify_error_code {   PURIFY_ERROR_OK = 0 , PURIFY_ERROR_INVALID_HEX , PURIFY_ERROR_INVALID_HEX_LENGTH , PURIFY_ERROR_INVALID_FIXED_SIZE ,   PURIFY_ERROR_OVERFLOW , PURIFY_ERROR_UNDERFLOW , PURIFY_ERROR_NARROWING_OVERFLOW , PURIFY_ERROR_DIVISION_BY_ZERO ,   PURIFY_ERROR_BIT_INDEX_OUT_OF_RANGE , PURIFY_ERROR_RANGE_VIOLATION , PURIFY_ERROR_EMPTY_INPUT , PURIFY_ERROR_SIZE_MISMATCH ,   PURIFY_ERROR_MISSING_VALUE , PURIFY_ERROR_INVALID_SYMBOL , PURIFY_ERROR_UNSUPPORTED_SYMBOL , PURIFY_ERROR_UNINITIALIZED_STATE ,   PURIFY_ERROR_INDEX_OUT_OF_RANGE , PURIFY_ERROR_INVALID_DIMENSIONS , PURIFY_ERROR_NON_BOOLEAN_VALUE , PURIFY_ERROR_EQUATION_MISMATCH ,   PURIFY_ERROR_BINDING_MISMATCH , PURIFY_ERROR_IO_OPEN_FAILED , PURIFY_ERROR_IO_WRITE_FAILED , PURIFY_ERROR_ENTROPY_UNAVAILABLE ,   PURIFY_ERROR_BACKEND_REJECTED_INPUT , PURIFY_ERROR_HASH_TO_CURVE_EXHAUSTED , PURIFY_ERROR_UNEXPECTED_SIZE , PURIFY_ERROR_GENERATOR_ORDER_CHECK_FAILED ,   PURIFY_ERROR_INTERNAL_MISMATCH , PURIFY_ERROR_TRANSCRIPT_CHECK_FAILED }
	Machine-readable status code returned by the Purify C core. More...

Functions
const char *	purify_error_name (purify_error_code code)
	Returns a stable programmatic name for one status code.
const char *	purify_error_message (purify_error_code code)
	Returns a human-facing description for one status code.
purify_error_code	purify_fill_secure_random (unsigned char *bytes, size_t bytes_len)
	Fills a caller-owned buffer with secure operating-system randomness.
purify_error_code	purify_validate_secret_key (const unsigned char secret_key[PURIFY_SECRET_KEY_BYTES])
	Validates one packed Purify secret key.
purify_error_code	purify_validate_public_key (const unsigned char public_key[PURIFY_PUBLIC_KEY_BYTES])
	Validates one packed Purify public key.
purify_error_code	purify_generate_key (purify_generated_key *out)
	Generates one random Purify keypair.
purify_error_code	purify_generate_key_from_seed (purify_generated_key *out, const unsigned char *seed, size_t seed_len)
	Deterministically derives one Purify keypair from seed material.
purify_error_code	purify_derive_public_key (unsigned char out_public_key[PURIFY_PUBLIC_KEY_BYTES], const unsigned char secret_key[PURIFY_SECRET_KEY_BYTES])
	Derives the packed public key corresponding to one packed Purify secret.
purify_error_code	purify_derive_bip340_key (purify_bip340_key *out, const unsigned char secret_key[PURIFY_SECRET_KEY_BYTES], purify_secp_context *secp_context)
	Derives one canonical BIP340 keypair from one packed Purify secret.
purify_error_code	purify_eval (unsigned char out_field_element[PURIFY_FIELD_ELEMENT_BYTES], const unsigned char secret_key[PURIFY_SECRET_KEY_BYTES], const unsigned char *message, size_t message_len)
	Evaluates the Purify PRF for one packed secret and message.

Macro Definition Documentation

PURIFY_BIP340_SECRET_KEY_BYTES

#define PURIFY_BIP340_SECRET_KEY_BYTES   32u

Definition at line 20 of file purify.h.

PURIFY_BIP340_XONLY_PUBKEY_BYTES

#define PURIFY_BIP340_XONLY_PUBKEY_BYTES   32u

Definition at line 21 of file purify.h.

PURIFY_FIELD_ELEMENT_BYTES

#define PURIFY_FIELD_ELEMENT_BYTES   32u

Definition at line 19 of file purify.h.

PURIFY_PUBLIC_KEY_BYTES

#define PURIFY_PUBLIC_KEY_BYTES   64u

Definition at line 18 of file purify.h.

PURIFY_SECRET_KEY_BYTES

#define PURIFY_SECRET_KEY_BYTES   64u

Definition at line 17 of file purify.h.

Typedef Documentation

purify_bip340_key

typedef struct purify_bip340_key purify_bip340_key

purify_error_code

typedef enum purify_error_code purify_error_code

purify_generated_key

typedef struct purify_generated_key purify_generated_key

Enumeration Type Documentation

purify_error_code

enum purify_error_code

Enumerator
PURIFY_ERROR_OK
PURIFY_ERROR_INVALID_HEX
PURIFY_ERROR_INVALID_HEX_LENGTH
PURIFY_ERROR_INVALID_FIXED_SIZE
PURIFY_ERROR_OVERFLOW
PURIFY_ERROR_UNDERFLOW
PURIFY_ERROR_NARROWING_OVERFLOW
PURIFY_ERROR_DIVISION_BY_ZERO
PURIFY_ERROR_BIT_INDEX_OUT_OF_RANGE
PURIFY_ERROR_RANGE_VIOLATION
PURIFY_ERROR_EMPTY_INPUT
PURIFY_ERROR_SIZE_MISMATCH
PURIFY_ERROR_MISSING_VALUE
PURIFY_ERROR_INVALID_SYMBOL
PURIFY_ERROR_UNSUPPORTED_SYMBOL
PURIFY_ERROR_UNINITIALIZED_STATE
PURIFY_ERROR_INDEX_OUT_OF_RANGE
PURIFY_ERROR_INVALID_DIMENSIONS
PURIFY_ERROR_NON_BOOLEAN_VALUE
PURIFY_ERROR_EQUATION_MISMATCH
PURIFY_ERROR_BINDING_MISMATCH
PURIFY_ERROR_IO_OPEN_FAILED
PURIFY_ERROR_IO_WRITE_FAILED
PURIFY_ERROR_ENTROPY_UNAVAILABLE
PURIFY_ERROR_BACKEND_REJECTED_INPUT
PURIFY_ERROR_HASH_TO_CURVE_EXHAUSTED
PURIFY_ERROR_UNEXPECTED_SIZE
PURIFY_ERROR_GENERATOR_ORDER_CHECK_FAILED
PURIFY_ERROR_INTERNAL_MISMATCH
PURIFY_ERROR_TRANSCRIPT_CHECK_FAILED

Definition at line 28 of file purify.h.

Function Documentation

purify_derive_bip340_key()

purify_error_code purify_derive_bip340_key	(	purify_bip340_key *	out,
		const unsigned char	secret_key[PURIFY_SECRET_KEY_BYTES],
		purify_secp_context *	secp_context
	)

Parameters

out	Output BIP340 keypair.
secret_key	Input 64-byte packed Purify secret.
secp_context	Caller-owned reusable context created by purify_secp_context_create. Aliasing: supported when out overlaps secret_key.

Returns

PURIFY_ERROR_OK on success.

Definition at line 217 of file c_api.cpp.

References purify::bytes_from_ascii(), purify::capi_detail::clear_bip340_key(), purify::Expected< T, E >::error(), purify::Expected< T, E >::has_value(), purify::capi_detail::parse_secret_key(), purify_bip340_key_from_seckey(), PURIFY_ERROR_BACKEND_REJECTED_INPUT, PURIFY_ERROR_INTERNAL_MISMATCH, PURIFY_ERROR_MISSING_VALUE, PURIFY_ERROR_OK, scalar, purify::capi_detail::secp256k1_order_minus_one(), purify_bip340_key::secret_key, purify::detail::secure_clear_bytes(), purify::core_api_detail::to_core_error_code(), and purify_bip340_key::xonly_public_key.

Referenced by purify::derive_bip340_key().

purify_derive_public_key()

purify_error_code purify_derive_public_key	(	unsigned char	out_public_key[PURIFY_PUBLIC_KEY_BYTES],
		const unsigned char	secret_key[PURIFY_SECRET_KEY_BYTES]
	)

Parameters

out_public_key	Output 64-byte packed Purify public key.
secret_key	Input 64-byte packed Purify secret. Aliasing: supported when out_public_key overlaps secret_key.

Returns

PURIFY_ERROR_OK on success.

Definition at line 196 of file c_api.cpp.

References purify::capi_detail::derive_public_key_from_secret(), purify::Expected< T, E >::error(), purify::Expected< T, E >::has_value(), purify::capi_detail::parse_secret_key(), PURIFY_ERROR_MISSING_VALUE, PURIFY_ERROR_OK, PURIFY_PUBLIC_KEY_BYTES, purify::core_api_detail::to_core_error_code(), and purify::capi_detail::write_uint512().

Referenced by purify::derive_key().

purify_error_message()

const char * purify_error_message

(

purify_error_code

code

)

Definition at line 251 of file core.c.

References kErrorMessages.

purify_error_name()

const char * purify_error_name

(

purify_error_code

code

)

Definition at line 242 of file core.c.

References kErrorNames.

purify_eval()

purify_error_code purify_eval	(	unsigned char	out_field_element[PURIFY_FIELD_ELEMENT_BYTES],
		const unsigned char	secret_key[PURIFY_SECRET_KEY_BYTES],
		const unsigned char *	message,
		size_t	message_len
	)

Parameters

out_field_element	Output 32-byte big-endian field element.
secret_key	Input 64-byte packed Purify secret.
message	Message bytes. May be NULL only when message_len == 0.
message_len	Message length in bytes. Aliasing: supported when out_field_element overlaps secret_key and/or message.

Returns

PURIFY_ERROR_OK on success.

Definition at line 263 of file c_api.cpp.

References purify::combine(), purify::capi_detail::copy_bytes(), purify::curve1(), purify::curve2(), purify::Expected< T, E >::error(), purify::Expected< T, E >::has_value(), purify::hash_to_curve(), purify::EllipticCurve::mul_secret_affine(), purify::capi_detail::parse_secret_key(), PURIFY_ERROR_MISSING_VALUE, PURIFY_ERROR_OK, PURIFY_FIELD_ELEMENT_BYTES, purify::capi_detail::tagged_message(), purify::core_api_detail::to_core_error_code(), purify::unpack_secret(), and purify::capi_detail::write_field_element().

Referenced by purify::eval().

purify_fill_secure_random()

purify_error_code purify_fill_secure_random	(	unsigned char *	bytes,
		size_t	bytes_len
	)

Parameters

bytes	Buffer to fill. May be NULL only when bytes_len == 0.
bytes_len	Buffer length in bytes.

Returns

PURIFY_ERROR_OK on success.

Definition at line 260 of file core.c.

References PURIFY_ERROR_ENTROPY_UNAVAILABLE, PURIFY_ERROR_MISSING_VALUE, and PURIFY_ERROR_OK.

Referenced by purify::fill_secure_random(), purify_core_sample_secret_key(), and purify_secp_context_create().

purify_generate_key()

purify_error_code purify_generate_key

(

purify_generated_key *

out

)

Parameters

out	Output bundle.

Returns

PURIFY_ERROR_OK on success.

Definition at line 134 of file c_api.cpp.

References purify::capi_detail::clear_generated_key(), purify::capi_detail::derive_public_key_from_secret(), purify::Expected< T, E >::error(), purify::Expected< T, E >::has_value(), purify::capi_detail::parse_secret_key(), purify_generated_key::public_key, purify_core_sample_secret_key(), PURIFY_ERROR_MISSING_VALUE, PURIFY_ERROR_OK, purify_generated_key::secret_key, purify::core_api_detail::to_core_error_code(), and purify::capi_detail::write_uint512().

Referenced by purify::generate_key().

purify_generate_key_from_seed()

purify_error_code purify_generate_key_from_seed	(	purify_generated_key *	out,
		const unsigned char *	seed,
		size_t	seed_len
	)

Parameters

out	Output bundle.
seed	Seed bytes. May be NULL only when seed_len == 0.
seed_len	Seed length in bytes. Values shorter than 16 bytes are rejected. Aliasing: supported when seed points anywhere inside out.

Returns

PURIFY_ERROR_OK on success.

Definition at line 161 of file c_api.cpp.

References purify::capi_detail::clear_generated_key(), purify::capi_detail::copy_bytes(), purify::capi_detail::derive_public_key_from_secret(), purify::Expected< T, E >::error(), purify::Expected< T, E >::has_value(), purify::capi_detail::parse_secret_key(), purify_generated_key::public_key, purify_core_seed_secret_key(), PURIFY_ERROR_MISSING_VALUE, PURIFY_ERROR_OK, purify::capi_detail::ranges_overlap(), purify_generated_key::secret_key, purify::core_api_detail::to_core_error_code(), and purify::capi_detail::write_uint512().

Referenced by purify::generate_key().

purify_validate_public_key()

purify_error_code purify_validate_public_key

(

const unsigned char

public_key[PURIFY_PUBLIC_KEY_BYTES]

)

Parameters

public_key

64-byte packed Purify public key.

Returns

PURIFY_ERROR_OK when the packed public key is canonical.

Definition at line 311 of file core.c.

References kPackedPublicKeySpaceSize, purify_core_validate_below(), and PURIFY_PUBLIC_KEY_BYTES.

Referenced by purify::capi_detail::parse_public_key().

purify_validate_secret_key()

purify_error_code purify_validate_secret_key

(

const unsigned char

secret_key[PURIFY_SECRET_KEY_BYTES]

)

Parameters

secret_key

64-byte packed Purify secret.

Returns

PURIFY_ERROR_OK when the packed secret is canonical.

Definition at line 307 of file core.c.

References kPackedSecretKeySpaceSize, purify_core_validate_below(), and PURIFY_SECRET_KEY_BYTES.

Referenced by purify::capi_detail::parse_secret_key().