Algorithms - Curve25519

Functions
WOLFSSL_API int	wc_curve25519_make_key (WC_RNG *rng, int keysize, curve25519_key *key)
	This function generates a curve25519 key using the given random number generator, rng, of the size given (keysize), and stores it in the given curve25519_key structure. It should be called after the key structure has been initialized through wc_curve25519_init. More...
WOLFSSL_API int	wc_curve25519_shared_secret (curve25519_key *private_key, curve25519_key *public_key, byte *out, word32 *outlen)
	This function computes a shared secret key given a secret private key and a received public key. It stores the generated secret key in the buffer out and assigns the variable of the secret key to outlen. Only supports big endian. More...
WOLFSSL_API int	wc_curve25519_shared_secret_ex (curve25519_key *private_key, curve25519_key *public_key, byte *out, word32 *outlen, int endian)
	This function computes a shared secret key given a secret private key and a received public key. It stores the generated secret key in the buffer out and assigns the variable of the secret key to outlen. Supports both big and little endian. More...
WOLFSSL_API int	wc_curve25519_init (curve25519_key *key)
	This function initializes a curve25519 key. It should be called before generating a key for the structure with wc_curve25519_init and before using the key to encrypt data. More...
WOLFSSL_API void	wc_curve25519_free (curve25519_key *key)
	This function frees a curve 25519 object. More...
WOLFSSL_API int	wc_curve25519_import_private (const byte *priv, word32 privSz, curve25519_key *key)
	This function imports a curve25519 private key only. (Big endian). More...
WOLFSSL_API int	wc_curve25519_import_private_ex (const byte *priv, word32 privSz, curve25519_key *key, int endian)
	curve25519 private key import only. (Big or Little endian). More...
WOLFSSL_API int	wc_curve25519_import_private_raw (const byte *priv, word32 privSz, const byte *pub, word32 pubSz, curve25519_key *key)
	This function imports a public-private key pair into a curve25519_key structure. Big endian only. More...
WOLFSSL_API int	wc_curve25519_import_private_raw_ex (const byte *priv, word32 privSz, const byte *pub, word32 pubSz, curve25519_key *key, int endian)
	This function imports a public-private key pair into a curve25519_key structure. Supports both big and little endian. More...
WOLFSSL_API int	wc_curve25519_export_private_raw (curve25519_key *key, byte *out, word32 *outLen)
	This function exports a private key from a curve25519_key structure and stores it in the given out buffer. It also sets outLen to be the size of the exported key. Big Endian only. More...
WOLFSSL_API int	wc_curve25519_export_private_raw_ex (curve25519_key *key, byte *out, word32 *outLen, int endian)
	This function exports a private key from a curve25519_key structure and stores it in the given out buffer. It also sets outLen to be the size of the exported key. Can specify whether it's big or little endian. More...
WOLFSSL_API int	wc_curve25519_import_public (const byte *in, word32 inLen, curve25519_key *key)
	This function imports a public key from the given in buffer and stores it in the curve25519_key structure. More...
WOLFSSL_API int	wc_curve25519_import_public_ex (const byte *in, word32 inLen, curve25519_key *key, int endian)
	This function imports a public key from the given in buffer and stores it in the curve25519_key structure. More...
WOLFSSL_API int	wc_curve25519_export_public (curve25519_key *key, byte *out, word32 *outLen)
	This function exports a public key from the given key structure and stores the result in the out buffer. Big endian only. More...
WOLFSSL_API int	wc_curve25519_export_public_ex (curve25519_key *key, byte *out, word32 *outLen, int endian)
	This function exports a public key from the given key structure and stores the result in the out buffer. Supports both big and little endian. More...
WOLFSSL_API int	wc_curve25519_export_key_raw (curve25519_key *key, byte *priv, word32 *privSz, byte *pub, word32 *pubSz)
	Export curve25519 key pair. Big endian only. More...
WOLFSSL_API int	wc_curve25519_export_key_raw_ex (curve25519_key *key, byte *priv, word32 *privSz, byte *pub, word32 *pubSz, int endian)
	Export curve25519 key pair. Big or little endian. More...
WOLFSSL_API int	wc_curve25519_size (curve25519_key *key)
	This function returns the key size of the given key structure. More...

Detailed Description

Function Documentation

wc_curve25519_export_key_raw()

WOLFSSL_API int wc_curve25519_export_key_raw	(	curve25519_key *	key,
		byte *	priv,
		word32 *	privSz,
		byte *	pub,
		word32 *	pubSz
	)

