My Project
Functions
Algorithms - ECC

Functions

int wc_ecc_make_key (WC_RNG *rng, int keysize, ecc_key *key)
 This function generates a new ecc_key and stores it in key. More...
 
int wc_ecc_make_key_ex (WC_RNG *rng, int keysize, ecc_key *key, int curve_id)
 This function generates a new ecc_key and stores it in key. More...
 
int wc_ecc_check_key (ecc_key *key)
 Perform sanity checks on ecc key validity. More...
 
void wc_ecc_key_free (ecc_key *key)
 This function frees an ecc_key key after it has been used. More...
 
int wc_ecc_shared_secret (ecc_key *private_key, ecc_key *public_key, byte *out, word32 *outlen)
 This function generates a new secret key using a local private key and a received public key. It stores this shared secret key in the buffer out and updates outlen to hold the number of bytes written to the output buffer. More...
 
int wc_ecc_shared_secret_ex (ecc_key *private_key, ecc_point *point, byte *out, word32 *outlen)
 Create an ECC shared secret between private key and public point. More...
 
int wc_ecc_sign_hash (const byte *in, word32 inlen, byte *out, word32 *outlen, WC_RNG *rng, ecc_key *key)
 This function signs a message digest using an ecc_key object to guarantee authenticity. More...
 
int wc_ecc_sign_hash_ex (const byte *in, word32 inlen, WC_RNG *rng, ecc_key *key, mp_int *r, mp_int *s)
 Sign a message digest. More...
 
int wc_ecc_verify_hash (const byte *sig, word32 siglen, const byte *hash, word32 hashlen, int *stat, ecc_key *key)
 This function verifies the ECC signature of a hash to ensure authenticity. It returns the answer through stat, with 1 corresponding to a valid signature, and 0 corresponding to an invalid signature. More...
 
int wc_ecc_verify_hash_ex (mp_int *r, mp_int *s, const byte *hash, word32 hashlen, int *stat, ecc_key *key)
 Verify an ECC signature. Result is written to stat. 1 is valid, 0 is invalid. Note: Do not use the return value to test for valid. Only use stat. More...
 
int wc_ecc_init (ecc_key *key)
 This function initializes an ecc_key object for future use with message verification or key negotiation. More...
 
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. More...
 
ecc_key * wc_ecc_key_new (void *heap)
 This function uses a user defined heap and allocates space for the key structure. More...
 
int wc_ecc_free (ecc_key *key)
 This function frees an ecc_key object after it has been used. More...
 
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. More...
 
int wc_ecc_is_valid_idx (int n)
 Checks if an ECC idx is valid. More...
 
ecc_point * wc_ecc_new_point (void)
 Allocate a new ECC point. More...
 
void wc_ecc_del_point (ecc_point *p)
 Free an ECC point from memory. More...
 
int wc_ecc_copy_point (ecc_point *p, ecc_point *r)
 Copy the value of one point to another one. More...
 
int wc_ecc_cmp_point (ecc_point *a, ecc_point *b)
 Compare the value of a point with another one. More...
 
int wc_ecc_point_is_at_infinity (ecc_point *p)
 Checks if a point is at infinity. Returns 1 if point is at infinity, 0 if not, < 0 on error. More...
 
int wc_ecc_mulmod (mp_int *k, ecc_point *G, ecc_point *R, mp_int *a, mp_int *modulus, int map)
 Perform ECC Fixed Point multiplication. More...
 
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. More...
 
int wc_ecc_export_x963_ex (ecc_key *key, byte *out, word32 *outLen, int compressed)
 This function exports the ECC key from the ecc_key structure, storing the result in out. The key will be stored in ANSI X9.63 format. It stores the bytes written to the output buffer in outLen. This function allows the additional option of compressing the certificate through the compressed parameter. When this parameter is true, the key will be stored in ANSI X9.63 compressed format. More...
 
