ecc.h

Functions

	Name
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.
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.
int	wc_ecc_make_pub(ecc_key * key, ecc_point * pubOut) wc_ecc_make_pub computes the public component from an ecc_key with an existing private component. If pubOut is supplied, the computed public key is stored there, else it is stored in the supplied ecc_key public component slot.
int	wc_ecc_make_pub_ex(ecc_key * key, ecc_point * pubOut, WC_RNG * rng) wc_ecc_make_pub_ex computes the public component from an ecc_key with an existing private component. If pubOut is supplied, the computed public key is stored there, else it is stored in the supplied ecc_key public component slot. The supplied rng, if non-NULL, is used to blind the private key value used in the computation.
int	wc_ecc_check_key(ecc_key * key) Perform sanity checks on ecc key validity.
void	wc_ecc_key_free(ecc_key * key) This function frees an ecc_key key after it has been used.
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.
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.
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.
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.
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.
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.
int	wc_ecc_init(ecc_key * key) This function initializes an ecc_key object for future use with message verification or key negotiation.
int	wc_ecc_init_ex(ecc_key * key, void * heap, int devId) This function initializes an ecc_key object for future use with message verification or key negotiation.
ecc_key *	wc_ecc_key_new(void * heap) This function uses a user defined heap and allocates space for the key structure.
int	wc_ecc_free(ecc_key * key) This function frees an ecc_key object after it has been used.
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. Threaded applications should call this function before exiting the thread.
int	wc_ecc_is_valid_idx(int n) Checks if an ECC idx is valid.
ecc_point *	wc_ecc_new_point(void ) Allocate a new ECC point.
void	wc_ecc_del_point(ecc_point * p) Free an ECC point from memory.
int	wc_ecc_copy_point(const ecc_point * p, ecc_point * r) Copy the value of one point to another one.
int	wc_ecc_cmp_point(ecc_point * a, ecc_point * b) Compare the value of a point with another one.
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.
int	wc_ecc_mulmod(const mp_int * k, ecc_point * G, ecc_point * R, mp_int * a, mp_int * modulus, int map) Perform ECC Fixed Point multiplication.
int	wc_ecc_export_x963(ecc_key * 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.
int	wc_ecc_export_x963_ex(ecc_key * key, byte * out, word32 * outLen, int compressed) This function exports the public 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.
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.
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.
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.
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.
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.
int	wc_ecc_export_point_der(const int curve_idx, ecc_point * point, byte * out, word32 * outLen) Export point to der.
int	wc_ecc_import_point_der(const byte * in, word32 inLen, const int curve_idx, ecc_point * point) Import point from der format.
int	wc_ecc_size(ecc_key * key) This function returns the key size of an ecc_key structure in octets.
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.
int	wc_ecc_sig_size(const 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.
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.
void	wc_ecc_ctx_free(ecEncCtx * ctx) This function frees the ecEncCtx object used for encrypting and decrypting messages.
int	wc_ecc_ctx_reset(ecEncCtx * ctx, WC_RNG * rng) This function resets an ecEncCtx structure to avoid having to free and allocate a new context object.
int	wc_ecc_ctx_set_algo(ecEncCtx * ctx, byte encAlgo, byte kdfAlgo, byte macAlgo) This function can optionally be called after wc_ecc_ctx_new. It sets the encryption, KDF, and MAC algorithms into an ecEncCtx object.
const byte *	wc_ecc_ctx_get_own_salt(ecEncCtx * ctx) 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.
int	wc_ecc_ctx_set_peer_salt(ecEncCtx * ctx, const byte * salt) This function sets the peer salt of an ecEncCtx object.
int	wc_ecc_ctx_set_kdf_salt(ecEncCtx * ctx, const byte * salt, word32 sz) This function sets the salt pointer and length to use with KDF into the ecEncCtx object.
int	wc_ecc_ctx_set_info(ecEncCtx * ctx, 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.
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.
int	wc_ecc_encrypt_ex(ecc_key * privKey, ecc_key * pubKey, const byte * msg, word32 msgSz, byte * out, word32 * outSz, ecEncCtx * ctx, int compressed) 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.
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.
int	wc_ecc_set_nonblock(ecc_key * key, ecc_nb_ctx_t * ctx) Enable ECC support for non_blocking operations. Supported for Single Precision (SP) math with the following build options: WOLFSSL_SP_NONBLOCK WOLFSSL_SP_SMALL WOLFSSL_SP_NO_MALLOC WC_ECC_NONBLOCK.
int	wc_ecc_set_curve(ecc_key * key, int keysize, int curve_id) Compare a curve which has larger key than specified size or the curve matched curve ID, set a curve with smaller key size to the key.
mp_int *	wc_ecc_key_get_priv(ecc_key * key) Gets private key mp_int from ECC key.
size_t	wc_ecc_get_sets_count(void ) Returns number of supported ECC curve sets.
const char *	wc_ecc_get_name(int curve_id) Gets curve name from curve ID.
int	wc_ecc_make_key_ex2(WC_RNG * rng, int keysize, ecc_key * key, int curve_id, int flags) Makes ECC key with extended options.
int	wc_ecc_is_point(ecc_point * ecp, mp_int * a, mp_int * b, mp_int * prime) Checks if point is on curve.
int	wc_ecc_get_generator(ecc_point * ecp, int curve_idx) Gets generator point for curve.
int	wc_ecc_set_deterministic(ecc_key * key, byte flag) Sets deterministic signing mode.
int	wc_ecc_set_deterministic_ex(ecc_key * key, byte flag, enum wc_HashType hashType) Sets deterministic signing with hash type.
int	wc_ecc_gen_deterministic_k(const byte * hash, word32 hashSz, enum wc_HashType hashType, mp_int * priv, mp_int * k, mp_int * order, void * heap) Generates deterministic k value for signing.
int	wc_ecc_sign_set_k(const byte * k, word32 klen, ecc_key * key) Sets k value for signing.
int	wc_ecc_init_id(ecc_key * key, unsigned char * id, int len, void * heap, int devId) Initializes ECC key with ID.
int	wc_ecc_init_label(ecc_key * key, const char * label, void * heap, int devId) Initializes ECC key with label.
int	wc_ecc_set_flags(ecc_key * key, word32 flags) Sets flags on ECC key.
void	wc_ecc_fp_init(void ) Initializes fixed-point cache.
int	wc_ecc_set_rng(ecc_key * key, WC_RNG * rng) Sets RNG for ECC key.
int	wc_ecc_get_curve_idx(int curve_id) Gets curve index from curve ID.
int	wc_ecc_get_curve_id(int curve_idx) Gets curve ID from curve index.
int	wc_ecc_get_curve_size_from_id(int curve_id) Gets curve size from curve ID.
int	wc_ecc_get_curve_idx_from_name(const char * curveName) Gets curve index from curve name.
int	wc_ecc_get_curve_size_from_name(const char * curveName) Gets curve size from curve name.
int	wc_ecc_get_curve_id_from_name(const char * curveName) Gets curve ID from curve name.
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) Gets curve ID from curve parameters.
int	wc_ecc_get_curve_id_from_dp_params(const ecc_set_type * dp) Gets curve ID from domain parameters.
int	wc_ecc_get_curve_id_from_oid(const byte * oid, word32 len) Gets curve ID from OID.
const ecc_set_type *	wc_ecc_get_curve_params(int curve_idx) Gets curve parameters from curve index.
ecc_point *	wc_ecc_new_point_h(void * h) Allocates new ECC point with heap hint.
void	wc_ecc_del_point_h(ecc_point * p, void * h) Frees ECC point with heap hint.
void	wc_ecc_forcezero_point(ecc_point * p) Securely zeros ECC point.
int	wc_ecc_point_is_on_curve(ecc_point * p, int curve_idx) Checks if point is on curve.
int	wc_ecc_import_x963_ex(const byte * in, word32 inLen, ecc_key * key, int curve_id) Imports X9.63 format with curve ID.
int	wc_ecc_import_private_key_ex(const byte * priv, word32 privSz, const byte * pub, word32 pubSz, ecc_key * key, int curve_id) Imports private key with curve ID.
int	wc_ecc_rs_raw_to_sig(const byte * r, word32 rSz, const byte * s, word32 sSz, byte * out, word32 * outlen) Converts raw r,s to signature.
int	wc_ecc_sig_to_rs(const byte * sig, word32 sigLen, byte * r, word32 * rLen, byte * s, word32 * sLen) Converts signature to raw r,s.
int	wc_ecc_import_raw_ex(ecc_key * key, const char * qx, const char * qy, const char * d, int curve_id) Imports raw key with curve ID.
int	wc_ecc_import_unsigned(ecc_key * key, const byte * qx, const byte * qy, const byte * d, int curve_id) Imports unsigned key with curve ID.
int	wc_ecc_export_ex(ecc_key * key, byte * qx, word32 * qxLen, byte * qy, word32 * qyLen, byte * d, word32 * dLen, int encType) Exports key with encoding type.
int	wc_ecc_export_public_raw(ecc_key * key, byte * qx, word32 * qxLen, byte * qy, word32 * qyLen) Exports public key in raw format.
int	wc_ecc_export_private_raw(ecc_key * key, byte * qx, word32 * qxLen, byte * qy, word32 * qyLen, byte * d, word32 * dLen) Exports private key in raw format.
int	wc_ecc_export_point_der_ex(const int curve_idx, ecc_point * point, byte * out, word32 * outLen, int compressed) Exports point in DER format with compression.
int	wc_ecc_import_point_der_ex(const byte * in, word32 inLen, const int curve_idx, ecc_point * point, int shortKeySize) Imports point from DER format.
int	wc_ecc_get_oid(word32 oidSum, const byte ** oid, word32 * oidSz) Gets OID for curve.
int	wc_ecc_set_custom_curve(ecc_key * key, const ecc_set_type * dp) Sets custom curve parameters.
ecEncCtx *	wc_ecc_ctx_new_ex(int flags, WC_RNG * rng, void * heap) Creates new ECC encryption context with heap.
int	wc_ecc_ctx_set_own_salt(ecEncCtx * ctx, const byte * salt, word32 sz) Sets own salt in context.
int	wc_X963_KDF(enum wc_HashType type, const byte * secret, word32 secretSz, const byte * sinfo, word32 sinfoSz, byte * out, word32 outSz) X9.63 Key Derivation Function.
int	wc_ecc_curve_cache_init(void ) Initializes curve cache.
void	wc_ecc_curve_cache_free(void ) Frees curve cache.
int	wc_ecc_gen_k(WC_RNG * rng, int size, mp_int * k, mp_int * order) Generates random k value.
int	wc_ecc_set_handle(ecc_key * key, remote_handle64 handle) Sets remote handle for hardware.
int	wc_ecc_use_key_id(ecc_key * key, word32 keyId, word32 flags) Uses key ID for hardware.
int	wc_ecc_get_key_id(ecc_key * key, word32 * keyId) Gets key ID from hardware key.

Functions Documentation

function wc_ecc_make_key

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.

Parameters:

rng pointer to an initialized RNG object with which to generate the key
keysize desired length for the ecc_key
key pointer to the ecc_key for which to generate a key

See:

Return:

0 Returned on success.
ECC_BAD_ARG_E Returned if rng or key evaluate to NULL
BAD_FUNC_ARG Returned if the specified key size is not in the correct range of supported keys
MEMORY_E Returned if there is an error allocating memory while computing the ecc key
MP_INIT_E may be returned if there is an error while computing the ecc key
MP_READ_E may be returned if there is an error while computing the ecc key
MP_CMP_E may be returned if there is an error while computing the ecc key
MP_INVMOD_E may be returned if there is an error while computing the ecc key
MP_EXPTMOD_E may be returned if there is an error while computing the ecc key
MP_MOD_E may be returned if there is an error while computing the ecc key
MP_MUL_E may be returned if there is an error while computing the ecc key
MP_ADD_E may be returned if there is an error while computing the ecc key
MP_MULMOD_E may be returned if there is an error while computing the ecc key
MP_TO_E may be returned if there is an error while computing the ecc key
MP_MEM may be returned if there is an error while computing the ecc key

Example

ecc_key key;
wc_ecc_init(&key);
WC_RNG rng;
wc_InitRng(&rng);
wc_ecc_make_key(&rng, 32, &key); // initialize 32 byte ecc key

function wc_ecc_make_key_ex

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.

Parameters:

key Pointer to store the created key.
keysize size of key to be created in bytes, set based on curveId
rng Rng to be used in key creation
curve_id Curve to use for key

See:

Return:

0 Returned on success.
ECC_BAD_ARG_E Returned if rng or key evaluate to NULL
BAD_FUNC_ARG Returned if the specified key size is not in the correct range of supported keys
MEMORY_E Returned if there is an error allocating memory while computing the ecc key
MP_INIT_E may be returned if there is an error while computing the ecc key
MP_READ_E may be returned if there is an error while computing the ecc key
MP_CMP_E may be returned if there is an error while computing the ecc key
MP_INVMOD_E may be returned if there is an error while computing the ecc key
MP_EXPTMOD_E may be returned if there is an error while computing the ecc key
MP_MOD_E may be returned if there is an error while computing the ecc key
MP_MUL_E may be returned if there is an error while computing the ecc key
MP_ADD_E may be returned if there is an error while computing the ecc key
MP_MULMOD_E may be returned if there is an error while computing the ecc key
MP_TO_E may be returned if there is an error while computing the ecc key
MP_MEM may be returned if there is an error while computing the ecc key

Example

ecc_key key;
int ret;
WC_RNG rng;
wc_ecc_init(&key);
wc_InitRng(&rng);
int curveId = ECC_SECP521R1;
int keySize = wc_ecc_get_curve_size_from_id(curveId);
ret = wc_ecc_make_key_ex(&rng, keySize, &key, curveId);
if (ret != MP_OKAY) {
    // error handling
}

function wc_ecc_make_pub

int wc_ecc_make_pub(
    ecc_key * key,
    ecc_point * pubOut
)

wc_ecc_make_pub computes the public component from an ecc_key with an existing private component. If pubOut is supplied, the computed public key is stored there, else it is stored in the supplied ecc_key public component slot.

Parameters:

key Pointer to an ecc_key containing a valid private component
pubOut Optional pointer to an ecc_point struct in which to store the computed public key

See:

Return:

0 Returned on success.
ECC_BAD_ARG_E Returned if key is NULL
BAD_FUNC_ARG Returned if the supplied key is not a valid ecc_key.
MEMORY_E Returned if there is an error allocating memory while computing the public key
MP_INIT_E may be returned if there is an error while computing the public key
MP_READ_E may be returned if there is an error while computing the public key
MP_CMP_E may be returned if there is an error while computing the public key
MP_INVMOD_E may be returned if there is an error while computing the public key
MP_EXPTMOD_E may be returned if there is an error while computing the public key
MP_MOD_E may be returned if there is an error while computing the public key
MP_MUL_E may be returned if there is an error while computing the public key
MP_ADD_E may be returned if there is an error while computing the public key
MP_MULMOD_E may be returned if there is an error while computing the public key
MP_TO_E may be returned if there is an error while computing the public key
MP_MEM may be returned if there is an error while computing the public key
ECC_OUT_OF_RANGE_E may be returned if there is an error while computing the public key
ECC_PRIV_KEY_E may be returned if there is an error while computing the public key
ECC_INF_E may be returned if there is an error while computing the public key

function wc_ecc_make_pub_ex

int wc_ecc_make_pub_ex(
    ecc_key * key,
    ecc_point * pubOut,
    WC_RNG * rng
)

wc_ecc_make_pub_ex computes the public component from an ecc_key with an existing private component. If pubOut is supplied, the computed public key is stored there, else it is stored in the supplied ecc_key public component slot. The supplied rng, if non-NULL, is used to blind the private key value used in the computation.

Parameters:

key Pointer to an ecc_key containing a valid private component
pubOut Optional pointer to an ecc_point struct in which to store the computed public key
rng Rng to be used in the public key computation

See:

Return:

0 Returned on success.
ECC_BAD_ARG_E Returned if key is NULL
BAD_FUNC_ARG Returned if the supplied key is not a valid ecc_key.
MEMORY_E Returned if there is an error allocating memory while computing the public key
MP_INIT_E may be returned if there is an error while computing the public key
MP_READ_E may be returned if there is an error while computing the public key
MP_CMP_E may be returned if there is an error while computing the public key
MP_INVMOD_E may be returned if there is an error while computing the public key
MP_EXPTMOD_E may be returned if there is an error while computing the public key
MP_MOD_E may be returned if there is an error while computing the public key
MP_MUL_E may be returned if there is an error while computing the public key
MP_ADD_E may be returned if there is an error while computing the public key
MP_MULMOD_E may be returned if there is an error while computing the public key
MP_TO_E may be returned if there is an error while computing the public key
MP_MEM may be returned if there is an error while computing the public key
ECC_OUT_OF_RANGE_E may be returned if there is an error while computing the public key
ECC_PRIV_KEY_E may be returned if there is an error while computing the public key
ECC_INF_E may be returned if there is an error while computing the public key

function wc_ecc_check_key

int wc_ecc_check_key(
    ecc_key * key
)

Perform sanity checks on ecc key validity.

Parameters:

key Pointer to key to check.

See: wc_ecc_point_is_at_infinity

Return:

MP_OKAY Success, key is OK.
BAD_FUNC_ARG Returns if key is NULL.
ECC_INF_E Returns if wc_ecc_point_is_at_infinity returns 1.

Example

ecc_key key;
WC_RNG rng;
int check_result;
wc_ecc_init(&key);
wc_InitRng(&rng);
wc_ecc_make_key(&rng, 32, &key);
check_result = wc_ecc_check_key(&key);

if (check_result == MP_OKAY)
{
    // key check succeeded
}
else
{
    // key check failed
}

function wc_ecc_key_free

void wc_ecc_key_free(
    ecc_key * key
)

This function frees an ecc_key key after it has been used.

Parameters:

key pointer to the ecc_key structure to free

See:

Example

// initialize key and perform ECC operations
...
wc_ecc_key_free(&key);

function wc_ecc_shared_secret

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.

Parameters:

private_key pointer to the ecc_key structure containing the local private key
public_key pointer to the ecc_key structure containing the received public key
out pointer to an output buffer in which to store the generated shared secret key
outlen pointer to the word32 object containing the length of the output buffer. Will be overwritten with the length written to the output buffer upon successfully generating a shared secret key

See:

Return:

0 Returned upon successfully generating a shared secret key
BAD_FUNC_ARG Returned if any of the input parameters evaluate to NULL
ECC_BAD_ARG_E Returned if the type of the private key given as argument, private_key, is not ECC_PRIVATEKEY, or if the public and private key types (given by ecc->dp) are not equivalent
MEMORY_E Returned if there is an error generating a new ecc point
BUFFER_E Returned if the generated shared secret key is too long to store in the provided buffer
MP_INIT_E may be returned if there is an error while computing the shared key
MP_READ_E may be returned if there is an error while computing the shared key
MP_CMP_E may be returned if there is an error while computing the shared key
MP_INVMOD_E may be returned if there is an error while computing the shared key
MP_EXPTMOD_E may be returned if there is an error while computing the shared key
MP_MOD_E may be returned if there is an error while computing the shared key
MP_MUL_E may be returned if there is an error while computing the shared key
MP_ADD_E may be returned if there is an error while computing the shared key
MP_MULMOD_E may be returned if there is an error while computing the shared key
MP_TO_E may be returned if there is an error while computing the shared key
MP_MEM may be returned if there is an error while computing the shared key

Example

ecc_key priv, pub;
WC_RNG rng;
byte secret[1024]; // can hold 1024 byte shared secret key
word32 secretSz = sizeof(secret);
int ret;

wc_InitRng(&rng); // initialize rng
wc_ecc_init(&priv); // initialize key
wc_ecc_make_key(&rng, 32, &priv); // make public/private key pair
// receive public key, and initialise into pub
ret = wc_ecc_shared_secret(&priv, &pub, secret, &secretSz);
// generate secret key
if ( ret != 0 ) {
    // error generating shared secret key
}

function wc_ecc_shared_secret_ex

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.

Parameters:

private_key The private ECC key.
point The point to use (public key).
out Output destination of the shared secret. Conforms to EC-DH from ANSI X9.63.
outlen Input the max size and output the resulting size of the shared secret.

See: wc_ecc_verify_hash_ex

Return:

MP_OKAY Indicates success.
BAD_FUNC_ARG Error returned when any arguments are null.
ECC_BAD_ARG_E Error returned if private_key->type is not ECC_PRIVATEKEY or private_key->idx fails to validate.
BUFFER_E Error when outlen is too small.
MEMORY_E Error to create a new point.
MP_VAL possible when an initialization failure occurs.
MP_MEM possible when an initialization failure occurs.

Example

ecc_key key;
ecc_point* point;
byte shared_secret[];
int secret_size;
int result;

point = wc_ecc_new_point();

result = wc_ecc_shared_secret_ex(&key, point,
&shared_secret, &secret_size);

if (result != MP_OKAY)
{
    // Handle error
}

function wc_ecc_sign_hash

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.

Parameters:

in pointer to the buffer containing the message hash to sign
inlen length of the message hash to sign
out buffer in which to store the generated signature
outlen max length of the output buffer. Will store the bytes written to out upon successfully generating a message signature
key pointer to a private ECC key with which to generate the signature

See: wc_ecc_verify_hash

Return:

0 Returned upon successfully generating a signature for the message digest
BAD_FUNC_ARG Returned if any of the input parameters evaluate to NULL, or if the output buffer is too small to store the generated signature
ECC_BAD_ARG_E Returned if the input key is not a private key, or if the ECC OID is invalid
RNG_FAILURE_E Returned if the rng cannot successfully generate a satisfactory key
MP_INIT_E may be returned if there is an error while computing the message signature
MP_READ_E may be returned if there is an error while computing the message signature
MP_CMP_E may be returned if there is an error while computing the message signature
MP_INVMOD_E may be returned if there is an error while computing the message signature
MP_EXPTMOD_E may be returned if there is an error while computing the message signature
MP_MOD_E may be returned if there is an error while computing the message signature
MP_MUL_E may be returned if there is an error while computing the message signature
MP_ADD_E may be returned if there is an error while computing the message signature
MP_MULMOD_E may be returned if there is an error while computing the message signature
MP_TO_E may be returned if there is an error while computing the message signature
MP_MEM may be returned if there is an error while computing the message signature

Example

ecc_key key;
WC_RNG rng;
int ret, sigSz;

byte sig[512]; // will hold generated signature
sigSz = sizeof(sig);
byte digest[] = { // initialize with message hash };
wc_InitRng(&rng); // initialize rng
wc_ecc_init(&key); // initialize key
wc_ecc_make_key(&rng, 32, &key); // make public/private key pair
ret = wc_ecc_sign_hash(digest, sizeof(digest), sig, &sigSz, &key);
if ( ret != 0 ) {
    // error generating message signature
}

function wc_ecc_sign_hash_ex

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.

Parameters:

in The message digest to sign.
inlen The length of the digest.
rng Pointer to WC_RNG struct.
key A private ECC key.
r The destination for r component of the signature.
s The destination for s component of the signature.

See: wc_ecc_verify_hash_ex

Return:

MP_OKAY Returned upon successfully generating a signature for the message digest
ECC_BAD_ARG_E Returned if the input key is not a private key, or if the ECC IDX is invalid, or if any of the input parameters evaluate to NULL, or if the output buffer is too small to store the generated signature
RNG_FAILURE_E Returned if the rng cannot successfully generate a satisfactory key
MP_INIT_E may be returned if there is an error while computing the message signature
MP_READ_E may be returned if there is an error while computing the message signature
MP_CMP_E may be returned if there is an error while computing the message signature
MP_INVMOD_E may be returned if there is an error while computing the message signature
MP_EXPTMOD_E may be returned if there is an error while computing the message signature
MP_MOD_E may be returned if there is an error while computing the message signature
MP_MUL_E may be returned if there is an error while computing the message signature
MP_ADD_E may be returned if there is an error while computing the message signature
MP_MULMOD_E may be returned if there is an error while computing the message signature
MP_TO_E may be returned if there is an error while computing the message signature
MP_MEM may be returned if there is an error while computing the message signature

Example

ecc_key key;
WC_RNG rng;
int ret, sigSz;
mp_int r; // destination for r component of signature.
mp_int s; // destination for s component of signature.

byte sig[512]; // will hold generated signature
sigSz = sizeof(sig);
byte digest[] = { initialize with message hash };
wc_InitRng(&rng); // initialize rng
wc_ecc_init(&key); // initialize key
mp_init(&r); // initialize r component
mp_init(&s); // initialize s component
wc_ecc_make_key(&rng, 32, &key); // make public/private key pair
ret = wc_ecc_sign_hash_ex(digest, sizeof(digest), &rng, &key, &r, &s);

if ( ret != MP_OKAY ) {
    // error generating message signature
}

function wc_ecc_verify_hash

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.

Parameters:

sig pointer to the buffer containing the signature to verify
siglen length of the signature to verify
hash pointer to the buffer containing the hash of the message verified
hashlen length of the hash of the message verified
stat pointer to the result of the verification. 1 indicates the message was successfully verified
key pointer to a public ECC key with which to verify the signature

See:

Return:

0 Returned upon successfully performing the signature verification. Note: This does not mean that the signature is verified. The authenticity information is stored instead in stat
BAD_FUNC_ARG Returned any of the input parameters evaluate to NULL
MEMORY_E Returned if there is an error allocating memory
MP_INIT_E may be returned if there is an error while computing the message signature
MP_READ_E may be returned if there is an error while computing the message signature
MP_CMP_E may be returned if there is an error while computing the message signature
MP_INVMOD_E may be returned if there is an error while computing the message signature
MP_EXPTMOD_E may be returned if there is an error while computing the message signature
MP_MOD_E may be returned if there is an error while computing the message signature
MP_MUL_E may be returned if there is an error while computing the message signature
MP_ADD_E may be returned if there is an error while computing the message signature
MP_MULMOD_E may be returned if there is an error while computing the message signature
MP_TO_E may be returned if there is an error while computing the message signature
MP_MEM may be returned if there is an error while computing the message signature

Example

ecc_key key;
int ret, verified = 0;

byte sig[1024] { initialize with received signature };
byte digest[] = { initialize with message hash };
// initialize key with received public key
ret = wc_ecc_verify_hash(sig, sizeof(sig), digest,sizeof(digest),
&verified, &key);
if ( ret != 0 ) {
    // error performing verification
} else if ( verified == 0 ) {
    // the signature is invalid
}

function wc_ecc_verify_hash_ex

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.

Parameters:

r The signature R component to verify
s The signature S component to verify
hash The hash (message digest) that was signed
hashlen The length of the hash (octets)
stat Result of signature, 1==valid, 0==invalid
key The corresponding public ECC key

See: wc_ecc_verify_hash

Return:

MP_OKAY If successful (even if the signature is not valid)
ECC_BAD_ARG_E Returns if arguments are null or if key-idx is invalid.
MEMORY_E Error allocating ints or points.

Example

mp_int r;
mp_int s;
int stat;
byte hash[] = { Some hash }
ecc_key key;

if(wc_ecc_verify_hash_ex(&r, &s, hash, hashlen, &stat, &key) == MP_OKAY)
{
    // Check stat
}

function wc_ecc_init

int wc_ecc_init(
    ecc_key * key
)

This function initializes an ecc_key object for future use with message verification or key negotiation.

Parameters:

key pointer to the ecc_key object to initialize

See:

Return:

0 Returned upon successfully initializing the ecc_key object
MEMORY_E Returned if there is an error allocating memory

Example

ecc_key key;
wc_ecc_init(&key);

function wc_ecc_init_ex

int wc_ecc_init_ex(
    ecc_key * key,
    void * heap,
    int devId
)

This function initializes an ecc_key object for future use with message verification or key negotiation.

Parameters:

key pointer to the ecc_key object to initialize
heap pointer to a heap identifier
devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used

See:

Return:

0 Returned upon successfully initializing the ecc_key object
MEMORY_E Returned if there is an error allocating memory

Example

ecc_key key;
wc_ecc_init_ex(&key, heap, devId);

function wc_ecc_key_new

ecc_key * wc_ecc_key_new(
    void * heap
)

This function uses a user defined heap and allocates space for the key structure.

Parameters:

heap Heap hint for memory allocation

See:

Return:

0 Returned upon successfully initializing the ecc_key object
MEMORY_E Returned if there is an error allocating memory
ecc_key pointer on success
NULL on failure

Allocates and initializes new ECC key.

Example

wc_ecc_key_new(&heap);

Example

ecc_key* key = wc_ecc_key_new(NULL);
if (key != NULL) {
    // use key
    wc_ecc_key_free(key);
}

function wc_ecc_free

int wc_ecc_free(
    ecc_key * key
)

This function frees an ecc_key object after it has been used.

Parameters:

key pointer to the ecc_key object to free

See: wc_ecc_init

Return: int integer returned indicating wolfSSL error or success status.

Example

// initialize key and perform secure exchanges
...
wc_ecc_free(&key);

function wc_ecc_fp_free

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. Threaded applications should call this function before exiting the thread.

Parameters:

none No parameters.

See: wc_ecc_free

Return: none No returns.

Example

ecc_key key;
// initialize key and perform secure exchanges
...

wc_ecc_fp_free();

function wc_ecc_is_valid_idx

int wc_ecc_is_valid_idx(
    int n
)

Checks if an ECC idx is valid.

Parameters:

n The idx number to check.

See: none

Return:

1 Return if valid.
0 Return if not valid.

Example

ecc_key key;
WC_RNG rng;
int is_valid;
wc_ecc_init(&key);
wc_InitRng(&rng);
wc_ecc_make_key(&rng, 32, &key);
is_valid = wc_ecc_is_valid_idx(key.idx);
if (is_valid == 1)
{
    // idx is valid
}
else if (is_valid == 0)
{
    // idx is not valid
}

function wc_ecc_new_point

ecc_point * wc_ecc_new_point(
    void 
)

Allocate a new ECC point.

Parameters:

none No parameters.

See:

Return:

p A newly allocated point.
NULL Returns NULL on error.
ecc_point pointer on success
NULL on failure

Allocates new ECC point.

Example

ecc_point* point;
point = wc_ecc_new_point();
if (point == NULL)
{
    // Handle point creation error
}
// Do stuff with point

Example

ecc_point* point = wc_ecc_new_point();
if (point != NULL) {
    // use point
    wc_ecc_del_point(point);
}

function wc_ecc_del_point

void wc_ecc_del_point(
    ecc_point * p
)

Free an ECC point from memory.

Parameters:

p The point to free.

See:

Return: none No returns.

Example

ecc_point* point;
point = wc_ecc_new_point();
if (point == NULL)
{
    // Handle point creation error
}
// Do stuff with point
wc_ecc_del_point(point);

function wc_ecc_copy_point

int wc_ecc_copy_point(
    const ecc_point * p,
    ecc_point * r
)

Copy the value of one point to another one.

Parameters:

p The point to copy.
r The created point.

See:

Return:

ECC_BAD_ARG_E Error thrown when p or r is null.
MP_OKAY Point copied successfully
ret Error from internal functions. Can be...

Example

ecc_point* point;
ecc_point* copied_point;
int copy_return;

point = wc_ecc_new_point();
copy_return = wc_ecc_copy_point(point, copied_point);
if (copy_return != MP_OKAY)
{
    // Handle error
}

function wc_ecc_cmp_point

int wc_ecc_cmp_point(
    ecc_point * a,
    ecc_point * b
)

Compare the value of a point with another one.

Parameters:

a First point to compare.
b Second point to compare.

See:

Return:

BAD_FUNC_ARG One or both arguments are NULL.
MP_EQ The points are equal.
ret Either MP_LT or MP_GT and signifies that the points are not equal.

Example

ecc_point* point;
ecc_point* point_to_compare;
int cmp_result;

point = wc_ecc_new_point();
point_to_compare = wc_ecc_new_point();
cmp_result = wc_ecc_cmp_point(point, point_to_compare);
if (cmp_result == BAD_FUNC_ARG)
{
    // arguments are invalid
}
else if (cmp_result == MP_EQ)
{
    // Points are equal
}
else
{
    // Points are not equal
}

function wc_ecc_point_is_at_infinity

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.

Parameters:

p The point to check.

See:

Return:

1 p is at infinity.
0 p is not at infinity.
<0 Error.

Example

ecc_point* point;
int is_infinity;
point = wc_ecc_new_point();

is_infinity = wc_ecc_point_is_at_infinity(point);
if (is_infinity < 0)
{
    // Handle error
}
else if (is_infinity == 0)
{
    // Point is not at infinity
}
else if (is_infinity == 1)
{
    // Point is at infinity
}

function wc_ecc_mulmod

int wc_ecc_mulmod(
    const mp_int * k,
    ecc_point * G,
    ecc_point * R,
    mp_int * a,
    mp_int * modulus,
    int map
)

Perform ECC Fixed Point multiplication.

Parameters:

k The multiplicand.
G Base point to multiply.
R Destination of product.
modulus The modulus for the curve.
map If non-zero maps the point back to affine coordinates, otherwise it's left in jacobian-montgomery form.

See: none

Return:

MP_OKAY Returns on successful operation.
MP_INIT_E Returned if there is an error initializing an integer for use with the multiple precision integer (mp_int) library.

Example

ecc_point* base;
ecc_point* destination;
// Initialize points
base = wc_ecc_new_point();
destination = wc_ecc_new_point();
// Setup other arguments
mp_int multiplicand;
mp_int modulus;
int map;

function wc_ecc_export_x963

int wc_ecc_export_x963(
    ecc_key * 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.

Parameters:

key pointer to the ecc_key object to export
out pointer to the buffer in which to store the ANSI X9.63 formatted key
outLen size of the output buffer. On successfully storing the key, will hold the bytes written to the output buffer

See:

Return:

0 Returned on successfully exporting the ecc_key
LENGTH_ONLY_E Returned if the output buffer evaluates to NULL, but the other two input parameters are valid. Indicates that the function is only returning the length required to store the key
ECC_BAD_ARG_E Returned if any of the input parameters are NULL, or the key is unsupported (has an invalid index)
BUFFER_E Returned if the output buffer is too small to store the ecc key. If the output buffer is too small, the size needed will be returned in outLen
MEMORY_E Returned if there is an error allocating memory with XMALLOC
MP_INIT_E may be returned if there is an error processing the ecc_key
MP_READ_E may be returned if there is an error processing the ecc_key
MP_CMP_E may be returned if there is an error processing the ecc_key
MP_INVMOD_E may be returned if there is an error processing the ecc_key
MP_EXPTMOD_E may be returned if there is an error processing the ecc_key
MP_MOD_E may be returned if there is an error processing the ecc_key
MP_MUL_E may be returned if there is an error processing the ecc_key
MP_ADD_E may be returned if there is an error processing the ecc_key
MP_MULMOD_E may be returned if there is an error processing the ecc_key
MP_TO_E may be returned if there is an error processing the ecc_key
MP_MEM may be returned if there is an error processing the ecc_key

Example

int ret;
byte buff[1024];
word32 buffSz = sizeof(buff);

ecc_key key;
// initialize key, make key
ret = wc_ecc_export_x963(&key, buff, &buffSz);
if ( ret != 0) {
    // error exporting key
}

function wc_ecc_export_x963_ex

int wc_ecc_export_x963_ex(
    ecc_key * key,
    byte * out,
    word32 * outLen,
    int compressed
)

This function exports the public 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.

Parameters:

key pointer to the ecc_key object to export
out pointer to the buffer in which to store the ANSI X9.63 formatted public key
outLen size of the output buffer. On successfully storing the public key, will hold the bytes written to the output buffer
compressed indicator of whether to store the key in compressed format. 1==compressed, 0==uncompressed

See:

Return:

0 Returned on successfully exporting the ecc_key public component
ECC_PRIVATEKEY_ONLY Returned if the ecc_key public component is missing
NOT_COMPILED_IN Returned if the HAVE_COMP_KEY was not enabled at compile time, but the key was requested in compressed format
LENGTH_ONLY_E Returned if the output buffer evaluates to NULL, but the other two input parameters are valid. Indicates that the function is only returning the length required to store the public key
ECC_BAD_ARG_E Returned if any of the input parameters are NULL, or the key is unsupported (has an invalid index)
BUFFER_E Returned if the output buffer is too small to store the public key. If the output buffer is too small, the size needed will be returned in outLen
MEMORY_E Returned if there is an error allocating memory with XMALLOC
MP_INIT_E may be returned if there is an error processing the ecc_key
MP_READ_E may be returned if there is an error processing the ecc_key
MP_CMP_E may be returned if there is an error processing the ecc_key
MP_INVMOD_E may be returned if there is an error processing the ecc_key
MP_EXPTMOD_E may be returned if there is an error processing the ecc_key
MP_MOD_E may be returned if there is an error processing the ecc_key
MP_MUL_E may be returned if there is an error processing the ecc_key
MP_ADD_E may be returned if there is an error processing the ecc_key
MP_MULMOD_E may be returned if there is an error processing the ecc_key
MP_TO_E may be returned if there is an error processing the ecc_key
MP_MEM may be returned if there is an error processing the ecc_key

Example

int ret;
byte buff[1024];
word32 buffSz = sizeof(buff);
ecc_key key;
// initialize key, make key
ret = wc_ecc_export_x963_ex(&key, buff, &buffSz, 1);
if ( ret != 0) {
    // error exporting key
}

function wc_ecc_import_x963

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.

Parameters:

in pointer to the buffer containing the ANSI x9.63 formatted ECC key
inLen length of the input buffer
key pointer to the ecc_key object in which to store the imported key

See:

Return:

0 Returned on successfully importing the ecc_key
NOT_COMPILED_IN Returned if the HAVE_COMP_KEY was not enabled at compile time, but the key is stored in compressed format
ECC_BAD_ARG_E Returned if in or key evaluate to NULL, or the inLen is even (according to the x9.63 standard, the key must be odd)
MEMORY_E Returned if there is an error allocating memory
ASN_PARSE_E Returned if there is an error parsing the ECC key; may indicate that the ECC key is not stored in valid ANSI X9.63 format
IS_POINT_E Returned if the public key exported is not a point on the ECC curve
MP_INIT_E may be returned if there is an error processing the ecc_key
MP_READ_E may be returned if there is an error processing the ecc_key
MP_CMP_E may be returned if there is an error processing the ecc_key
MP_INVMOD_E may be returned if there is an error processing the ecc_key
MP_EXPTMOD_E may be returned if there is an error processing the ecc_key
MP_MOD_E may be returned if there is an error processing the ecc_key
MP_MUL_E may be returned if there is an error processing the ecc_key
MP_ADD_E may be returned if there is an error processing the ecc_key
MP_MULMOD_E may be returned if there is an error processing the ecc_key
MP_TO_E may be returned if there is an error processing the ecc_key
MP_MEM may be returned if there is an error processing the ecc_key

Example

int ret;
byte buff[] = { initialize with ANSI X9.63 formatted key };

ecc_key pubKey;
wc_ecc_init(&pubKey);

ret = wc_ecc_import_x963(buff, sizeof(buff), &pubKey);
if ( ret != 0) {
    // error importing key
}

function wc_ecc_import_private_key

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.

Parameters:

priv pointer to the buffer containing the raw private key
privSz size of the private key buffer
pub pointer to the buffer containing the ANSI x9.63 formatted ECC public key
pubSz length of the public key input buffer
key pointer to the ecc_key object in which to store the imported private/public key pair

See:

Return:

0 Returned on successfully importing the ecc_key NOT_COMPILED_IN Returned if the HAVE_COMP_KEY was not enabled at compile time, but the key is stored in compressed format
ECC_BAD_ARG_E Returned if in or key evaluate to NULL, or the inLen is even (according to the x9.63 standard, the key must be odd)
MEMORY_E Returned if there is an error allocating memory
ASN_PARSE_E Returned if there is an error parsing the ECC key; may indicate that the ECC key is not stored in valid ANSI X9.63 format
IS_POINT_E Returned if the public key exported is not a point on the ECC curve
MP_INIT_E may be returned if there is an error processing the ecc_key
MP_READ_E may be returned if there is an error processing the ecc_key
MP_CMP_E may be returned if there is an error processing the ecc_key
MP_INVMOD_E may be returned if there is an error processing the ecc_key
MP_EXPTMOD_E may be returned if there is an error processing the ecc_key
MP_MOD_E may be returned if there is an error processing the ecc_key
MP_MUL_E may be returned if there is an error processing the ecc_key
MP_ADD_E may be returned if there is an error processing the ecc_key
MP_MULMOD_E may be returned if there is an error processing the ecc_key
MP_TO_E may be returned if there is an error processing the ecc_key
MP_MEM may be returned if there is an error processing the ecc_key

Example

int ret;
byte pub[] = { initialize with ANSI X9.63 formatted key };
byte priv[] = { initialize with the raw private key };

ecc_key key;
wc_ecc_init(&key);
ret = wc_ecc_import_private_key(priv, sizeof(priv), pub, sizeof(pub),
&key);
if ( ret != 0) {
    // error importing key
}

function wc_ecc_rs_to_sig

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.

Parameters:

r pointer to the buffer containing the R portion of the signature as a string
s pointer to the buffer containing the S portion of the signature as a string
out pointer to the buffer in which to store the DER-encoded ECDSA signature
outlen length of the output buffer available. Will store the bytes written to the buffer after successfully converting the signature to ECDSA format

See:

Return:

0 Returned on successfully converting the signature
ECC_BAD_ARG_E Returned if any of the input parameters evaluate to NULL, or if the input buffer is not large enough to hold the DER-encoded ECDSA signature
MP_INIT_E may be returned if there is an error processing the ecc_key
MP_READ_E may be returned if there is an error processing the ecc_key
MP_CMP_E may be returned if there is an error processing the ecc_key
MP_INVMOD_E may be returned if there is an error processing the ecc_key
MP_EXPTMOD_E may be returned if there is an error processing the ecc_key
MP_MOD_E may be returned if there is an error processing the ecc_key
MP_MUL_E may be returned if there is an error processing the ecc_key
MP_ADD_E may be returned if there is an error processing the ecc_key
MP_MULMOD_E may be returned if there is an error processing the ecc_key
MP_TO_E may be returned if there is an error processing the ecc_key
MP_MEM may be returned if there is an error processing the ecc_key

Example

int ret;
ecc_key key;
// initialize key, generate R and S

char r[] = { initialize with R };
char s[] = { initialize with S };
byte sig[wc_ecc_sig_size(key)];
// signature size will be 2 * ECC key size + ~10 bytes for ASN.1 overhead
word32 sigSz = sizeof(sig);
ret = wc_ecc_rs_to_sig(r, s, sig, &sigSz);
if ( ret != 0) {
    // error converting parameters to signature
}

function wc_ecc_import_raw

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.

Parameters:

key pointer to an ecc_key structure to fill
qx pointer to a buffer containing the x component of the base point as an ASCII hex string
qy pointer to a buffer containing the y component of the base point as an ASCII hex string
d pointer to a buffer containing the private key as an ASCII hex string
curveName pointer to a string containing the ECC curve name, as found in ecc_sets

See: wc_ecc_import_private_key

Return:

0 Returned upon successfully importing into the ecc_key structure
ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL
MEMORY_E Returned if there is an error initializing space to store the parameters of the ecc_key
ASN_PARSE_E Returned if the input curveName is not defined in ecc_sets
MP_INIT_E may be returned if there is an error processing the input parameters
MP_READ_E may be returned if there is an error processing the input parameters
MP_CMP_E may be returned if there is an error processing the input parameters
MP_INVMOD_E may be returned if there is an error processing the input parameters
MP_EXPTMOD_E may be returned if there is an error processing the input parameters
MP_MOD_E may be returned if there is an error processing the input parameters
MP_MUL_E may be returned if there is an error processing the input parameters
MP_ADD_E may be returned if there is an error processing the input parameters
MP_MULMOD_E may be returned if there is an error processing the input parameters
MP_TO_E may be returned if there is an error processing the input parameters
MP_MEM may be returned if there is an error processing the input parameters

Example

int ret;
ecc_key key;
wc_ecc_init(&key);

char qx[] = { initialize with x component of base point };
char qy[] = { initialize with y component of base point };
char d[]  = { initialize with private key };
ret = wc_ecc_import_raw(&key,qx, qy, d, "ECC-256");
if ( ret != 0) {
    // error initializing key with given inputs
}

function wc_ecc_export_private_only

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.

Parameters:

key pointer to an ecc_key structure from which to export the private key
out pointer to the buffer in which to store the private key
outLen pointer to a word32 object with the size available in out. Set with the number of bytes written to out after successfully exporting the private key

See: wc_ecc_import_private_key

Return:

0 Returned upon successfully exporting the private key
ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL
MEMORY_E Returned if there is an error initializing space to store the parameters of the ecc_key
ASN_PARSE_E Returned if the input curveName is not defined in ecc_sets
MP_INIT_E may be returned if there is an error processing the input parameters
MP_READ_E may be returned if there is an error processing the input parameters
MP_CMP_E may be returned if there is an error processing the input parameters
MP_INVMOD_E may be returned if there is an error processing the input parameters
MP_EXPTMOD_E may be returned if there is an error processing the input parameters
MP_MOD_E may be returned if there is an error processing the input parameters
MP_MUL_E may be returned if there is an error processing the input parameters
MP_ADD_E may be returned if there is an error processing the input parameters
MP_MULMOD_E may be returned if there is an error processing the input parameters
MP_TO_E may be returned if there is an error processing the input parameters
MP_MEM may be returned if there is an error processing the input parameters

Example

int ret;
ecc_key key;
// initialize key, make key

char priv[ECC_KEY_SIZE];
word32 privSz = sizeof(priv);
ret = wc_ecc_export_private_only(&key, priv, &privSz);
if ( ret != 0) {
    // error exporting private key
}

function wc_ecc_export_point_der

int wc_ecc_export_point_der(
    const int curve_idx,
    ecc_point * point,
    byte * out,
    word32 * outLen
)

Export point to der.

Parameters:

curve_idx Index of the curve used from ecc_sets.
point Point to export to der.
out Destination for the output.
outLen Maxsize allowed for output, destination for final size of output

See: wc_ecc_import_point_der

Return:

0 Returned on success.
ECC_BAD_ARG_E Returns if curve_idx is less than 0 or invalid. Also returns when
LENGTH_ONLY_E outLen is set but nothing else.
BUFFER_E Returns if outLen is less than 1 + 2 * the curve size.
MEMORY_E Returns if there is a problem allocating memory.

Example

int curve_idx;
ecc_point* point;
byte out[];
word32 outLen;
wc_ecc_export_point_der(curve_idx, point, out, &outLen);

function wc_ecc_import_point_der

int wc_ecc_import_point_der(
    const byte * in,
    word32 inLen,
    const int curve_idx,
    ecc_point * point
)

Import point from der format.

Parameters:

in der buffer to import point from.
inLen Length of der buffer.
curve_idx Index of curve.
point Destination for point.

See: wc_ecc_export_point_der

Return:

ECC_BAD_ARG_E Returns if any arguments are null or if inLen is even.
MEMORY_E Returns if there is an error initializing
NOT_COMPILED_IN Returned if HAVE_COMP_KEY is not true and in is a compressed cert
MP_OKAY Successful operation.

Example

byte in[];
word32 inLen;
int curve_idx;
ecc_point* point;
wc_ecc_import_point_der(in, inLen, curve_idx, point);

function wc_ecc_size

int wc_ecc_size(
    ecc_key * key
)

This function returns the key size of an ecc_key structure in octets.

Parameters:

key pointer to an ecc_key structure for which to get the key size

See: wc_ecc_make_key

Return:

Given a valid key, returns the key size in octets
0 Returned if the given key is NULL

Example

int keySz;
ecc_key key;
// initialize key, make key
keySz = wc_ecc_size(&key);
if ( keySz == 0) {
    // error determining key size
}

function wc_ecc_sig_size_calc

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.

Parameters:

key size

See:

Return: returns the maximum signature size, in octets

Example

int sigSz = wc_ecc_sig_size_calc(32);
if ( sigSz == 0) {
    // error determining sig size
}

function wc_ecc_sig_size

int wc_ecc_sig_size(
    const 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.

Parameters:

key pointer to an ecc_key structure for which to get the signature size

See:

Return:

Success Given a valid key, returns the maximum signature size, in octets
0 Returned if the given key is NULL

Example

int sigSz;
ecc_key key;
// initialize key, make key

sigSz = wc_ecc_sig_size(&key);
if ( sigSz == 0) {
    // error determining sig size
}

function wc_ecc_ctx_new

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.

Parameters:

flags indicate whether this is a server or client context Options are: REQ_RESP_CLIENT, and REQ_RESP_SERVER
rng pointer to a RNG object with which to generate a salt
flags Context flags
rng Random number generator

See:

Return:

Success On successfully generating a new ecEncCtx object, returns a pointer to that object
NULL Returned if the function fails to generate a new ecEncCtx object
ecEncCtx pointer on success
NULL on failure

Creates new ECC encryption context.

Example

ecEncCtx* ctx;
WC_RNG rng;
wc_InitRng(&rng);
ctx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng);
if(ctx == NULL) {
    // error generating new ecEncCtx object
}

Example

WC_RNG rng;
ecEncCtx* ctx = wc_ecc_ctx_new(0, &rng);

function wc_ecc_ctx_free

void wc_ecc_ctx_free(
    ecEncCtx * ctx
)

This function frees the ecEncCtx object used for encrypting and decrypting messages.

Parameters:

ctx pointer to the ecEncCtx object to free

See: wc_ecc_ctx_new

Return: none Returns.

Example

ecEncCtx* ctx;
WC_RNG rng;
wc_InitRng(&rng);
ctx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng);
// do secure communication
...
wc_ecc_ctx_free(&ctx);

function wc_ecc_ctx_reset

int wc_ecc_ctx_reset(
    ecEncCtx * ctx,
    WC_RNG * rng
)

This function resets an ecEncCtx structure to avoid having to free and allocate a new context object.

Parameters:

ctx pointer to the ecEncCtx object to reset
rng pointer to an RNG object with which to generate a new salt
ctx ECC encryption context
rng Random number generator

See:

Return:

0 Returned if the ecEncCtx structure is successfully reset
BAD_FUNC_ARG Returned if either rng or ctx is NULL
RNG_FAILURE_E Returned if there is an error generating a new salt for the ECC object
0 on success
negative on error

Resets ECC encryption context.

Example

ecEncCtx* ctx;
WC_RNG rng;
wc_InitRng(&rng);
ctx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng);
// do secure communication
...
wc_ecc_ctx_reset(&ctx, &rng);
// do more secure communication

Example

ecEncCtx* ctx;
WC_RNG rng;
int ret = wc_ecc_ctx_reset(ctx, &rng);

function wc_ecc_ctx_set_algo

int wc_ecc_ctx_set_algo(
    ecEncCtx * ctx,
    byte encAlgo,
    byte kdfAlgo,
    byte macAlgo
)

This function can optionally be called after wc_ecc_ctx_new. It sets the encryption, KDF, and MAC algorithms into an ecEncCtx object.

Parameters:

ctx pointer to the ecEncCtx for which to set the info
encAlgo encryption algorithm to use.
kdfAlgo KDF algorithm to use.
macAlgo MAC algorithm to use.

See: wc_ecc_ctx_new

Return:

0 Returned upon successfully setting the information for the ecEncCtx object.
BAD_FUNC_ARG Returned if the given ecEncCtx object is NULL.

Example

ecEncCtx* ctx;
// initialize ctx
if(wc_ecc_ctx_set_algo(&ctx, ecAES_128_CTR, ecHKDF_SHA256, ecHMAC_SHA256))) {
    // error setting info
}

function wc_ecc_ctx_get_own_salt

const byte * wc_ecc_ctx_get_own_salt(
    ecEncCtx * ctx
)

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.

Parameters:

ctx pointer to the ecEncCtx object from which to get the salt
ctx ECC encryption context

See:

Return:

Success On success, returns the ecEncCtx salt
NULL Returned if the ecEncCtx object is NULL, or the ecEncCtx's state is not ecSRV_INIT or ecCLI_INIT. In the latter two cases, this function also sets the ecEncCtx's state to ecSRV_BAD_STATE or ecCLI_BAD_STATE, respectively
Salt pointer on success
NULL on failure

Gets own salt from context.

Example

ecEncCtx* ctx;
WC_RNG rng;
const byte* salt;
wc_InitRng(&rng);
ctx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng);
salt = wc_ecc_ctx_get_own_salt(&ctx);
if(salt == NULL) {
    // error getting salt
}

