ecc.h File Reference

Go to the source code of this file.

Data Structures
struct	ecc_set_type
struct	ecc_set_type
struct	alt_fp_int
struct	ecc_point
struct	ecc_key

Typedefs
typedef enum ecc_curve_id	ecc_curve_id
typedef word16	ecc_oid_t
typedef struct ecc_set_type	ecc_set_type
typedef struct alt_fp_int	alt_fp_int
typedef struct ecc_key	ecc_key
typedef struct ecEncCtx	ecEncCtx

Enumerations
enum	ecc_curve_id {   ECC_CURVE_INVALID = -1, ECC_CURVE_DEF = 0, ECC_SECP192R1, ECC_PRIME192V2,   ECC_PRIME192V3, ECC_PRIME239V1, ECC_PRIME239V2, ECC_PRIME239V3,   ECC_SECP256R1, ECC_SECP112R1, ECC_SECP112R2, ECC_SECP128R1,   ECC_SECP128R2, ECC_SECP160R1, ECC_SECP160R2, ECC_SECP224R1,   ECC_SECP384R1, ECC_SECP521R1, ECC_SECP160K1, ECC_SECP192K1,   ECC_SECP224K1, ECC_SECP256K1, ECC_BRAINPOOLP160R1, ECC_BRAINPOOLP192R1,   ECC_BRAINPOOLP224R1, ECC_BRAINPOOLP256R1, ECC_BRAINPOOLP320R1, ECC_BRAINPOOLP384R1,   ECC_BRAINPOOLP512R1, ECC_X25519, ECC_X448, ECC_CURVE_CUSTOM }
enum	{ WC_ECC_FLAG_NONE = 0x00, WC_ECC_FLAG_COFACTOR = 0x01 }
enum	ecEncAlgo { ecAES_128_CBC = 1, ecAES_256_CBC = 2 }
enum	ecKdfAlgo { ecHKDF_SHA256 = 1, ecHKDF_SHA1 = 2 }
enum	ecMacAlgo { ecHMAC_SHA256 = 1, ecHMAC_SHA1 = 2 }
enum	{   KEY_SIZE_128 = 16, KEY_SIZE_256 = 32, IV_SIZE_64 = 8, IV_SIZE_128 = 16,   EXCHANGE_SALT_SZ = 16, EXCHANGE_INFO_SZ = 23 }
enum	ecFlags { REQ_RESP_CLIENT = 1, REQ_RESP_SERVER = 2 }

Functions
WOLFSSL_ABI WOLFSSL_API ecc_key *	wc_ecc_key_new (void *)
WOLFSSL_ABI WOLFSSL_API void	wc_ecc_key_free (ecc_key *)
WOLFSSL_API const char *	wc_ecc_get_name (int curve_id)
ECC_API int	ecc_mul2add (ecc_point *A, mp_int *kA, ecc_point *B, mp_int *kB, ecc_point *C, mp_int *a, mp_int *modulus, void *heap)
ECC_API int	ecc_map (ecc_point *, mp_int *, mp_digit)
ECC_API int	ecc_map_ex (ecc_point *, mp_int *, mp_digit, int ct)
ECC_API int	ecc_projective_add_point (ecc_point *P, ecc_point *Q, ecc_point *R, mp_int *a, mp_int *modulus, mp_digit mp)
ECC_API int	ecc_projective_dbl_point (ecc_point *P, ecc_point *R, mp_int *a, mp_int *modulus, mp_digit mp)
WOLFSSL_API int	wc_ecc_make_key (WC_RNG *rng, int keysize, ecc_key *key)
	This function generates a new ecc_key and stores it in key. More...
WOLFSSL_ABI WOLFSSL_API int	wc_ecc_make_key_ex (WC_RNG *rng, int keysize, ecc_key *key, int curve_id)
	This function generates a new ecc_key and stores it in key. More...