int wc_ecc_import_x963 (const byte *in, word32 inLen, ecc_key *key)
 This function imports a public ECC key from a buffer containing the key stored in ANSI X9.63 format. This function will handle both compressed and uncompressed keys, as long as compressed keys are enabled at compile time through the HAVE_COMP_KEY option. More...
 
int wc_ecc_import_private_key (const byte *priv, word32 privSz, const byte *pub, word32 pubSz, ecc_key *key)
 This function imports a public/private ECC key pair from a buffer containing the raw private key, and a second buffer containing the ANSI X9.63 formatted public key. This function will handle both compressed and uncompressed keys, as long as compressed keys are enabled at compile time through the HAVE_COMP_KEY option. More...
 
int wc_ecc_rs_to_sig (const char *r, const char *s, byte *out, word32 *outlen)
 This function converts the R and S portions of an ECC signature into a DER-encoded ECDSA signature. This function also stores the length written to the output buffer, out, in outlen. More...
 
int wc_ecc_import_raw (ecc_key *key, const char *qx, const char *qy, const char *d, const char *curveName)
 This function fills an ecc_key structure with the raw components of an ECC signature. More...
 
int wc_ecc_export_private_only (ecc_key *key, byte *out, word32 *outLen)
 This function exports only the private key from an ecc_key structure. It stores the private key in the buffer out, and sets the bytes written to this buffer in outLen. More...
 
int wc_ecc_export_point_der (const int curve_idx, ecc_point *point, byte *out, word32 *outLen)
 Export point to der. More...
 
int wc_ecc_import_point_der (byte *in, word32 inLen, const int curve_idx, ecc_point *point)
 Import point from der format. More...
 
int wc_ecc_size (ecc_key *key)
 This function returns the key size of an ecc_key structure in octets. More...
 
int wc_ecc_sig_size_calc (int sz)
 This function returns the worst case size for an ECC signature, given by: (keySz * 2) + SIG_HEADER_SZ + ECC_MAX_PAD_SZ. The actual signature size can be computed with wc_ecc_sign_hash. More...
 
int wc_ecc_sig_size (ecc_key *key)
 This function returns the worst case size for an ECC signature, given by: (keySz * 2) + SIG_HEADER_SZ + ECC_MAX_PAD_SZ. The actual signature size can be computed with wc_ecc_sign_hash. More...
 
ecEncCtx * wc_ecc_ctx_new (int flags, WC_RNG *rng)
 This function allocates and initializes space for a new ECC context object to allow secure message exchange with ECC. More...
 
void wc_ecc_ctx_free (ecEncCtx *)
 This function frees the ecEncCtx object used for encrypting and decrypting messages. More...
 
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. More...
 
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. More...
 
const byte * wc_ecc_ctx_get_own_salt (ecEncCtx *)
 This function returns the salt of an ecEncCtx object. This function should only be called when the ecEncCtx's state is ecSRV_INIT or ecCLI_INIT. More...
 
int wc_ecc_ctx_set_peer_salt (ecEncCtx *ctx, const byte *salt)
 This function sets the peer salt of an ecEncCtx object. More...
 
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. More...
 
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. More...
 
int wc_ecc_encrypt (ecc_key *privKey, ecc_key *pubKey, const byte *msg, word32 msgSz, byte *out, word32 *outSz, ecEncCtx *ctx)
 This function encrypts the given input message from msg to out. This function takes an optional ctx object as parameter. When supplied, encryption proceeds based on the ecEncCtx's encAlgo, kdfAlgo, and macAlgo. If ctx is not supplied, processing completes with the default algorithms, ecAES_128_CBC, ecHKDF_SHA256 and ecHMAC_SHA256. This function requires that the messages are padded according to the encryption type specified by ctx. More...
 
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. More...
 