Example

ecEncCtx* ctx;
const byte* salt = wc_ecc_ctx_get_own_salt(ctx);

function wc_ecc_ctx_set_peer_salt

int wc_ecc_ctx_set_peer_salt(
    ecEncCtx * ctx,
    const byte * salt
)

This function sets the peer salt of an ecEncCtx object.

Parameters:

ctx pointer to the ecEncCtx for which to set the salt
salt pointer to the peer's salt

See:

Return:

0 Returned upon successfully setting the peer salt for the ecEncCtx object.
BAD_FUNC_ARG Returned if the given ecEncCtx object is NULL or has an invalid protocol, or if the given salt is NULL
BAD_ENC_STATE_E Returned if the ecEncCtx's state is ecSRV_SALT_GET or ecCLI_SALT_GET. In the latter two cases, this function also sets the ecEncCtx's state to ecSRV_BAD_STATE or ecCLI_BAD_STATE, respectively

Example

ecEncCtx* cliCtx, srvCtx;
WC_RNG rng;
const byte* cliSalt, srvSalt;
int ret;

wc_InitRng(&rng);
cliCtx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng);
srvCtx = wc_ecc_ctx_new(REQ_RESP_SERVER, &rng);

cliSalt = wc_ecc_ctx_get_own_salt(&cliCtx);
srvSalt = wc_ecc_ctx_get_own_salt(&srvCtx);
ret = wc_ecc_ctx_set_peer_salt(&cliCtx, srvSalt);