WOLFSSL_API int	wc_ecc_make_pub (ecc_key *key, ecc_point *pubOut)
WOLFSSL_API int	wc_ecc_check_key (ecc_key *key)
	Perform sanity checks on ecc key validity. More...
WOLFSSL_API int	wc_ecc_is_point (ecc_point *ecp, mp_int *a, mp_int *b, mp_int *prime)
WOLFSSL_API int	wc_ecc_get_generator (ecc_point *ecp, int curve_idx)
WOLFSSL_API int	wc_ecc_shared_secret (ecc_key *private_key, ecc_key *public_key, byte *out, word32 *outlen)
	This function generates a new secret key using a local private key and a received public key. It stores this shared secret key in the buffer out and updates outlen to hold the number of bytes written to the output buffer. More...
WOLFSSL_LOCAL int	wc_ecc_shared_secret_gen (ecc_key *private_key, ecc_point *point, byte *out, word32 *outlen)
WOLFSSL_API int	wc_ecc_shared_secret_ex (ecc_key *private_key, ecc_point *point, byte *out, word32 *outlen)
	Create an ECC shared secret between private key and public point. More...
WOLFSSL_ABI WOLFSSL_API int	wc_ecc_sign_hash (const byte *in, word32 inlen, byte *out, word32 *outlen, WC_RNG *rng, ecc_key *key)
	This function signs a message digest using an ecc_key object to guarantee authenticity. More...
WOLFSSL_API int	wc_ecc_sign_hash_ex (const byte *in, word32 inlen, WC_RNG *rng, ecc_key *key, mp_int *r, mp_int *s)
	Sign a message digest. More...
WOLFSSL_API int	wc_ecc_sign_set_k (const byte *k, word32 klen, ecc_key *key)
WOLFSSL_API int	wc_ecc_verify_hash (const byte *sig, word32 siglen, const byte *hash, word32 hashlen, int *stat, ecc_key *key)
	This function verifies the ECC signature of a hash to ensure authenticity. It returns the answer through stat, with 1 corresponding to a valid signature, and 0 corresponding to an invalid signature. More...
WOLFSSL_API int	wc_ecc_verify_hash_ex (mp_int *r, mp_int *s, const byte *hash, word32 hashlen, int *stat, ecc_key *key)
	Verify an ECC signature. Result is written to stat. 1 is valid, 0 is invalid. Note: Do not use the return value to test for valid. Only use stat. More...
WOLFSSL_API int	wc_ecc_init (ecc_key *key)
	This function initializes an ecc_key object for future use with message verification or key negotiation. More...
WOLFSSL_ABI WOLFSSL_API int	wc_ecc_init_ex (ecc_key *key, void *heap, int devId)
WOLFSSL_API int	wc_ecc_init_id (ecc_key *key, unsigned char *id, int len, void *heap, int devId)
WOLFSSL_LOCAL void	wc_ecc_free_curve (const ecc_set_type *curve, void *heap)
WOLFSSL_ABI WOLFSSL_API int	wc_ecc_free (ecc_key *key)
	This function frees an ecc_key object after it has been used. More...
WOLFSSL_API int	wc_ecc_set_flags (ecc_key *key, word32 flags)
WOLFSSL_API void	wc_ecc_fp_free (void)
	This function frees the fixed-point cache, which can be used with ecc to speed up computation times. To use this functionality, FP_ECC (fixed-point ecc), should be defined. More...
WOLFSSL_API int	wc_ecc_set_curve (ecc_key *key, int keysize, int curve_id)
WOLFSSL_API int	wc_ecc_is_valid_idx (int n)
	Checks if an ECC idx is valid. More...