int wc_ecc_decrypt (ecc_key *privKey, ecc_key *pubKey, const byte *msg, word32 msgSz, byte *out, word32 *outSz, ecEncCtx *ctx)
 This function decrypts the ciphertext from msg to out. This function takes an optional ctx object as parameter. When supplied, encryption proceeds based on the ecEncCtx's encAlgo, kdfAlgo, and macAlgo. If ctx is not supplied, processing completes with the default algorithms, ecAES_128_CBC, ecHKDF_SHA256 and ecHMAC_SHA256. This function requires that the messages are padded according to the encryption type specified by ctx. More...
 
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. More...
 

Detailed Description

Function Documentation

◆ wc_ecc_check_key()

int wc_ecc_check_key ( ecc_key *  key)

Perform sanity checks on ecc key validity.

Returns
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.
Parameters
keyPointer to key to check.

Example

ecc_key key;
WC_RNG rng;
int check_result;
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
}
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_check_key(ecc_key *key)
Perform sanity checks on ecc key validity.
int wc_ecc_init(ecc_key *key)
This function initializes an ecc_key object for future use with message verification or key negotiati...
int wc_InitRng(WC_RNG *)
Gets the seed (from OS) and key cipher for rng. rng->drbg (deterministic random bit generator) alloca...
See also
wc_ecc_point_is_at_infinity

◆ wc_ecc_cmp_point()

int wc_ecc_cmp_point ( ecc_point *  a,
ecc_point *  b 
)

Compare the value of a point with another one.

Returns
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.
Parameters
aFirst point to compare.
bSecond point to compare.

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
}
int wc_ecc_cmp_point(ecc_point *a, ecc_point *b)
Compare the value of a point with another one.
ecc_point * wc_ecc_new_point(void)
Allocate a new ECC point.
See also
wc_ecc_new_point
wc_ecc_del_point
wc_ecc_copy_point

◆ wc_ecc_copy_point()

int wc_ecc_copy_point ( ecc_point *  p,
ecc_point *  r 
)

Copy the value of one point to another one.

Returns
ECC_BAD_ARG_E Error thrown when p or r is null.
MP_OKAY Point copied successfully
ret Error from internal functions. Can be...
Parameters
pThe point to copy.
rThe created point.

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
}
int wc_ecc_copy_point(ecc_point *p, ecc_point *r)
Copy the value of one point to another one.
See also
wc_ecc_new_point
wc_ecc_cmp_point
wc_ecc_del_point

◆ wc_ecc_ctx_free()

void wc_ecc_ctx_free ( ecEncCtx *  )

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

Returns
none Returns.
Parameters
ctxpointer to the ecEncCtx object to free

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);
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 ex...
See also
wc_ecc_ctx_new

◆ wc_ecc_ctx_get_own_salt()

const byte* wc_ecc_ctx_get_own_salt ( ecEncCtx *  )

This function returns the salt of an ecEncCtx object. This function should only be called when the ecEncCtx's state is ecSRV_INIT or ecCLI_INIT.

Returns
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
Parameters
ctxpointer to the ecEncCtx object from which to get the salt

Example

ecEncCtx* ctx;
WC_RNG rng;
const byte* salt;
wc_InitRng(&rng);
ctx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng);
if(salt == NULL) {
// error getting salt
}
const byte * wc_ecc_ctx_get_own_salt(ecEncCtx *)
This function returns the salt of an ecEncCtx object. This function should only be called when the ec...
See also
wc_ecc_ctx_new
wc_ecc_ctx_set_peer_salt
wc_ecc_ctx_set_kdf_salt

◆ 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.

Returns
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
Parameters
flagsindicate whether this is a server or client context Options are: REQ_RESP_CLIENT, and REQ_RESP_SERVER
rngpointer to a RNG object with which to generate a salt

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
}
See also
wc_ecc_encrypt
wc_ecc_encrypt_ex
wc_ecc_decrypt

◆ 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.

Returns
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
Parameters
ctxpointer to the ecEncCtx object to reset
rngpointer to an RNG object with which to generate a new salt

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
See also
wc_ecc_ctx_new

◆ 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.