function wc_ecc_ctx_set_kdf_salt

int wc_ecc_ctx_set_kdf_salt(
    ecEncCtx * ctx,
    const byte * salt,
    word32 sz
)

This function sets the salt pointer and length to use with KDF into the ecEncCtx object.

Parameters:

ctx pointer to the ecEncCtx for which to set the salt
salt pointer to salt buffer
sz length salt in bytes

See:

wc_ecc_ctx_get_own_salt
wc_ecc_ctx_get_peer_salt

Return:

0 Returned upon successfully setting the salt for the ecEncCtx object.
BAD_FUNC_ARG Returned if the given ecEncCtx object is NULL or if the given salt is NULL and length is not NULL.

Example

ecEncCtx* srvCtx;
WC_RNG rng;
byte cliSalt[] = { fixed salt data };
word32 cliSaltLen = (word32)sizeof(cliSalt);
int ret;

wc_InitRng(&rng);
cliCtx = wc_ecc_ctx_new(REQ_RESP_SERVER, &rng);

ret = wc_ecc_ctx_set_kdf_salt(&cliCtx, cliSalt, cliSaltLen);

function wc_ecc_ctx_set_info

int wc_ecc_ctx_set_info(
    ecEncCtx * ctx,
    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.

Parameters:

ctx pointer to the ecEncCtx for which to set the info
info pointer to a buffer containing the info to set
sz size of the info buffer

See: wc_ecc_ctx_new

Return:

0 Returned upon successfully setting the information for the ecEncCtx object.
BAD_FUNC_ARG Returned if the given ecEncCtx object is NULL, the input info is NULL or it's size is invalid

Example

ecEncCtx* ctx;
byte info[] = { initialize with information };
// initialize ctx, get salt,
if(wc_ecc_ctx_set_info(&ctx, info, sizeof(info))) {
    // error setting info
}

function wc_ecc_encrypt

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.

Parameters:

privKey pointer to the ecc_key object containing the private key to use for encryption
pubKey pointer to the ecc_key object containing the public key of the peer with whom one wishes to communicate
msg pointer to the buffer holding the message to encrypt
msgSz size of the buffer to encrypt
out pointer to the buffer in which to store the encrypted ciphertext
outSz pointer to a word32 object containing the available size in the out buffer. Upon successfully encrypting the message, holds the number of bytes written to the output buffer
ctx Optional: pointer to an ecEncCtx object specifying different encryption algorithms to use

See:

Return:

0 Returned upon successfully encrypting the input message
BAD_FUNC_ARG Returned if privKey, pubKey, msg, msgSz, out, or outSz are NULL, or the ctx object specifies an unsupported encryption type
BAD_ENC_STATE_E Returned if the ctx object given is in a state that is not appropriate for encryption
BUFFER_E Returned if the supplied output buffer is too small to store the encrypted ciphertext
MEMORY_E Returned if there is an error allocating memory for the shared secret key

Example

byte msg[] = { initialize with msg to encrypt. Ensure padded to block size };
byte out[sizeof(msg)];
word32 outSz = sizeof(out);
int ret;
ecc_key cli, serv;
// initialize cli with private key
// initialize serv with received public key

ecEncCtx* cliCtx, servCtx;
// initialize cliCtx and servCtx
// exchange salts
ret = wc_ecc_encrypt(&cli, &serv, msg, sizeof(msg), out, &outSz, cliCtx);
if(ret != 0) {
    // error encrypting message
}

function wc_ecc_encrypt_ex

int wc_ecc_encrypt_ex(
    ecc_key * privKey,
    ecc_key * pubKey,
    const byte * msg,
    word32 msgSz,
    byte * out,
    word32 * outSz,
    ecEncCtx * ctx,
    int compressed
)

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.

Parameters:

privKey pointer to the ecc_key object containing the private key to use for encryption
pubKey pointer to the ecc_key object containing the public key of the peer with whom one wishes to communicate
msg pointer to the buffer holding the message to encrypt
msgSz size of the buffer to encrypt
out pointer to the buffer in which to store the encrypted ciphertext
outSz pointer to a word32 object containing the available size in the out buffer. Upon successfully encrypting the message, holds the number of bytes written to the output buffer
ctx Optional: pointer to an ecEncCtx object specifying different encryption algorithms to use
compressed Public key field is to be output in compressed format.

See:

Return:

0 Returned upon successfully encrypting the input message
BAD_FUNC_ARG Returned if privKey, pubKey, msg, msgSz, out, or outSz are NULL, or the ctx object specifies an unsupported encryption type
BAD_ENC_STATE_E Returned if the ctx object given is in a state that is not appropriate for encryption
BUFFER_E Returned if the supplied output buffer is too small to store the encrypted ciphertext
MEMORY_E Returned if there is an error allocating memory for the shared secret key

Example

byte msg[] = { initialize with msg to encrypt. Ensure padded to block size };
byte out[sizeof(msg)];
word32 outSz = sizeof(out);
int ret;
ecc_key cli, serv;
// initialize cli with private key
// initialize serv with received public key

ecEncCtx* cliCtx, servCtx;
// initialize cliCtx and servCtx
// exchange salts
ret = wc_ecc_encrypt_ex(&cli, &serv, msg, sizeof(msg), out, &outSz, cliCtx,
    1);
if(ret != 0) {
    // error encrypting message
}

function wc_ecc_decrypt

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.

Parameters:

privKey pointer to the ecc_key object containing the private key to use for decryption
pubKey pointer to the ecc_key object containing the public key of the peer with whom one wishes to communicate
msg pointer to the buffer holding the ciphertext to decrypt
msgSz size of the buffer to decrypt
out pointer to the buffer in which to store the decrypted plaintext
outSz pointer to a word32 object containing the available size in the out buffer. Upon successfully decrypting the ciphertext, holds the number of bytes written to the output buffer
ctx Optional: pointer to an ecEncCtx object specifying different decryption algorithms to use

See:

Return:

0 Returned upon successfully decrypting the input message
BAD_FUNC_ARG Returned if privKey, pubKey, msg, msgSz, out, or outSz are NULL, or the ctx object specifies an unsupported encryption type
BAD_ENC_STATE_E Returned if the ctx object given is in a state that is not appropriate for decryption
BUFFER_E Returned if the supplied output buffer is too small to store the decrypted plaintext
MEMORY_E Returned if there is an error allocating memory for the shared secret key

Example

byte cipher[] = { initialize with
ciphertext to decrypt. Ensure padded to block size };
byte plain[sizeof(cipher)];
word32 plainSz = sizeof(plain);
int ret;
ecc_key cli, serv;
// initialize cli with private key
// initialize serv with received public key
ecEncCtx* cliCtx, servCtx;
// initialize cliCtx and servCtx
// exchange salts
ret = wc_ecc_decrypt(&cli, &serv, cipher, sizeof(cipher),
plain, &plainSz, cliCtx);

if(ret != 0) {
    // error decrypting message
}

function wc_ecc_set_nonblock

int wc_ecc_set_nonblock(
    ecc_key * key,
    ecc_nb_ctx_t * ctx
)

Enable ECC support for non-blocking operations. Supported for Single Precision (SP) math with the following build options: WOLFSSL_SP_NONBLOCK WOLFSSL_SP_SMALL WOLFSSL_SP_NO_MALLOC WC_ECC_NONBLOCK.

Parameters:

key pointer to the ecc_key object
ctx pointer to ecc_nb_ctx_t structure with stack data cache for SP

Return: 0 Returned upon successfully setting the callback context the input message

Example

int ret;
ecc_key ecc;
ecc_nb_ctx_t nb_ctx;

ret = wc_ecc_init(&ecc);
if (ret == 0) {
    ret = wc_ecc_set_nonblock(&ecc, &nb_ctx);
    if (ret == 0) {
        do {
            ret = wc_ecc_verify_hash_ex(
                &r, &s,       // r/s as mp_int
                hash, hashSz, // computed hash digest
                &verify_res,  // verification result 1=success
                &key
            );

            // TODO: Real-time work can be called here
        } while (ret == FP_WOULDBLOCK);
    }
    wc_ecc_free(&key);
}

function wc_ecc_set_curve

int wc_ecc_set_curve(
    ecc_key * key,
    int keysize,
    int curve_id
)

Compare a curve which has larger key than specified size or the curve matched curve ID, set a curve with smaller key size to the key.

Parameters:

keysize Key size in bytes
curve_id Curve ID

                                                                                                _Example_

 int ret;
ecc_key ecc;

ret = wc_ecc_init(&ecc);
if (ret != 0)
    return ret;
    ret = wc_ecc_set_curve(&ecc, 32, ECC_SECP256R1));
    if (ret != 0)
        return ret;