WOLFSSL_API int	wc_ecc_get_curve_idx (int curve_id)
WOLFSSL_API int	wc_ecc_get_curve_id (int curve_idx)
WOLFSSL_API int	wc_ecc_get_curve_size_from_id (int curve_id)
WOLFSSL_API int	wc_ecc_get_curve_idx_from_name (const char *curveName)
WOLFSSL_API int	wc_ecc_get_curve_size_from_name (const char *curveName)
WOLFSSL_API int	wc_ecc_get_curve_id_from_name (const char *curveName)
WOLFSSL_API int	wc_ecc_get_curve_id_from_params (int fieldSize, const byte *prime, word32 primeSz, const byte *Af, word32 AfSz, const byte *Bf, word32 BfSz, const byte *order, word32 orderSz, const byte *Gx, word32 GxSz, const byte *Gy, word32 GySz, int cofactor)
WOLFSSL_API int	wc_ecc_get_curve_id_from_dp_params (const ecc_set_type *dp)
WOLFSSL_API int	wc_ecc_get_curve_id_from_oid (const byte *oid, word32 len)
WOLFSSL_API const ecc_set_type *	wc_ecc_get_curve_params (int curve_idx)
WOLFSSL_API ecc_point *	wc_ecc_new_point (void)
	Allocate a new ECC point. More...
WOLFSSL_API ecc_point *	wc_ecc_new_point_h (void *h)
WOLFSSL_API void	wc_ecc_del_point (ecc_point *p)
	Free an ECC point from memory. More...
WOLFSSL_API void	wc_ecc_del_point_h (ecc_point *p, void *h)
WOLFSSL_API int	wc_ecc_copy_point (ecc_point *p, ecc_point *r)
	Copy the value of one point to another one. More...
WOLFSSL_API int	wc_ecc_cmp_point (ecc_point *a, ecc_point *b)
	Compare the value of a point with another one. More...
WOLFSSL_API int	wc_ecc_point_is_at_infinity (ecc_point *p)
	Checks if a point is at infinity. Returns 1 if point is at infinity, 0 if not, < 0 on error. More...
WOLFSSL_API int	wc_ecc_mulmod (mp_int *k, ecc_point *G, ecc_point *R, mp_int *a, mp_int *modulus, int map)
	Perform ECC Fixed Point multiplication. More...
WOLFSSL_LOCAL int	wc_ecc_mulmod_ex (mp_int *k, ecc_point *G, ecc_point *R, mp_int *a, mp_int *modulus, int map, void *heap)
WOLFSSL_API int	wc_ecc_export_x963 (ecc_key *, byte *out, word32 *outLen)
	This function exports the ECC key from the ecc_key structure, storing the result in out. The key will be stored in ANSI X9.63 format. It stores the bytes written to the output buffer in outLen. More...
WOLFSSL_API int	wc_ecc_export_x963_ex (ecc_key *, byte *out, word32 *outLen, int compressed)
	This function exports the ECC key from the ecc_key structure, storing the result in out. The key will be stored in ANSI X9.63 format. It stores the bytes written to the output buffer in outLen. This function allows the additional option of compressing the certificate through the compressed parameter. When this parameter is true, the key will be stored in ANSI X9.63 compressed format. More...
WOLFSSL_ABI WOLFSSL_API int	wc_ecc_import_x963 (const byte *in, word32 inLen, ecc_key *key)
	This function imports a public ECC key from a buffer containing the key stored in ANSI X9.63 format. This function will handle both compressed and uncompressed keys, as long as compressed keys are enabled at compile time through the HAVE_COMP_KEY option. More...
WOLFSSL_API int	wc_ecc_import_x963_ex (const byte *in, word32 inLen, ecc_key *key, int curve_id)
WOLFSSL_API int	wc_ecc_import_private_key (const byte *priv, word32 privSz, const byte *pub, word32 pubSz, ecc_key *key)
	This function imports a public/private ECC key pair from a buffer containing the raw private key, and a second buffer containing the ANSI X9.63 formatted public key. This function will handle both compressed and uncompressed keys, as long as compressed keys are enabled at compile time through the HAVE_COMP_KEY option. More...