Returns
0 Returned upon successfully setting the information for the ecEncCtx object.
BAD_FUNC_ARG Returned if the given ecEncCtx object is NULL.
Parameters
ctxpointer to the ecEncCtx for which to set the info
encAlgoencryption algorithm to use.
kdfAlgoKDF algorithm to use.
macAlgoMAC algorithm to use.

Example

ecEncCtx* ctx;
// initialize ctx
if(wc_ecc_ctx_set_algo(&ctx, ecAES_128_CTR, ecHKDF_SHA256, ecHMAC_SHA256))) {
// error setting info
}
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,...
See also
wc_ecc_ctx_new

◆ 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.

Returns
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
Parameters
ctxpointer to the ecEncCtx for which to set the info
infopointer to a buffer containing the info to set
szsize of the info buffer

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
}
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 inf...
See also
wc_ecc_ctx_new

◆ 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.

Returns
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.
Parameters
ctxpointer to the ecEncCtx for which to set the salt
saltpointer to salt buffer
szlength salt in bytes

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);
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.
See also
wc_ecc_ctx_get_own_salt
wc_ecc_ctx_get_peer_salt

◆ 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.

Returns
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
Parameters
ctxpointer to the ecEncCtx for which to set the salt
saltpointer to the peer's salt

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);
int wc_ecc_ctx_set_peer_salt(ecEncCtx *ctx, const byte *salt)
This function sets the peer salt of an ecEncCtx object.
See also
wc_ecc_ctx_get_own_salt
wc_ecc_ctx_set_kdf_salt

◆ 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.

Returns
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
Parameters
privKeypointer to the ecc_key object containing the private key to use for decryption
pubKeypointer to the ecc_key object containing the public key of the peer with whom one wishes to communicate
msgpointer to the buffer holding the ciphertext to decrypt
msgSzsize of the buffer to decrypt
outpointer to the buffer in which to store the decrypted plaintext
outSzpointer 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
ctxOptional: pointer to an ecEncCtx object specifying different decryption algorithms to use

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
}
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 ...
See also
wc_ecc_encrypt
wc_ecc_encrypt_ex

◆ wc_ecc_del_point()

void wc_ecc_del_point ( ecc_point *  p)

Free an ECC point from memory.

Returns
none No returns.
Parameters
pThe point to free.

Example

ecc_point* point;
point = wc_ecc_new_point();
if (point == NULL)
{
// Handle point creation error
}
// Do stuff with point
void wc_ecc_del_point(ecc_point *p)
Free an ECC point from memory.
See also
wc_ecc_new_point
wc_ecc_cmp_point
wc_ecc_copy_point

◆ 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.

Returns
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
Parameters
privKeypointer to the ecc_key object containing the private key to use for encryption
pubKeypointer to the ecc_key object containing the public key of the peer with whom one wishes to communicate
msgpointer to the buffer holding the message to encrypt
msgSzsize of the buffer to encrypt
outpointer to the buffer in which to store the encrypted ciphertext
outSzpointer 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
ctxOptional: pointer to an ecEncCtx object specifying different encryption algorithms to use

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
}
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 o...
See also
wc_ecc_encrypt_ex
wc_ecc_decrypt

◆ 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.

Returns
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
Parameters
privKeypointer to the ecc_key object containing the private key to use for encryption
pubKeypointer to the ecc_key object containing the public key of the peer with whom one wishes to communicate
msgpointer to the buffer holding the message to encrypt
msgSzsize of the buffer to encrypt
outpointer to the buffer in which to store the encrypted ciphertext
outSzpointer 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
ctxOptional: pointer to an ecEncCtx object specifying different encryption algorithms to use
compressedPublic key field is to be output in compressed format.

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
}
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 o...
See also
wc_ecc_encrypt
wc_ecc_decrypt

◆ 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.

Returns
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.
Parameters
curve_idxIndex of the curve used from ecc_sets.
pointPoint to export to der.
outDestination for the output.
outLenMaxsize allowed for output, destination for final size of output