Return: 0 Returned upon successfully setting the key

function wc_ecc_key_get_priv

mp_int * wc_ecc_key_get_priv(
    ecc_key * key
)

Gets private key mp_int from ECC key.

Parameters:

key ECC key structure

See: wc_ecc_init

Return:

mp_int pointer on success
NULL on failure

Example

ecc_key key;
mp_int* priv = wc_ecc_key_get_priv(&key);

function wc_ecc_get_sets_count

size_t wc_ecc_get_sets_count(
    void 
)

Returns number of supported ECC curve sets.

See: wc_ecc_get_curve_params

Return: Number of curve sets

Example

size_t count = wc_ecc_get_sets_count();

function wc_ecc_get_name

const char * wc_ecc_get_name(
    int curve_id
)

Gets curve name from curve ID.

Parameters:

curve_id Curve identifier

See: wc_ecc_get_curve_id

Return:

Curve name string on success
NULL on failure

Example

const char* name = wc_ecc_get_name(ECC_SECP256R1);

function wc_ecc_make_key_ex2

int wc_ecc_make_key_ex2(
    WC_RNG * rng,
    int keysize,
    ecc_key * key,
    int curve_id,
    int flags
)

Makes ECC key with extended options.

Parameters:

rng Random number generator
keysize Key size in bytes
key ECC key structure
curve_id Curve identifier
flags Additional flags