WOLFSSL_API int	wc_ecc_import_private_key_ex (const byte *priv, word32 privSz, const byte *pub, word32 pubSz, ecc_key *key, int curve_id)
WOLFSSL_API int	wc_ecc_rs_to_sig (const char *r, const char *s, byte *out, word32 *outlen)
	This function converts the R and S portions of an ECC signature into a DER-encoded ECDSA signature. This function also stores the length written to the output buffer, out, in outlen. More...
WOLFSSL_API int	wc_ecc_rs_raw_to_sig (const byte *r, word32 rSz, const byte *s, word32 sSz, byte *out, word32 *outlen)
WOLFSSL_API int	wc_ecc_sig_to_rs (const byte *sig, word32 sigLen, byte *r, word32 *rLen, byte *s, word32 *sLen)
WOLFSSL_API int	wc_ecc_import_raw (ecc_key *key, const char *qx, const char *qy, const char *d, const char *curveName)
	This function fills an ecc_key structure with the raw components of an ECC signature. More...
WOLFSSL_API int	wc_ecc_import_raw_ex (ecc_key *key, const char *qx, const char *qy, const char *d, int curve_id)
WOLFSSL_API int	wc_ecc_import_unsigned (ecc_key *key, byte *qx, byte *qy, byte *d, int curve_id)
WOLFSSL_API int	wc_ecc_export_ex (ecc_key *key, byte *qx, word32 *qxLen, byte *qy, word32 *qyLen, byte *d, word32 *dLen, int encType)
WOLFSSL_API int	wc_ecc_export_private_only (ecc_key *key, byte *out, word32 *outLen)
	This function exports only the private key from an ecc_key structure. It stores the private key in the buffer out, and sets the bytes written to this buffer in outLen. More...
WOLFSSL_API int	wc_ecc_export_public_raw (ecc_key *key, byte *qx, word32 *qxLen, byte *qy, word32 *qyLen)
WOLFSSL_API int	wc_ecc_export_private_raw (ecc_key *key, byte *qx, word32 *qxLen, byte *qy, word32 *qyLen, byte *d, word32 *dLen)
WOLFSSL_API int	wc_ecc_export_point_der_ex (const int curve_idx, ecc_point *point, byte *out, word32 *outLen, int compressed)
WOLFSSL_API int	wc_ecc_export_point_der (const int curve_idx, ecc_point *point, byte *out, word32 *outLen)
	Export point to der. More...
WOLFSSL_LOCAL int	wc_ecc_export_point_der_compressed (const int curve_idx, ecc_point *point, byte *out, word32 *outLen)
WOLFSSL_API int	wc_ecc_import_point_der_ex (byte *in, word32 inLen, const int curve_idx, ecc_point *point, int shortKeySize)
WOLFSSL_API int	wc_ecc_import_point_der (byte *in, word32 inLen, const int curve_idx, ecc_point *point)
	Import point from der format. More...
WOLFSSL_API int	wc_ecc_size (ecc_key *key)
	This function returns the key size of an ecc_key structure in octets. More...
WOLFSSL_API int	wc_ecc_sig_size_calc (int sz)
	This function returns the worst case size for an ECC signature, given by: (keySz * 2) + SIG_HEADER_SZ + ECC_MAX_PAD_SZ. The actual signature size can be computed with wc_ecc_sign_hash. More...
WOLFSSL_API int	wc_ecc_sig_size (ecc_key *key)
	This function returns the worst case size for an ECC signature, given by: (keySz * 2) + SIG_HEADER_SZ + ECC_MAX_PAD_SZ. The actual signature size can be computed with wc_ecc_sign_hash. More...
WOLFSSL_API int	wc_ecc_get_oid (word32 oidSum, const byte **oid, word32 *oidSz)
WOLFSSL_API int	wc_ecc_set_custom_curve (ecc_key *key, const ecc_set_type *dp)
WOLFSSL_API ecEncCtx *	wc_ecc_ctx_new (int flags, WC_RNG *rng)
	This function allocates and initializes space for a new ECC context object to allow secure message exchange with ECC. More...