Example

int curve_idx;
ecc_point* point;
byte out[];
word32 outLen;
wc_ecc_export_point_der(curve_idx, point, out, &outLen);
int wc_ecc_export_point_der(const int curve_idx, ecc_point *point, byte *out, word32 *outLen)
Export point to der.
See also
wc_ecc_import_point_der

◆ 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.

Returns
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
Parameters
keypointer to an ecc_key structure from which to export the private key
outpointer to the buffer in which to store the private key
outLenpointer 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

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
}
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 th...
See also
wc_ecc_import_private_key

◆ 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.

Returns
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
Parameters
keypointer to the ecc_key object to export
outpointer to the buffer in which to store the ANSI X9.63 formatted key
outLensize of the output buffer. On successfully storing the key, will hold the bytes written to the output buffer

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
}
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....
See also
wc_ecc_export_x963_ex
wc_ecc_import_x963

◆ wc_ecc_export_x963_ex()

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

This function exports the ECC key from the ecc_key structure, storing the result in out. The key will be stored in ANSI X9.63 format. It stores the bytes written to the output buffer in outLen. This function allows the additional option of compressing the certificate through the compressed parameter. When this parameter is true, the key will be stored in ANSI X9.63 compressed format.

Returns
0 Returned on successfully exporting the ecc_key
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 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
Parameters
keypointer to the ecc_key object to export
outpointer to the buffer in which to store the ANSI X9.63 formatted key
outLensize of the output buffer. On successfully storing the key, will hold the bytes written to the output buffer
compressedindicator of whether to store the key in compressed format. 1==compressed, 0==uncompressed

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
}
int wc_ecc_export_x963_ex(ecc_key *key, byte *out, word32 *outLen, int compressed)
This function exports the ECC key from the ecc_key structure, storing the result in out....
See also
wc_ecc_export_x963
wc_ecc_import_x963

◆ 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.

Returns
none No returns.
Parameters
noneNo parameters.

Example

ecc_key key;
// initialize key and perform secure exchanges
...
wc_ecc_fp_free();
See also
wc_ecc_free

◆ wc_ecc_free()

int wc_ecc_free ( ecc_key *  key)

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

Returns
int integer returned indicating wolfSSL error or success status.
Parameters
keypointer to the ecc_key object to free

Example

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

◆ wc_ecc_import_point_der()

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

Import point from der format.

Returns
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.
Parameters
inder buffer to import point from.
inLenLength of der buffer.
curve_idxIndex of curve.
pointDestination for point.

Example

byte in[];
word32 inLen;
int curve_idx;
ecc_point* point;
wc_ecc_import_point_der(in, inLen, curve_idx, point);
int wc_ecc_import_point_der(byte *in, word32 inLen, const int curve_idx, ecc_point *point)
Import point from der format.
See also
wc_ecc_export_point_der

◆ 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.

Returns
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
Parameters
privpointer to the buffer containing the raw private key
privSzsize of the private key buffer
pubpointer to the buffer containing the ANSI x9.63 formatted ECC public key
pubSzlength of the public key input buffer
keypointer to the ecc_key object in which to store the imported private/public key pair

Example

int ret;
byte pub[] = { initialize with ANSI X9.63 formatted key };
byte priv[] = { initialize with the raw private key };
ecc_key key;
ret = wc_ecc_import_private_key(priv, sizeof(priv), pub, sizeof(pub),
&key);
if ( ret != 0) {
// error importing 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,...
See also
wc_ecc_export_x963
wc_ecc_import_private_key

◆ 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.

Returns
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
Parameters
keypointer to an ecc_key structure to fill
qxpointer to a buffer containing the x component of the base point as an ASCII hex string
qypointer to a buffer containing the y component of the base point as an ASCII hex string
dpointer to a buffer containing the private key as an ASCII hex string
curveNamepointer to a string containing the ECC curve name, as found in ecc_sets

Example

int ret;
ecc_key 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
}
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.
See also
wc_ecc_import_private_key