See: wc_ecc_make_key_ex

Return:

0 on success
negative on error

Example

WC_RNG rng;
ecc_key key;
int ret = wc_ecc_make_key_ex2(&rng, 32, &key,
                              ECC_SECP256R1, 0);

function wc_ecc_is_point

int wc_ecc_is_point(
    ecc_point * ecp,
    mp_int * a,
    mp_int * b,
    mp_int * prime
)

Checks if point is on curve.

Parameters:

ecp ECC point
a Curve parameter a
b Curve parameter b
prime Curve prime

See: wc_ecc_point_is_on_curve

Return:

1 if point is on curve
0 if not on curve
negative on error

Example

ecc_point* point;
mp_int a, b, prime;
int ret = wc_ecc_is_point(point, &a, &b, &prime);

function wc_ecc_get_generator

int wc_ecc_get_generator(
    ecc_point * ecp,
    int curve_idx
)

Gets generator point for curve.

Parameters:

ecp ECC point to store generator
curve_idx Curve index

See: wc_ecc_get_curve_params

Return:

0 on success
negative on error

Example

ecc_point* gen = wc_ecc_new_point();
int ret = wc_ecc_get_generator(gen, 0);

function wc_ecc_set_deterministic

int wc_ecc_set_deterministic(
    ecc_key * key,
    byte flag
)