WOLFSSL_API ecEncCtx *	wc_ecc_ctx_new_ex (int flags, WC_RNG *rng, void *heap)
WOLFSSL_API void	wc_ecc_ctx_free (ecEncCtx *)
	This function frees the ecEncCtx object used for encrypting and decrypting messages. More...
WOLFSSL_API int	wc_ecc_ctx_reset (ecEncCtx *, WC_RNG *)
	This function resets an ecEncCtx structure to avoid having to free and allocate a new context object. More...
WOLFSSL_API const byte *	wc_ecc_ctx_get_own_salt (ecEncCtx *)
	This function returns the salt of an ecEncCtx object. This function should only be called when the ecEncCtx's state is ecSRV_INIT or ecCLI_INIT. More...
WOLFSSL_API int	wc_ecc_ctx_set_peer_salt (ecEncCtx *, const byte *salt)
	This function sets the peer salt of an ecEncCtx object. More...
WOLFSSL_API int	wc_ecc_ctx_set_info (ecEncCtx *, const byte *info, int sz)
	This function can optionally be called before or after wc_ecc_ctx_set_peer_salt. It sets optional information for an ecEncCtx object. More...
WOLFSSL_API int	wc_ecc_encrypt (ecc_key *privKey, ecc_key *pubKey, const byte *msg, word32 msgSz, byte *out, word32 *outSz, ecEncCtx *ctx)
	This function encrypts the given input message from msg to out. This function takes an optional ctx object as parameter. When supplied, encryption proceeds based on the ecEncCtx's encAlgo, kdfAlgo, and macAlgo. If ctx is not supplied, processing completes with the default algorithms, ecAES_128_CBC, ecHKDF_SHA256 and ecHMAC_SHA256. This function requires that the messages are padded according to the encryption type specified by ctx. More...
WOLFSSL_API int	wc_ecc_decrypt (ecc_key *privKey, ecc_key *pubKey, const byte *msg, word32 msgSz, byte *out, word32 *outSz, ecEncCtx *ctx)
	This function decrypts the ciphertext from msg to out. This function takes an optional ctx object as parameter. When supplied, encryption proceeds based on the ecEncCtx's encAlgo, kdfAlgo, and macAlgo. If ctx is not supplied, processing completes with the default algorithms, ecAES_128_CBC, ecHKDF_SHA256 and ecHMAC_SHA256. This function requires that the messages are padded according to the encryption type specified by ctx. More...
WOLFSSL_API int	wc_X963_KDF (enum wc_HashType type, const byte *secret, word32 secretSz, const byte *sinfo, word32 sinfoSz, byte *out, word32 outSz)
WOLFSSL_API int	wc_ecc_curve_cache_init (void)
WOLFSSL_API void	wc_ecc_curve_cache_free (void)
WOLFSSL_API int	wc_ecc_gen_k (WC_RNG *rng, int size, mp_int *k, mp_int *order)
WOLFSSL_API int	wc_ecc_set_handle (ecc_key *key, remote_handle64 handle)
WOLFSSL_LOCAL int	sp_dsp_ecc_verify_256 (remote_handle64 handle, const byte *hash, word32 hashLen, mp_int *pX, mp_int *pY, mp_int *pZ, mp_int *r, mp_int *sm, int *res, void *heap)

Variables
	C
const ecc_set_type	ecc_sets []
const size_t	ecc_sets_count

Function Documentation

ecc_map_ex()

ECC_API int ecc_map_ex	(	ecc_point *	P,
		mp_int *	modulus,
		mp_digit	mp,
		int	ct
	)

Map a projective Jacobian point back to affine space P [in/out] The point to map modulus The modulus of the field the ECC curve is in mp The "b" value from montgomery_setup() ct Operation should be constant time. return MP_OKAY on success

ecc_mul2add()