◆ 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.

Returns
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
Parameters
inpointer to the buffer containing the ANSI x9.63 formatted ECC key
inLenlength of the input buffer
keypointer to the ecc_key object in which to store the imported 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
}
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....
See also
wc_ecc_export_x963
wc_ecc_import_private_key

◆ 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.

Returns
0 Returned upon successfully initializing the ecc_key object
MEMORY_E Returned if there is an error allocating memory
Parameters
keypointer to the ecc_key object to initialize

Example

ecc_key key;
See also
wc_ecc_make_key
wc_ecc_free

◆ 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.

Returns
0 Returned upon successfully initializing the ecc_key object
MEMORY_E Returned if there is an error allocating memory
Parameters
keypointer to the ecc_key object to initialize
heappointer to a heap identifier
devIdID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used

Example

ecc_key key;
wc_ecc_init_ex(&key, heap, devId);
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 negotiati...
See also
wc_ecc_make_key
wc_ecc_free
wc_ecc_init

◆ wc_ecc_is_valid_idx()

int wc_ecc_is_valid_idx ( int  n)

Checks if an ECC idx is valid.

Returns
1 Return if valid.
0 Return if not valid.
Parameters
nThe idx number to check.

Example

ecc_key key;
WC_RNG rng;
int is_valid;
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
}
int wc_ecc_is_valid_idx(int n)
Checks if an ECC idx is valid.
See also
none

◆ 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
keypointer to the ecc_key structure to free

Example

// initialize key and perform ECC operations
...
wc_ecc_key_free(&key);
See also
wc_ecc_key_new
wc_ecc_init_ex

◆ 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.

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

Example

ecc_key * wc_ecc_key_new(void *heap)
This function uses a user defined heap and allocates space for the key structure.
See also
wc_ecc_make_key
wc_ecc_key_free
wc_ecc_init

◆ 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.

Returns
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
Parameters
rngpointer to an initialized RNG object with which to generate the key
keysizedesired length for the ecc_key
keypointer to the ecc_key for which to generate a key

Example

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

◆ 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.

Returns
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
Parameters
keyPointer to store the created key.
keysizesize of key to be created in bytes, set based on curveId
rngRng to be used in key creation
curve_idCurve to use for key

Example

ecc_key key;
int ret;
WC_RNG rng;
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
}
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.
See also
wc_ecc_make_key
wc_ecc_get_curve_size_from_id

◆ wc_ecc_mulmod()

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

Perform ECC Fixed Point multiplication.

Returns
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.
Parameters
kThe multiplicand.
GBase point to multiply.
RDestination of product.
modulusThe modulus for the curve.
mapIf non-zero maps the point back to affine coordinates, otherwise it's left in jacobian-montgomery form.

Example

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

◆ wc_ecc_new_point()

ecc_point* wc_ecc_new_point ( void  )

Allocate a new ECC point.

Returns
p A newly allocated point.
NULL Returns NULL on error.
Parameters
noneNo parameters.

Example

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

◆ 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.

Returns
1 p is at infinity.
0 p is not at infinity.
<0 Error.
Parameters
pThe point to check.

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
}
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.
See also
wc_ecc_new_point
wc_ecc_del_point
wc_ecc_cmp_point
wc_ecc_copy_point

◆ 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.

Returns
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
Parameters
rpointer to the buffer containing the R portion of the signature as a string
spointer to the buffer containing the S portion of the signature as a string
outpointer to the buffer in which to store the DER-encoded ECDSA signature
outlenlength of the output buffer available. Will store the bytes written to the buffer after successfully converting the signature to ECDSA format

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
}
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....
int wc_ecc_sig_size(ecc_key *key)
This function returns the worst case size for an ECC signature, given by: (keySz * 2) + SIG_HEADER_SZ...
See also
wc_ecc_sign_hash
wc_ecc_sig_size

◆ 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.