Sets deterministic signing mode.

Parameters:

key ECC key
flag Enable/disable flag

See: wc_ecc_set_deterministic_ex

Return:

0 on success
negative on error

Example

ecc_key key;
int ret = wc_ecc_set_deterministic(&key, 1);

function wc_ecc_set_deterministic_ex

int wc_ecc_set_deterministic_ex(
    ecc_key * key,
    byte flag,
    enum wc_HashType hashType
)

Sets deterministic signing with hash type.

Parameters:

key ECC key
flag Enable/disable flag
hashType Hash algorithm type

See: wc_ecc_set_deterministic

Return:

0 on success
negative on error

Example

ecc_key key;
int ret = wc_ecc_set_deterministic_ex(&key, 1, WC_HASH_TYPE_SHA256);

function wc_ecc_gen_deterministic_k

int wc_ecc_gen_deterministic_k(
    const byte * hash,
    word32 hashSz,
    enum wc_HashType hashType,
    mp_int * priv,
    mp_int * k,
    mp_int * order,
    void * heap
)

Generates deterministic k value for signing.

Parameters:

hash Hash value
hashSz Hash size
hashType Hash algorithm type
priv Private key
k Output k value
order Curve order
heap Heap hint

See: wc_ecc_sign_set_k

Return:

0 on success
negative on error

Example

byte hash[32];
mp_int priv, k, order;
int ret = wc_ecc_gen_deterministic_k(hash, 32,
                                     WC_HASH_TYPE_SHA256,
                                     &priv, &k, &order, NULL);

function wc_ecc_sign_set_k

int wc_ecc_sign_set_k(
    const byte * k,
    word32 klen,
    ecc_key * key
)

Sets k value for signing.

Parameters:

k K value buffer
klen K value length
key ECC key

See: wc_ecc_gen_deterministic_k

Return:

0 on success
negative on error

Example

byte k[32];
ecc_key key;
int ret = wc_ecc_sign_set_k(k, sizeof(k), &key);

function wc_ecc_init_id

int wc_ecc_init_id(
    ecc_key * key,
    unsigned char * id,
    int len,
    void * heap,
    int devId
)

Initializes ECC key with ID.

Parameters:

key ECC key
id ID buffer
len ID length
heap Heap hint
devId Device ID

See: wc_ecc_init_label

Return:

0 on success
negative on error

Note: This API is only available when WOLF_PRIVATE_KEY_ID is defined, which is set for PKCS11 support.

Example

ecc_key key;
unsigned char id[] = "mykey";
int ret = wc_ecc_init_id(&key, id, sizeof(id), NULL,
                         INVALID_DEVID);

function wc_ecc_init_label

int wc_ecc_init_label(
    ecc_key * key,
    const char * label,
    void * heap,
    int devId
)

Initializes ECC key with label.

Parameters:

key ECC key
label Label string
heap Heap hint
devId Device ID

See: wc_ecc_init_id

Return:

0 on success
negative on error

Note: This API is only available when WOLF_PRIVATE_KEY_ID is defined, which is set for PKCS11 support.

Example

ecc_key key;
int ret = wc_ecc_init_label(&key, "mykey", NULL,
                            INVALID_DEVID);

function wc_ecc_set_flags

int wc_ecc_set_flags(
    ecc_key * key,
    word32 flags
)

Sets flags on ECC key.

Parameters:

key ECC key
flags Flags to set

See: wc_ecc_init

Return:

0 on success
negative on error

Example

ecc_key key;
int ret = wc_ecc_set_flags(&key, WC_ECC_FLAG_COFACTOR);

function wc_ecc_fp_init

void wc_ecc_fp_init(
    void 
)

Initializes fixed-point cache.

See: wc_ecc_init

Return: none No returns

Example

wc_ecc_fp_init();

function wc_ecc_set_rng

int wc_ecc_set_rng(
    ecc_key * key,
    WC_RNG * rng
)

Sets RNG for ECC key.

Parameters:

key ECC key
rng Random number generator

See: wc_ecc_make_key

Return:

0 on success
negative on error

Example

ecc_key key;
WC_RNG rng;
int ret = wc_ecc_set_rng(&key, &rng);

function wc_ecc_get_curve_idx

int wc_ecc_get_curve_idx(
    int curve_id
)

Gets curve index from curve ID.

Parameters:

curve_id Curve identifier

See: wc_ecc_get_curve_id

Return:

Curve index on success
negative on error

Example

int idx = wc_ecc_get_curve_idx(ECC_SECP256R1);

function wc_ecc_get_curve_id

int wc_ecc_get_curve_id(
    int curve_idx
)

Gets curve ID from curve index.

Parameters:

curve_idx Curve index

See: wc_ecc_get_curve_idx

Return:

Curve ID on success
negative on error

Example

int id = wc_ecc_get_curve_id(0);

function wc_ecc_get_curve_size_from_id

int wc_ecc_get_curve_size_from_id(
    int curve_id
)

Gets curve size from curve ID.

Parameters:

curve_id Curve identifier

See: wc_ecc_get_curve_id

Return:

Key size in bytes on success
negative on error

Example

int size = wc_ecc_get_curve_size_from_id(ECC_SECP256R1);

function wc_ecc_get_curve_idx_from_name

int wc_ecc_get_curve_idx_from_name(
    const char * curveName
)

Gets curve index from curve name.

Parameters:

curveName Curve name string

See: wc_ecc_get_name

Return:

Curve index on success
negative on error

Example

int idx = wc_ecc_get_curve_idx_from_name("SECP256R1");

function wc_ecc_get_curve_size_from_name

int wc_ecc_get_curve_size_from_name(
    const char * curveName
)

Gets curve size from curve name.

Parameters:

curveName Curve name string

See: wc_ecc_get_curve_idx_from_name

Return:

Key size in bytes on success
negative on error

Example

int size = wc_ecc_get_curve_size_from_name("SECP256R1");

function wc_ecc_get_curve_id_from_name

int wc_ecc_get_curve_id_from_name(
    const char * curveName
)

Gets curve ID from curve name.

Parameters:

curveName Curve name string

See: wc_ecc_get_name

Return:

Curve ID on success
negative on error

Example

int id = wc_ecc_get_curve_id_from_name("SECP256R1");

function wc_ecc_get_curve_id_from_params

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
)

Gets curve ID from curve parameters.

Parameters:

fieldSize Field size
prime Prime modulus
primeSz Prime size
Af Curve parameter A
AfSz A size
Bf Curve parameter B
BfSz B size
order Curve order
orderSz Order size
Gx Generator X coordinate
GxSz Gx size
Gy Generator Y coordinate
GySz Gy size
cofactor Curve cofactor