Export curve25519 key pair. Big endian only.

Returns

0 Success

BAD_FUNC_ARG Returned if any input parameters are NULL.

ECC_BAD_ARG_E Returned if wc_curve25519_size() is not equal to key.

Parameters

key	Description
priv	Private key buffer.
privSz	Size of private key buffer.
pub	Public key buffer.
pubSz	Size of public key buffer.

Example

int ret;
byte pub[32];
byte priv[32];
int pubSz;
int privSz;

curve25519_key key;
// initialize and make key

ret = wc_curve25519_export_key_raw(&key, priv, &privSz, pub, &pubSz);
if (ret != 0) {
    // error exporting key
}

See also

wc_curve25519_export_key_raw_ex

wc_curve25519_export_private_raw

wc_curve25519_export_public_raw

wc_curve25519_export_key_raw_ex()

WOLFSSL_API int wc_curve25519_export_key_raw_ex	(	curve25519_key *	key,
		byte *	priv,
		word32 *	privSz,
		byte *	pub,
		word32 *	pubSz,
		int	endian
	)

Export curve25519 key pair. Big or little endian.

Returns

0 Success

BAD_FUNC_ARG Returned if any input parameters are NULL.

ECC_BAD_ARG_E Returned if wc_curve25519_size() is not equal to key.

Parameters

key	Description
priv	Private key buffer.
privSz	Size of private key buffer.
pub	Public key buffer.
pubSz	Size of public key buffer.
endian	EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which form to use.

Example

int ret;

byte pub[32];
byte priv[32];
int pubSz;
int privSz;

curve25519_key key;
// initialize and make key

ret = wc_curve25519_export_key_raw_ex(&key,priv, &privSz, pub, &pubSz,
EC25519_BIG_ENDIAN);
if (ret != 0) {
    // error exporting key
}

See also

wc_curve25519_export_key_raw

wc_curve25519_export_private_raw_ex

wc_curve25519_export_public_ex

wc_curve25519_export_private_raw()

WOLFSSL_API int wc_curve25519_export_private_raw	(	curve25519_key *	key,
		byte *	out,
		word32 *	outLen
	)

This function exports a private key from a curve25519_key structure and stores it in the given out buffer. It also sets outLen to be the size of the exported key. Big Endian only.

Returns

0 Returned on successfully exporting the private key from the curve25519_key structure

BAD_FUNC_ARG Returned if any input parameters are NULL.

ECC_BAD_ARG_E Returned if wc_curve25519_size() is not equal to key.

Parameters

key	pointer to the structure from which to export the key
out	pointer to the buffer in which to store the exported key
outLen	will store the bytes written to the output buffer

Example

int ret;
byte priv[32];
int privSz;

curve25519_key key;
// initialize and make key

ret = wc_curve25519_export_private_raw(&key, priv, &privSz);
if (ret != 0) {
    // error exporting key
}

See also

wc_curve25519_init

wc_curve25519_make_key

wc_curve25519_import_private_raw

wc_curve25519_export_private_raw_ex

wc_curve25519_export_private_raw_ex()

WOLFSSL_API int wc_curve25519_export_private_raw_ex	(	curve25519_key *	key,
		byte *	out,
		word32 *	outLen,
		int	endian
	)

This function exports a private key from a curve25519_key structure and stores it in the given out buffer. It also sets outLen to be the size of the exported key. Can specify whether it's big or little endian.

Returns

0 Returned on successfully exporting the private key from the curve25519_key structure

BAD_FUNC_ARG Returned if any input parameters are NULL.

ECC_BAD_ARG_E Returned if wc_curve25519_size() is not equal to key.

Parameters

key	pointer to the structure from which to export the key
out	pointer to the buffer in which to store the exported key
outLen	will store the bytes written to the output buffer
endian	EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which form to use.

Example

int ret;

byte priv[32];
int privSz;
curve25519_key key;
// initialize and make key
ret = wc_curve25519_export_private_raw_ex(&key, priv, &privSz,
EC25519_BIG_ENDIAN);
if (ret != 0) {
    // error exporting key
}

See also

wc_curve25519_init

wc_curve25519_make_key

wc_curve25519_import_private_raw

wc_curve25519_export_private_raw

wc_curve25519_size

wc_curve25519_export_public()

WOLFSSL_API int wc_curve25519_export_public	(	curve25519_key *	key,
		byte *	out,
		word32 *	outLen
	)