ECC_API int ecc_mul2add	(	ecc_point *	A,
		mp_int *	kA,
		ecc_point *	B,
		mp_int *	kB,
		ecc_point *	C,
		mp_int *	a,
		mp_int *	modulus,
		void *	heap
	)

ECC Fixed Point mulmod global with heap hint used Computes kA*A + kB*B = C using Shamir's Trick A First point to multiply kA What to multiple A by B Second point to multiply kB What to multiple B by C [out] Destination point (can overlap with A or B) a ECC curve parameter a modulus Modulus for curve return MP_OKAY on success

ecc_projective_add_point()

ECC_API int ecc_projective_add_point	(	ecc_point *	P,
		ecc_point *	Q,
		ecc_point *	R,
		mp_int *	a,
		mp_int *	modulus,
		mp_digit	mp
	)

Add two ECC points P The point to add Q The point to add R [out] The destination of the double a ECC curve parameter a modulus The modulus of the field the ECC curve is in mp The "b" value from montgomery_setup() return MP_OKAY on success

ecc_projective_dbl_point()

ECC_API int ecc_projective_dbl_point	(	ecc_point *	P,
		ecc_point *	R,
		mp_int *	a,
		mp_int *	modulus,
		mp_digit	mp
	)

Double an ECC point P The point to double R [out] The destination of the double a ECC curve parameter a modulus The modulus of the field the ECC curve is in mp The "b" value from montgomery_setup() return MP_OKAY on success

wc_ecc_import_raw_ex()

WOLFSSL_API int wc_ecc_import_raw_ex	(	ecc_key *	key,
		const char *	qx,
		const char *	qy,
		const char *	d,
		int	curve_id
	)

Import raw ECC key key The destination ecc_key structure qx x component of the public key, as ASCII hex string qy y component of the public key, as ASCII hex string d private key, as ASCII hex string, optional if importing public key only dp Custom ecc_set_type return MP_OKAY on success

wc_ecc_mulmod_ex()

WOLFSSL_LOCAL int wc_ecc_mulmod_ex	(	mp_int *	k,
		ecc_point *	G,
		ecc_point *	R,
		mp_int *	a,
		mp_int *	modulus,
		int	map,
		void *	heap
	)

ECC Fixed Point mulmod global k The multiplicand G Base point to multiply R [out] Destination of product a ECC curve parameter a modulus The modulus for the curve map [boolean] If non-zero maps the point back to affine coordinates, otherwise it's left in jacobian-montgomery form return MP_OKAY if successful

Perform a point multiplication (timing resistant) k The scalar to multiply by G The base point R [out] Destination for kG modulus The modulus of the field the ECC curve is in map Boolean whether to map back to affine or not (1==map, 0 == leave in projective) return MP_OKAY on success

wc_ecc_new_point_h()

WOLFSSL_API ecc_point* wc_ecc_new_point_h

(

void *

heap

)

use a heap hint when creating new ecc_point return an allocated point on success or NULL on failure

wc_ecc_rs_raw_to_sig()

WOLFSSL_API int wc_ecc_rs_raw_to_sig	(	const byte *	r,
		word32	rSz,
		const byte *	s,
		word32	sSz,
		byte *	out,
		word32 *	outlen
	)

Convert ECC R,S raw unsigned bin to signature r R component of signature rSz R size s S component of signature sSz S size out DER-encoded ECDSA signature outlen [in/out] output buffer size, output signature size return MP_OKAY on success

wc_ecc_sig_to_rs()

WOLFSSL_API int wc_ecc_sig_to_rs	(	const byte *	sig,
		word32	sigLen,
		byte *	r,
		word32 *	rLen,
		byte *	s,
		word32 *	sLen
	)

Convert ECC signature to R,S sig DER-encoded ECDSA signature sigLen length of signature in octets r R component of signature rLen [in/out] output "r" buffer size, output "r" size s S component of signature sLen [in/out] output "s" buffer size, output "s" size return MP_OKAY on success, negative on error