Returns
0 Returned upon successfully setting the callback context the input message
Parameters
keypointer to the ecc_key object
ctxpointer to ecc_nb_ctx_t structure with stack data cache for SP

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 {
&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);
}
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 re...
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 fol...
int wc_ecc_free(ecc_key *key)
This function frees an ecc_key object after it has been used.

◆ 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.

Returns
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
Parameters
private_keypointer to the ecc_key structure containing the local private key
public_keypointer to the ecc_key structure containing the received public key
outpointer to an output buffer in which to store the generated shared secret key
outlenpointer 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

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
}
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....
See also
wc_ecc_init
wc_ecc_make_key

◆ 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.

Returns
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.
Parameters
private_keyThe private ECC key.
pointThe point to use (public key).
outOutput destination of the shared secret. Conforms to EC-DH from ANSI X9.63.
outlenInput the max size and output the resulting size of the shared secret.

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
}
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.
See also
wc_ecc_verify_hash_ex

◆ wc_ecc_sig_size()

int wc_ecc_sig_size ( ecc_key *  key)

This function returns the worst case size for an ECC signature, given by: (keySz * 2) + SIG_HEADER_SZ + ECC_MAX_PAD_SZ. The actual signature size can be computed with wc_ecc_sign_hash.

Returns
Success Given a valid key, returns the maximum signature size, in octets
0 Returned if the given key is NULL
Parameters
keypointer to an ecc_key structure for which to get the signature size

Example

int sigSz;
ecc_key key;
// initialize key, make key
sigSz = wc_ecc_sig_size(&key);
if ( sigSz == 0) {
// error determining sig size
}
See also
wc_ecc_sign_hash
wc_ecc_sig_size_calc

◆ 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.

Returns
returns the maximum signature size, in octets
Parameters
keysize

Example

int sigSz = wc_ecc_sig_size_calc(32);
if ( sigSz == 0) {
// error determining sig size
}
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...
See also
wc_ecc_sign_hash
wc_ecc_sig_size

◆ 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.

Returns
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
Parameters
inpointer to the buffer containing the message hash to sign
inlenlength of the message hash to sign
outbuffer in which to store the generated signature
outlenmax length of the output buffer. Will store the bytes written to out upon successfully generating a message signature
keypointer to a private ECC key with which to generate the 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
}
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.
See also
wc_ecc_verify_hash

◆ 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.

Returns
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
Parameters
inThe message digest to sign.
inlenThe length of the digest.
rngPointer to WC_RNG struct.
keyA private ECC key.
rThe destination for r component of the signature.
sThe destination for s component of the 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
}
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.
See also
wc_ecc_verify_hash_ex

◆ wc_ecc_size()

int wc_ecc_size ( ecc_key *  key)

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

Returns
Given a valid key, returns the key size in octets
0 Returned if the given key is NULL
Parameters
keypointer to an ecc_key structure for which to get the key size

Example

int keySz;
ecc_key key;
// initialize key, make key
keySz = wc_ecc_size(&key);
if ( keySz == 0) {
// error determining key size
}
int wc_ecc_size(ecc_key *key)
This function returns the key size of an ecc_key structure in octets.
See also
wc_ecc_make_key

◆ 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.

Returns
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
Parameters
sigpointer to the buffer containing the signature to verify
siglenlength of the signature to verify
hashpointer to the buffer containing the hash of the message verified
hashlenlength of the hash of the message verified
statpointer to the result of the verification. 1 indicates the message was successfully verified
keypointer to a public ECC key with which to verify the 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
}
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 thro...
See also
wc_ecc_sign_hash
wc_ecc_verify_hash_ex

◆ 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.

Returns
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.
Parameters
rThe signature R component to verify
sThe signature S component to verify
hashThe hash (message digest) that was signed
hashlenThe length of the hash (octets)
statResult of signature, 1==valid, 0==invalid
keyThe corresponding public ECC key

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
}
See also
wc_ecc_verify_hash