See: wc_ecc_get_curve_params

Return:

Curve ID on success
negative on error

Example

int id = wc_ecc_get_curve_id_from_params(256, prime, 32,
                                         Af, 32, Bf, 32,
                                         order, 32, Gx, 32,
                                         Gy, 32, 1);

function wc_ecc_get_curve_id_from_dp_params

int wc_ecc_get_curve_id_from_dp_params(
    const ecc_set_type * dp
)

Gets curve ID from domain parameters.

Parameters:

dp Domain parameters

See: wc_ecc_get_curve_params

Return:

Curve ID on success
negative on error

Example

const ecc_set_type* dp;
int id = wc_ecc_get_curve_id_from_dp_params(dp);

function wc_ecc_get_curve_id_from_oid

int wc_ecc_get_curve_id_from_oid(
    const byte * oid,
    word32 len
)

Gets curve ID from OID.

Parameters:

oid OID buffer
len OID length

See: wc_ecc_get_oid

Return:

Curve ID on success
negative on error

Example

byte oid[] = {0x2A, 0x86, 0x48, 0xCE, 0x3D, 0x03, 0x01, 0x07};
int id = wc_ecc_get_curve_id_from_oid(oid, sizeof(oid));

function wc_ecc_get_curve_params

const ecc_set_type * wc_ecc_get_curve_params(
    int curve_idx
)

Gets curve parameters from curve index.

Parameters:

curve_idx Curve index

See: wc_ecc_get_curve_idx

Return:

ecc_set_type pointer on success
NULL on failure

Example

const ecc_set_type* params = wc_ecc_get_curve_params(0);

function wc_ecc_new_point_h

ecc_point * wc_ecc_new_point_h(
    void * h
)

Allocates new ECC point with heap hint.

Parameters:

h Heap hint

See: wc_ecc_del_point_h

Return:

ecc_point pointer on success
NULL on failure

Example

ecc_point* point = wc_ecc_new_point_h(NULL);
if (point != NULL) {
    // use point
    wc_ecc_del_point_h(point, NULL);
}

function wc_ecc_del_point_h

void wc_ecc_del_point_h(
    ecc_point * p,
    void * h
)

Frees ECC point with heap hint.

Parameters:

p ECC point to free
h Heap hint

See: wc_ecc_new_point_h

Return: none No returns

Example

ecc_point* point = wc_ecc_new_point_h(NULL);
// use point
wc_ecc_del_point_h(point, NULL);

function wc_ecc_forcezero_point

void wc_ecc_forcezero_point(
    ecc_point * p
)

Securely zeros ECC point.

Parameters:

p ECC point to zero

See: wc_ecc_del_point

Return: none No returns

Example

ecc_point* point;
wc_ecc_forcezero_point(point);

function wc_ecc_point_is_on_curve

int wc_ecc_point_is_on_curve(
    ecc_point * p,
    int curve_idx
)

Checks if point is on curve.

Parameters:

p ECC point
curve_idx Curve index

See: wc_ecc_is_point

Return:

1 if on curve
0 if not on curve
negative on error

Example

ecc_point* point;
int ret = wc_ecc_point_is_on_curve(point, 0);

function wc_ecc_import_x963_ex

int wc_ecc_import_x963_ex(
    const byte * in,
    word32 inLen,
    ecc_key * key,
    int curve_id
)

Imports X9.63 format with curve ID.

Parameters:

in Input buffer
inLen Input length
key ECC key
curve_id Curve identifier

See: wc_ecc_import_x963

Return:

0 on success
negative on error

Example

byte x963[65];
ecc_key key;
int ret = wc_ecc_import_x963_ex(x963, sizeof(x963), &key,
                                ECC_SECP256R1);

function wc_ecc_import_private_key_ex

int wc_ecc_import_private_key_ex(
    const byte * priv,
    word32 privSz,
    const byte * pub,
    word32 pubSz,
    ecc_key * key,
    int curve_id
)

Imports private key with curve ID.

Parameters:

priv Private key buffer
privSz Private key size
pub Public key buffer
pubSz Public key size
key ECC key
curve_id Curve identifier

See: wc_ecc_import_private_key

Return:

0 on success
negative on error

Example

byte priv[32], pub[65];
ecc_key key;
int ret = wc_ecc_import_private_key_ex(priv, 32, pub, 65,
                                       &key, ECC_SECP256R1);

function wc_ecc_rs_raw_to_sig

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

Converts raw r,s to signature.

Parameters:

r R value buffer
rSz R value size
s S value buffer
sSz S value size
out Output signature buffer
outlen Output signature length

See: wc_ecc_sig_to_rs

Return:

0 on success
negative on error

Example

byte r[32], s[32], sig[72];
word32 sigLen = sizeof(sig);
int ret = wc_ecc_rs_raw_to_sig(r, 32, s, 32, sig, &sigLen);

function wc_ecc_sig_to_rs

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

Converts signature to raw r,s.

Parameters:

sig Signature buffer
sigLen Signature length
r R value buffer
rLen R value length
s S value buffer
sLen S value length

See: wc_ecc_rs_raw_to_sig

Return:

0 on success
negative on error

Example

byte sig[72], r[32], s[32];
word32 rLen = 32, sLen = 32;
int ret = wc_ecc_sig_to_rs(sig, 72, r, &rLen, s, &sLen);

function wc_ecc_import_raw_ex

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

Imports raw key with curve ID.

Parameters:

key ECC key
qx X coordinate string
qy Y coordinate string
d Private key string
curve_id Curve identifier

See: wc_ecc_import_raw

Return:

0 on success
negative on error

Example

ecc_key key;
int ret = wc_ecc_import_raw_ex(&key, qxStr, qyStr, dStr,
                               ECC_SECP256R1);

function wc_ecc_import_unsigned

int wc_ecc_import_unsigned(
    ecc_key * key,
    const byte * qx,
    const byte * qy,
    const byte * d,
    int curve_id
)

Imports unsigned key with curve ID.

Parameters:

key ECC key
qx X coordinate buffer
qy Y coordinate buffer
d Private key buffer
curve_id Curve identifier

See: wc_ecc_import_raw_ex

Return:

0 on success
negative on error

Example

ecc_key key;
byte qx[32], qy[32], d[32];
int ret = wc_ecc_import_unsigned(&key, qx, qy, d,
                                 ECC_SECP256R1);

function wc_ecc_export_ex

int wc_ecc_export_ex(
    ecc_key * key,
    byte * qx,
    word32 * qxLen,
    byte * qy,
    word32 * qyLen,
    byte * d,
    word32 * dLen,
    int encType
)

Exports key with encoding type.

Parameters:

key ECC key
qx X coordinate buffer
qxLen X coordinate length
qy Y coordinate buffer
qyLen Y coordinate length
d Private key buffer
dLen Private key length
encType Encoding type

See: wc_ecc_export_public_raw

Return:

0 on success
negative on error

Example

ecc_key key;
byte qx[32], qy[32], d[32];
word32 qxLen = 32, qyLen = 32, dLen = 32;
int ret = wc_ecc_export_ex(&key, qx, &qxLen, qy, &qyLen,
                           d, &dLen, 0);

function wc_ecc_export_public_raw

int wc_ecc_export_public_raw(
    ecc_key * key,
    byte * qx,
    word32 * qxLen,
    byte * qy,
    word32 * qyLen
)

Exports public key in raw format.

Parameters:

key ECC key
qx X coordinate buffer
qxLen X coordinate length
qy Y coordinate buffer
qyLen Y coordinate length

See: wc_ecc_export_private_raw

Return:

0 on success
negative on error

Example

ecc_key key;
byte qx[32], qy[32];
word32 qxLen = 32, qyLen = 32;
int ret = wc_ecc_export_public_raw(&key, qx, &qxLen, qy,
                                   &qyLen);

function wc_ecc_export_private_raw

int wc_ecc_export_private_raw(
    ecc_key * key,
    byte * qx,
    word32 * qxLen,
    byte * qy,
    word32 * qyLen,
    byte * d,
    word32 * dLen
)

Exports private key in raw format.

Parameters:

key ECC key
qx X coordinate buffer
qxLen X coordinate length
qy Y coordinate buffer
qyLen Y coordinate length
d Private key buffer
dLen Private key length

See: wc_ecc_export_public_raw

Return:

0 on success
negative on error

Example

ecc_key key;
byte qx[32], qy[32], d[32];
word32 qxLen = 32, qyLen = 32, dLen = 32;
int ret = wc_ecc_export_private_raw(&key, qx, &qxLen, qy,
                                    &qyLen, d, &dLen);

function wc_ecc_export_point_der_ex

int wc_ecc_export_point_der_ex(
    const int curve_idx,
    ecc_point * point,
    byte * out,
    word32 * outLen,
    int compressed
)

Exports point in DER format with compression.

Parameters:

curve_idx Curve index
point ECC point
out Output buffer
outLen Output length
compressed Compression flag

See: wc_ecc_export_point_der

Return:

Size on success
negative on error

Example

ecc_point* point;
byte out[65];
word32 outLen = sizeof(out);
int ret = wc_ecc_export_point_der_ex(0, point, out, &outLen,
                                     0);

function wc_ecc_import_point_der_ex

int wc_ecc_import_point_der_ex(
    const byte * in,
    word32 inLen,
    const int curve_idx,
    ecc_point * point,
    int shortKeySize
)

Imports point from DER format.

Parameters:

in Input buffer
inLen Input length
curve_idx Curve index
point ECC point
shortKeySize Short key size flag

See: wc_ecc_import_point_der

Return:

0 on success
negative on error

Example

byte der[65];
ecc_point* point = wc_ecc_new_point();
int ret = wc_ecc_import_point_der_ex(der, sizeof(der), 0,
                                     point, 0);

function wc_ecc_get_oid

int wc_ecc_get_oid(
    word32 oidSum,
    const byte ** oid,
    word32 * oidSz
)

Gets OID for curve.

Parameters:

oidSum OID sum
oid OID buffer pointer
oidSz OID size pointer

See: wc_ecc_get_curve_id_from_oid

Return:

0 on success
negative on error

Example

const byte* oid;
word32 oidSz;
int ret = wc_ecc_get_oid(0x2A8648CE3D030107, &oid, &oidSz);

function wc_ecc_set_custom_curve

int wc_ecc_set_custom_curve(
    ecc_key * key,
    const ecc_set_type * dp
)

Sets custom curve parameters.

Parameters:

key ECC key
dp Domain parameters

See: wc_ecc_get_curve_params

Return:

0 on success
negative on error

Example

ecc_key key;
ecc_set_type dp;
int ret = wc_ecc_set_custom_curve(&key, &dp);

function wc_ecc_ctx_new_ex

ecEncCtx * wc_ecc_ctx_new_ex(
    int flags,
    WC_RNG * rng,
    void * heap
)

Creates new ECC encryption context with heap.

Parameters:

flags Context flags
rng Random number generator
heap Heap hint

See: wc_ecc_ctx_new

Return:

ecEncCtx pointer on success
NULL on failure

Example

WC_RNG rng;
ecEncCtx* ctx = wc_ecc_ctx_new_ex(0, &rng, NULL);

function wc_ecc_ctx_set_own_salt

int wc_ecc_ctx_set_own_salt(
    ecEncCtx * ctx,
    const byte * salt,
    word32 sz
)

Sets own salt in context.

Parameters:

ctx ECC encryption context
salt Salt buffer
sz Salt size

See: wc_ecc_ctx_get_own_salt

Return:

0 on success
negative on error

Example

ecEncCtx* ctx;
byte salt[16];
int ret = wc_ecc_ctx_set_own_salt(ctx, salt, sizeof(salt));

function wc_X963_KDF

int wc_X963_KDF(
    enum wc_HashType type,
    const byte * secret,
    word32 secretSz,
    const byte * sinfo,
    word32 sinfoSz,
    byte * out,
    word32 outSz
)

X9.63 Key Derivation Function.

Parameters:

type Hash type
secret Shared secret
secretSz Secret size
sinfo Shared info
sinfoSz Shared info size
out Output buffer
outSz Output size