This function exports a public key from the given key structure and stores the result in the out buffer. Big endian only.

Returns

0 Returned on successfully exporting the public key from the curve25519_key structure

ECC_BAD_ARG_E Returned if any of the input parameters are NULL

Parameters

key	pointer to the curve25519_key structure in from which to export the key
out	pointer to the buffer in which to store the public key
outLen	will store the bytes written to the output buffer

Example

int ret;
byte pub[32];
int pubSz;
curve25519_key key;
// initialize and make key
ret = wc_curve25519_export_public(&key,pub, &pubSz);
if (ret != 0) {
    // error exporting key
}

See also

wc_curve25519_init

wc_curve25519_export_private_raw

wc_curve25519_import_public

wc_curve25519_export_public_ex()

WOLFSSL_API int wc_curve25519_export_public_ex	(	curve25519_key *	key,
		byte *	out,
		word32 *	outLen,
		int	endian
	)

This function exports a public key from the given key structure and stores the result in the out buffer. Supports both big and little endian.

Returns

0 Returned on successfully exporting the public key from the curve25519_key structure

ECC_BAD_ARG_E Returned if any of the input parameters are NULL

Parameters

key	pointer to the curve25519_key structure in from which to export the key
out	pointer to the buffer in which to store the public key
outLen	will store the bytes written to the output buffer
endian	EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which form to use.

Example

int ret;

byte pub[32];
int pubSz;
curve25519_key key;
// initialize and make key

ret = wc_curve25519_export_public_ex(&key,pub, &pubSz, EC25519_BIG_ENDIAN);
if (ret != 0) {
    // error exporting key
}

See also

wc_curve25519_init

wc_curve25519_export_private_raw

wc_curve25519_import_public

wc_curve25519_free()

WOLFSSL_API void wc_curve25519_free

(

curve25519_key *

key

)

This function frees a curve 25519 object.

Returns

none No returns.

Parameters

key	pointer to the key object to free

Example

curve25519_key privKey;
// initialize key, use it to generate shared secret key
wc_curve25519_free(&privKey);

See also

wc_curve25519_init

wc_curve25519_make_key

wc_curve25519_import_private()

WOLFSSL_API int wc_curve25519_import_private	(	const byte *	priv,
		word32	privSz,
		curve25519_key *	key
	)

This function imports a curve25519 private key only. (Big endian).

Returns

0 Success

BAD_FUNC_ARG Returns if key or priv is null.

ECC_BAD_ARG_E Returns if privSz is not equal to wc_curve25519_size(key).

Parameters

priv	Private key buffer
privSz	Size of private key buffer.
key	The curve25519_key structure to store the private key.

Example

byte priv[] = { Contents of private key };
curve25519_key key;
wc_curve25519_init(&key);

if(wc_curve25519_import_private(priv, sizeof(priv), &key) != 0)
{
    // Some error was thrown
}

See also

wc_curve25519_import_private_ex

wc_curve25519_size

wc_curve25519_import_private_ex()

WOLFSSL_API int wc_curve25519_import_private_ex	(	const byte *	priv,
		word32	privSz,
		curve25519_key *	key,
		int	endian
	)

curve25519 private key import only. (Big or Little endian).

Returns

0 Success

Returns if key or priv is null.

ECC_BAD_ARG_E Returns if privSz is not equal to wc_curve25519_size(key).

Parameters

priv	Buffer for private key.
privSz	Size of private key buffer.
key	The curve25519_key structure to store the private key.
endian	EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which form to use.

Example