See: wc_ecc_shared_secret

Return:

0 on success
negative on error

Example

byte secret[32], sinfo[10], out[32];
int ret = wc_X963_KDF(WC_HASH_TYPE_SHA256, secret, 32,
                      sinfo, 10, out, 32);

function wc_ecc_curve_cache_init

int wc_ecc_curve_cache_init(
    void 
)

Initializes curve cache.

See: wc_ecc_curve_cache_free

Return:

0 on success
negative on error

Example

int ret = wc_ecc_curve_cache_init();

function wc_ecc_curve_cache_free

void wc_ecc_curve_cache_free(
    void 
)

Frees curve cache.

See: wc_ecc_curve_cache_init

Return: none No returns

Example

wc_ecc_curve_cache_free();

function wc_ecc_gen_k

int wc_ecc_gen_k(
    WC_RNG * rng,
    int size,
    mp_int * k,
    mp_int * order
)

Generates random k value.

Parameters:

rng Random number generator
size Key size
k Output k value
order Curve order

See: wc_ecc_sign_hash

Return:

0 on success
negative on error

Example

WC_RNG rng;
mp_int k, order;
int ret = wc_ecc_gen_k(&rng, 32, &k, &order);

function wc_ecc_set_handle

int wc_ecc_set_handle(
    ecc_key * key,
    remote_handle64 handle
)

Sets remote handle for hardware.

Parameters:

key ECC key
handle Remote handle

See: wc_ecc_init

Return:

0 on success
negative on error

Example

ecc_key key;
remote_handle64 handle = 0x1234;
int ret = wc_ecc_set_handle(&key, handle);

function wc_ecc_use_key_id

int wc_ecc_use_key_id(
    ecc_key * key,
    word32 keyId,
    word32 flags
)

Uses key ID for hardware.

Parameters:

key ECC key
keyId Key identifier
flags Flags

See: wc_ecc_get_key_id

Return:

0 on success
negative on error

Example

ecc_key key;
int ret = wc_ecc_use_key_id(&key, 1, 0);

function wc_ecc_get_key_id

int wc_ecc_get_key_id(
    ecc_key * key,
    word32 * keyId
)

Gets key ID from hardware key.

Parameters:

key ECC key
keyId Key identifier pointer

See: wc_ecc_use_key_id

Return:

0 on success
negative on error

Example

ecc_key key;
word32 keyId;
int ret = wc_ecc_get_key_id(&key, &keyId);

Source code


int wc_ecc_make_key(WC_RNG* rng, int keysize, ecc_key* key);

int wc_ecc_make_key_ex(WC_RNG* rng, int keysize, ecc_key* key, int curve_id);

int wc_ecc_make_pub(ecc_key* key, ecc_point* pubOut);

int wc_ecc_make_pub_ex(ecc_key* key, ecc_point* pubOut, WC_RNG* rng);

int wc_ecc_check_key(ecc_key* key);

void wc_ecc_key_free(ecc_key* key);

int wc_ecc_shared_secret(ecc_key* private_key, ecc_key* public_key, byte* out,
                      word32* outlen);

int wc_ecc_shared_secret_ex(ecc_key* private_key, ecc_point* point,
                             byte* out, word32 *outlen);

int wc_ecc_sign_hash(const byte* in, word32 inlen, byte* out, word32 *outlen,
                     WC_RNG* rng, ecc_key* key);

int wc_ecc_sign_hash_ex(const byte* in, word32 inlen, WC_RNG* rng,
                        ecc_key* key, mp_int *r, mp_int *s);

int wc_ecc_verify_hash(const byte* sig, word32 siglen, const byte* hash,
                    word32 hashlen, int* stat, ecc_key* key);

int wc_ecc_verify_hash_ex(mp_int *r, mp_int *s, const byte* hash,
                          word32 hashlen, int* stat, ecc_key* key);

int wc_ecc_init(ecc_key* key);

int wc_ecc_init_ex(ecc_key* key, void* heap, int devId);

ecc_key* wc_ecc_key_new(void* heap);

int wc_ecc_free(ecc_key* key);

void wc_ecc_fp_free(void);

int wc_ecc_is_valid_idx(int n);

ecc_point* wc_ecc_new_point(void);

void wc_ecc_del_point(ecc_point* p);

int wc_ecc_copy_point(const ecc_point* p, ecc_point *r);

int wc_ecc_cmp_point(ecc_point* a, ecc_point *b);

int wc_ecc_point_is_at_infinity(ecc_point *p);

int wc_ecc_mulmod(const mp_int* k, ecc_point *G, ecc_point *R,
                  mp_int* a, mp_int* modulus, int map);

int wc_ecc_export_x963(ecc_key* key, byte* out, word32* outLen);

int wc_ecc_export_x963_ex(ecc_key* key, byte* out, word32* outLen, int compressed);

int wc_ecc_import_x963(const byte* in, word32 inLen, ecc_key* key);

int wc_ecc_import_private_key(const byte* priv, word32 privSz, const byte* pub,
                           word32 pubSz, ecc_key* key);

int wc_ecc_rs_to_sig(const char* r, const char* s, byte* out, word32* outlen);

int wc_ecc_import_raw(ecc_key* key, const char* qx, const char* qy,
                   const char* d, const char* curveName);

int wc_ecc_export_private_only(ecc_key* key, byte* out, word32* outLen);

int wc_ecc_export_point_der(const int curve_idx, ecc_point* point,
                            byte* out, word32* outLen);

int wc_ecc_import_point_der(const byte* in, word32 inLen, const int curve_idx,
                            ecc_point* point);

int wc_ecc_size(ecc_key* key);

int wc_ecc_sig_size_calc(int sz);


int wc_ecc_sig_size(const ecc_key* key);


ecEncCtx* wc_ecc_ctx_new(int flags, WC_RNG* rng);

void wc_ecc_ctx_free(ecEncCtx* ctx);

int wc_ecc_ctx_reset(ecEncCtx* ctx, WC_RNG* rng);  /* reset for use again w/o alloc/free */

int wc_ecc_ctx_set_algo(ecEncCtx* ctx, byte encAlgo, byte kdfAlgo,
    byte macAlgo);

const byte* wc_ecc_ctx_get_own_salt(ecEncCtx*);

int wc_ecc_ctx_set_peer_salt(ecEncCtx* ctx, const byte* salt);

int wc_ecc_ctx_set_kdf_salt(ecEncCtx* ctx, const byte* salt, word32 sz);

int wc_ecc_ctx_set_info(ecEncCtx* ctx, const byte* info, int sz);

int wc_ecc_encrypt(ecc_key* privKey, ecc_key* pubKey, const byte* msg,
                word32 msgSz, byte* out, word32* outSz, ecEncCtx* ctx);

int wc_ecc_encrypt_ex(ecc_key* privKey, ecc_key* pubKey, const byte* msg,
    word32 msgSz, byte* out, word32* outSz, ecEncCtx* ctx, int compressed);

int wc_ecc_decrypt(ecc_key* privKey, ecc_key* pubKey, const byte* msg,
                word32 msgSz, byte* out, word32* outSz, ecEncCtx* ctx);


int wc_ecc_set_nonblock(ecc_key *key, ecc_nb_ctx_t* ctx);

int wc_ecc_set_curve(ecc_key *key, int keysize, int curve_id);

mp_int* wc_ecc_key_get_priv(ecc_key* key);

ecc_key* wc_ecc_key_new(void* heap);

size_t wc_ecc_get_sets_count(void);

const char* wc_ecc_get_name(int curve_id);

int wc_ecc_make_key_ex2(WC_RNG* rng, int keysize, ecc_key* key,
    int curve_id, int flags);

int wc_ecc_is_point(ecc_point* ecp, mp_int* a, mp_int* b,
    mp_int* prime);

int wc_ecc_get_generator(ecc_point* ecp, int curve_idx);

int wc_ecc_set_deterministic(ecc_key* key, byte flag);

int wc_ecc_set_deterministic_ex(ecc_key* key, byte flag,
    enum wc_HashType hashType);

int wc_ecc_gen_deterministic_k(const byte* hash, word32 hashSz,
    enum wc_HashType hashType, mp_int* priv, mp_int* k,
    mp_int* order, void* heap);

int wc_ecc_sign_set_k(const byte* k, word32 klen, ecc_key* key);

int wc_ecc_init_id(ecc_key* key, unsigned char* id, int len,
    void* heap, int devId);

int wc_ecc_init_label(ecc_key* key, const char* label, void* heap,
    int devId);

int wc_ecc_set_flags(ecc_key* key, word32 flags);

void wc_ecc_fp_init(void);

int wc_ecc_set_rng(ecc_key* key, WC_RNG* rng);

int wc_ecc_get_curve_idx(int curve_id);

int wc_ecc_get_curve_id(int curve_idx);

int wc_ecc_get_curve_size_from_id(int curve_id);

int wc_ecc_get_curve_idx_from_name(const char* curveName);

int wc_ecc_get_curve_size_from_name(const char* curveName);

int wc_ecc_get_curve_id_from_name(const char* curveName);

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);

int wc_ecc_get_curve_id_from_dp_params(const ecc_set_type* dp);

int wc_ecc_get_curve_id_from_oid(const byte* oid, word32 len);

const ecc_set_type* wc_ecc_get_curve_params(int curve_idx);

ecc_point* wc_ecc_new_point(void);

ecc_point* wc_ecc_new_point_h(void* h);

void wc_ecc_del_point_h(ecc_point* p, void* h);

void wc_ecc_forcezero_point(ecc_point* p);

int wc_ecc_point_is_on_curve(ecc_point *p, int curve_idx);

int wc_ecc_import_x963_ex(const byte* in, word32 inLen,
    ecc_key* key, int curve_id);

int wc_ecc_import_private_key_ex(const byte* priv, word32 privSz,
    const byte* pub, word32 pubSz, ecc_key* key, int curve_id);

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

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

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

int wc_ecc_import_unsigned(ecc_key* key, const byte* qx,
    const byte* qy, const byte* d, int curve_id);

int wc_ecc_export_ex(ecc_key* key, byte* qx, word32* qxLen,
    byte* qy, word32* qyLen, byte* d, word32* dLen, int encType);

int wc_ecc_export_public_raw(ecc_key* key, byte* qx,
    word32* qxLen, byte* qy, word32* qyLen);

int wc_ecc_export_private_raw(ecc_key* key, byte* qx,
    word32* qxLen, byte* qy, word32* qyLen, byte* d, word32* dLen);

int wc_ecc_export_point_der_ex(const int curve_idx,
    ecc_point* point, byte* out, word32* outLen, int compressed);

int wc_ecc_import_point_der_ex(const byte* in, word32 inLen,
    const int curve_idx, ecc_point* point, int shortKeySize);

int wc_ecc_get_oid(word32 oidSum, const byte** oid, word32* oidSz);

int wc_ecc_set_custom_curve(ecc_key* key, const ecc_set_type* dp);

ecEncCtx* wc_ecc_ctx_new(int flags, WC_RNG* rng);

ecEncCtx* wc_ecc_ctx_new_ex(int flags, WC_RNG* rng, void* heap);

int wc_ecc_ctx_reset(ecEncCtx* ctx, WC_RNG* rng);

const byte* wc_ecc_ctx_get_own_salt(ecEncCtx* ctx);

int wc_ecc_ctx_set_own_salt(ecEncCtx* ctx, const byte* salt,
    word32 sz);

int wc_X963_KDF(enum wc_HashType type, const byte* secret,
    word32 secretSz, const byte* sinfo, word32 sinfoSz,
    byte* out, word32 outSz);

int wc_ecc_curve_cache_init(void);

void wc_ecc_curve_cache_free(void);

int wc_ecc_gen_k(WC_RNG* rng, int size, mp_int* k, mp_int* order);

int wc_ecc_set_handle(ecc_key* key, remote_handle64 handle);

int wc_ecc_use_key_id(ecc_key* key, word32 keyId, word32 flags);

int wc_ecc_get_key_id(ecc_key* key, word32* keyId);

Updated on 2025-12-31 at 01:16:04 +0000