byte priv[] = { // Contents of private key };
curve25519_key key;
wc_curve25519_init(&key);

if(wc_curve25519_import_private_ex(priv, sizeof(priv), &key,
EC25519_BIG_ENDIAN) != 0)
{
   // Some error was thrown
}

See also

wc_curve25519_import_private

wc_curbe25519_size

wc_curve25519_import_private_raw()

WOLFSSL_API int wc_curve25519_import_private_raw	(	const byte *	priv,
		word32	privSz,
		const byte *	pub,
		word32	pubSz,
		curve25519_key *	key
	)

This function imports a public-private key pair into a curve25519_key structure. Big endian only.

Returns

0 Returned on importing into the curve25519_key structure

ECC_BAD_ARG_E Returned if any of the input parameters are NULL, or the input key’s key size does not match the public or private key sizes

Parameters

priv	pointer to a buffer containing the private key to import
privSz	length of the private key to import
pub	pointer to a buffer containing the public key to import
pubSz	length of the public key to import
key	pointer to the structure in which to store the imported keys

Example

int ret;

byte priv[32];
byte pub[32];
// initialize with public and private keys
curve25519_key key;

wc_curve25519_init(&key);
// initialize key

ret = wc_curve25519_import_private_raw(&priv, sizeof(priv), pub,
sizeof(pub),&key);
if (ret != 0) {
    // error importing keys
}

See also

wc_curve25519_init

wc_curve25519_make_key

wc_curve25519_import_public

wc_curve25519_export_private_raw

wc_curve25519_import_private_raw_ex()

WOLFSSL_API int wc_curve25519_import_private_raw_ex	(	const byte *	priv,
		word32	privSz,
		const byte *	pub,
		word32	pubSz,
		curve25519_key *	key,
		int	endian
	)

This function imports a public-private key pair into a curve25519_key structure. Supports both big and little endian.

Returns

0 Returned on importing into the curve25519_key structure

ECC_BAD_ARG_E Returned if any of the input parameters are NULL, or the input key’s key size does not match the public or private key sizes

Parameters

priv	pointer to a buffer containing the private key to import
privSz	length of the private key to import
pub	pointer to a buffer containing the public key to import
pubSz	length of the public key to import
key	pointer to the structure in which to store the imported keys
endian	EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which form to use.

Example

int ret;
byte priv[32];
byte pub[32];
// initialize with public and private keys
curve25519_key key;

wc_curve25519_init(&key);
// initialize key

ret = wc_curve25519_import_private_raw_ex(&priv, sizeof(priv), pub,
sizeof(pub),&key, EC25519_BIG_ENDIAN);
if (ret != 0) {
    // error importing keys
}

See also

wc_curve25519_init

wc_curve25519_make_key

wc_curve25519_import_public

wc_curve25519_export_private_rawm

wc_curve25519_import_private_raw

wc_curve25519_import_public()

WOLFSSL_API int wc_curve25519_import_public	(	const byte *	in,
		word32	inLen,
		curve25519_key *	key
	)

This function imports a public key from the given in buffer and stores it in the curve25519_key structure.

Returns

0 Returned on successfully importing the public key into the curve25519_key structure

ECC_BAD_ARG_E Returned if any of the input parameters are NULL, or if the inLen parameter does not match the key size of the key structure.

BAD_FUNC_ARG Returned if any of the input parameters are NULL.

Parameters

in	pointer to the buffer containing the public key to import
inLen	length of the public key to import
key	pointer to the curve25519_key structure in which to store the key

Example

int ret;

byte pub[32];
// initialize pub with public key

curve25519_key key;
// initialize key

ret = wc_curve25519_import_public(pub,sizeof(pub), &key);
if (ret != 0) {
    // error exporting key
}

See also

wc_curve25519_init

wc_curve25519_export_public

wc_curve25519_import_private_raw

wc_curve25519_public_ex

wc_curve25519_import_public_ex()

WOLFSSL_API int wc_curve25519_import_public_ex	(	const byte *	in,
		word32	inLen,
		curve25519_key *	key,
		int	endian
	)

This function imports a public key from the given in buffer and stores it in the curve25519_key structure.

0 Returned on successfully importing the public key into the curve25519_key structure ECC_BAD_ARG_E Returned if the inLen parameter does not match the key size of the key structure BAD_FUNC_ARG Returned if any of the input parameters are NULL.

Parameters

in	pointer to the buffer containing the public key to import
inLen	length of the public key to import
key	pointer to the curve25519_key structure in which to store the key
endian	EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which form to use.

Example

int ret;
byte pub[32];
// initialize pub with public key
curve25519_key key;
// initialize key

ret = wc_curve25519_import_public_ex(pub,sizeof(pub), &key,
EC25519_BIG_ENDIAN);
if (ret != 0) {
    // error exporting key
}

See also

wc_curve25519_init

wc_curve25519_export_public

wc_curve25519_import_private_raw

wc_curve25519_import_public

wc_25519_size

wc_curve25519_init()

WOLFSSL_API int wc_curve25519_init

(

curve25519_key *

key

)

This function initializes a curve25519 key. It should be called before generating a key for the structure with wc_curve25519_init and before using the key to encrypt data.

Returns

0 Returned on successfully initializing the curve25519_key structure

Parameters

key	pointer to the curve25519_key structure to initialize

Example

curve25519_key key;
wc_curve25519_init(&key); // initialize key
// make key and proceed to encryption

See also

wc_curve25519_make_key

wc_curve25519_make_key()

WOLFSSL_API int wc_curve25519_make_key	(	WC_RNG *	rng,
		int	keysize,
		curve25519_key *	key
	)

This function generates a curve25519 key using the given random number generator, rng, of the size given (keysize), and stores it in the given curve25519_key structure. It should be called after the key structure has been initialized through wc_curve25519_init.

Returns

0 Returned on successfully generating the key and and storing it in the given curve25519_key structure

ECC_BAD_ARG_E Returned if rng or key evaluate to NULL, or the input keysize does not correspond to the keysize for a curve25519 key ( 32 bytes)

RNG_FAILURE_E Returned if the rng internal status is not DRBG_OK or if there is in generating the next random block with rng

Parameters

rng	pointer to the RNG object used to generate the ecc key
keysize	size of the key to generate. Must be 32 bytes for curve25519
key	pointer to the curve25519_key structure in which to store the generated key

Example

curve25519_key key;
wc_curve25519_init(&key); // initialize key
WC_RNG rng;
wc_InitRng(&rng); // initialize random number generator

if( wc_curve25519_make_key(&rng, 32, &key) != 0) {
    // making 25519 key
}

See also

wc_curve25519_init

wc_curve25519_shared_secret()

WOLFSSL_API int wc_curve25519_shared_secret	(	curve25519_key *	private_key,
		curve25519_key *	public_key,
		byte *	out,
		word32 *	outlen
	)

This function computes a shared secret key given a secret private key and a received public key. It stores the generated secret key in the buffer out and assigns the variable of the secret key to outlen. Only supports big endian.

Returns

0 Returned on successfully computing a shared secret key

BAD_FUNC_ARG Returned if any of the input parameters passed in are NULL

ECC_BAD_ARG_E Returned if the first bit of the public key is set, to avoid implementation fingerprinting

Parameters

private_key	pointer to the curve25519_key structure initialized with the user’s private key
public_key	pointer to the curve25519_key structure containing the received public key
out	pointer to a buffer in which to store the 32 byte computed secret key
outlen	pointer in which to store the length written to the output buffer

Example

byte sharedKey[32];
word32 keySz;
curve25519_key privKey, pubKey;
// initialize both keys

if ( wc_curve25519_shared_secret(&privKey, &pubKey, sharedKey,
&keySz) != 0 ) {
    // error generating shared key
}

See also

wc_curve25519_init

wc_curve25519_make_key

wc_curve25519_shared_secret_ex

wc_curve25519_shared_secret_ex()

WOLFSSL_API int wc_curve25519_shared_secret_ex	(	curve25519_key *	private_key,
		curve25519_key *	public_key,
		byte *	out,
		word32 *	outlen,
		int	endian
	)

This function computes a shared secret key given a secret private key and a received public key. It stores the generated secret key in the buffer out and assigns the variable of the secret key to outlen. Supports both big and little endian.

Returns

0 Returned on successfully computing a shared secret key

BAD_FUNC_ARG Returned if any of the input parameters passed in are NULL

ECC_BAD_ARG_E Returned if the first bit of the public key is set, to avoid implementation fingerprinting

Parameters

private_key	pointer to the curve25519_key structure initialized with the user’s private key
public_key	pointer to the curve25519_key structure containing the received public key
out	pointer to a buffer in which to store the 32 byte computed secret key
outlen	pointer in which to store the length written to the output buffer
endian	EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which form to use.

Example

byte sharedKey[32];
word32 keySz;

curve25519_key privKey, pubKey;
// initialize both keys

if ( wc_curve25519_shared_secret_ex(&privKey, &pubKey, sharedKey, &keySz,
EC25519_BIG_ENDIAN) != 0 ) {
    // error generating shared key
}

See also

wc_curve25519_init

wc_curve25519_make_key

wc_curve25519_shared_secret

wc_curve25519_size()

WOLFSSL_API int wc_curve25519_size

(

curve25519_key *

key

)

This function returns the key size of the given key structure.

Returns

Success Given a valid, initialized curve25519_key structure, returns the size of the key.

0 Returned if key is NULL

Parameters

key	pointer to the curve25519_key structure in for which to determine the key size

Example

curve25519_key key;
// initialize and make key
int keySz;
keySz = wc_curve25519_size(&key);

See also

wc_curve25519_init

wc_curve25519_make_key