Algorithms - ED25519

Functions
WOLFSSL_API int	wc_ed25519_make_key (WC_RNG *rng, int keysize, ed25519_key *key)
	This function generates a new ed25519_key and stores it in key.
WOLFSSL_API int	wc_ed25519_sign_msg (const byte *in, word32 inlen, byte *out, word32 *outlen, ed25519_key *key)
	This function signs a message digest using an ed25519_key object to guarantee authenticity.
WOLFSSL_API int	wc_ed25519_verify_msg (const byte *sig, word32 siglen, const byte *msg, word32 msglen, int *stat, ed25519_key *key)
	This function verifies the ed25519 signature of a message to ensure authenticity. It returns the answer through stat, with 1 corresponding to a valid signature, and 0 corresponding to an invalid signature.
WOLFSSL_API int	wc_ed25519_init (ed25519_key *key)
	This function initializes an ed25519_key object for future use with message verification.
WOLFSSL_API void	wc_ed25519_free (ed25519_key *key)
	This function frees an ed25519 object after it has been used.
WOLFSSL_API int	wc_ed25519_import_public (const byte *in, word32 inLen, ed25519_key *key)
	This function imports a public ed25519_key pair from a buffer containing the public key. This function will handle both compressed and uncompressed keys.
WOLFSSL_API int	wc_ed25519_import_private_key (const byte *priv, word32 privSz, const byte *pub, word32 pubSz, ed25519_key *key)
	This function imports a public/private ed25519 key pair from a pair of buffers. This function will handle both compressed and uncompressed keys.
WOLFSSL_API int	wc_ed25519_export_public (ed25519_key *, byte *out, word32 *outLen)
	This function exports the private key from an ed25519_key structure. It stores the public key in the buffer out, and sets the bytes written to this buffer in outLen.
WOLFSSL_API int	wc_ed25519_export_private_only (ed25519_key *key, byte *out, word32 *outLen)
	This function exports only the private key from an ed25519_key structure. It stores the private key in the buffer out, and sets the bytes written to this buffer in outLen.
WOLFSSL_API int	wc_ed25519_export_private (ed25519_key *key, byte *out, word32 *outLen)
	Export the private key, including public part.
WOLFSSL_API int	wc_ed25519_export_key (ed25519_key *key, byte *priv, word32 *privSz, byte *pub, word32 *pubSz)
	Export full private key and public key.
WOLFSSL_API int	wc_ed25519_size (ed25519_key *key)
	This function returns the key size of an ed25519_key structure, or 32 bytes.
WOLFSSL_API int	wc_ed25519_priv_size (ed25519_key *key)
	Returns the private key size (secret + public) in bytes.
WOLFSSL_API int	wc_ed25519_pub_size (ed25519_key *key)
	Returns the compressed key size in bytes (public key).
WOLFSSL_API int	wc_ed25519_sig_size (ed25519_key *key)
	This function returns the size of an ed25519 signature (64 in bytes).

Detailed Description

Function Documentation

wc_ed25519_export_key()

WOLFSSL_API int wc_ed25519_export_key	(	ed25519_key *	key,
		byte *	priv,
		word32 *	privSz,
		byte *	pub,
		word32 *	pubSz )

Export full private key and public key.

Returns

0 Success

BAD_FUNC_ARG: Returns if any argument is null.

BUFFER_E: Returns if outLen is less than ED25519_PRV_KEY_SIZE or ED25519_PUB_KEY_SIZE

Parameters

key	The ed25519_key structure to export to.
priv	Byte array to store private key.
privSz	Size of priv buffer.
pub	Byte array to store public key.
pubSz	Size of pub buffer.

Example

int ret;
ed25519_key key;
// initialize key, make key
 
char pub[32];
word32 pubSz = sizeof(pub);
char priv[32];
word32 privSz = sizeof(priv);
 
ret = wc_ed25519_export_key(&key, priv, &pubSz, pub, &pubSz);
if ( ret != 0) {
    // error exporting public key
}

See also

wc_ed25519_export_private

wc_ed25519_export_public

wc_ed25519_export_private()

WOLFSSL_API int wc_ed25519_export_private	(	ed25519_key *	key,
		byte *	out,
		word32 *	outLen )

Export the private key, including public part.

Returns

0 Success

BAD_FUNC_ARG Returns if any argument is null.

BUFFER_E Returns if outLen is less than ED25519_PRV_KEY_SIZE

Parameters

key	ed25519_key struct to export from.
out	Destination for private key.
outLen	Max length of output, set to the length of the exported private key.

Example

ed25519_key key;
wc_ed25519_init(&key);
 
WC_RNG rng;
wc_InitRng(&rng);
 
wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key
 
byte out[32]; // out needs to be a sufficient buffer size
word32 outLen = sizeof(out);
int key_size = wc_ed25519_export_private(&key, out, &outLen);
if(key_size == BUFFER_E)
{
    // Check size of out compared to outLen to see if function reset outLen
}

See also

none

wc_ed25519_export_private_only()

WOLFSSL_API int wc_ed25519_export_private_only	(	ed25519_key *	key,
		byte *	out,
		word32 *	outLen )

This function exports only the private key from an ed25519_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

BUFFER_E Returned if the buffer provided is not large enough to store the private key

Parameters

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

Example

int ret;
ed25519_key key;
// initialize key, make key
 
char priv[32]; // 32 bytes because only private key
word32 privSz = sizeof(priv);
ret = wc_ed25519_export_private_only(&key, priv, &privSz);
if ( ret != 0) {
    // error exporting private key
}

See also

wc_ed25519_export_public

wc_ed25519_import_private_key

wc_ed25519_export_public()

WOLFSSL_API int wc_ed25519_export_public	(	ed25519_key *	key,
		byte *	out,
		word32 *	outLen )

This function exports the private key from an ed25519_key structure. It stores the public key in the buffer out, and sets the bytes written to this buffer in outLen.

Returns

0 Returned upon successfully exporting the public key

BAD_FUNC_ARG Returned if any of the input values evaluate to NULL

BUFFER_E Returned if the buffer provided is not large enough to store the private key. Upon returning this error, the function sets the size required in outLen

Parameters

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

Example

int ret;
ed25519_key key;
// initialize key, make key
 
char pub[32];
word32 pubSz = sizeof(pub);
 
ret = wc_ed25519_export_public(&key, pub, &pubSz);
if ( ret != 0) {
    // error exporting public key
}

See also

wc_ed25519_import_public_key

wc_ed25519_export_private_only

wc_ed25519_free()

WOLFSSL_API void wc_ed25519_free

(

ed25519_key *

key

)

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

Returns

none No returns.

Parameters

key	pointer to the ed25519_key object to free

Example

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

See also

wc_ed25519_init

wc_ed25519_import_private_key()

WOLFSSL_API int wc_ed25519_import_private_key	(	const byte *	priv,
		word32	privSz,
		const byte *	pub,
		word32	pubSz,
		ed25519_key *	key )

This function imports a public/private ed25519 key pair from a pair of buffers. This function will handle both compressed and uncompressed keys.

Returns

0 Returned on successfully importing the ed25519_key

BAD_FUNC_ARG Returned if in or key evaluate to NULL, or if either privSz or pubSz are less than the size of an ed25519 key

Parameters

priv	pointer to the buffer containing the private key
privSz	size of the private key
pub	pointer to the buffer containing the public key
pubSz	length of the public key
key	pointer to the ed25519_key object in which to store the imported private/public key pair

Example

int ret;
byte priv[] = { // initialize with 32 byte private key };
byte pub[]  = { // initialize with the corresponding public key };
 
ed25519_key key;
wc_ed25519_init_key(&key);
ret = wc_ed25519_import_private_key(priv, sizeof(priv), pub,
sizeof(pub), &key);
if ( ret != 0) {
    // error importing key
}

See also

wc_ed25519_import_public_key

wc_ed25519_export_private_only

wc_ed25519_import_public()

WOLFSSL_API int wc_ed25519_import_public	(	const byte *	in,
		word32	inLen,
		ed25519_key *	key )

This function imports a public ed25519_key pair from a buffer containing the public key. This function will handle both compressed and uncompressed keys.

Returns

0 Returned on successfully importing the ed25519_key

BAD_FUNC_ARG Returned if in or key evaluate to NULL, or inLen is less than the size of an ed25519 key

Parameters

in	pointer to the buffer containing the public key
inLen	length of the buffer containing the public key
key	pointer to the ed25519_key object in which to store the public key

Example

int ret;
byte pub[] = { // initialize ed25519 public key };
 
ed_25519 key;
wc_ed25519_init_key(&key);
ret = wc_ed25519_import_public(pub, sizeof(pub), &key);
if ( ret != 0) {
    // error importing key
}

See also

wc_ed25519_import_private_key

wc_ed25519_export_public

wc_ed25519_init()

WOLFSSL_API int wc_ed25519_init

(

ed25519_key *

key

)

This function initializes an ed25519_key object for future use with message verification.

Returns

0 Returned upon successfully initializing the ed25519_key object

BAD_FUNC_ARG Returned if key is NULL

Parameters

key	pointer to the ed25519_key object to initialize

Example

ed25519_key key;
wc_ed25519_init(&key);

See also

wc_ed25519_make_key

wc_ed25519_free

wc_ed25519_make_key()

WOLFSSL_API int wc_ed25519_make_key	(	WC_RNG *	rng,
		int	keysize,
		ed25519_key *	key )

This function generates a new ed25519_key and stores it in key.

Returns

0 Returned upon successfully making an ed25519_key

BAD_FUNC_ARG Returned if rng or key evaluate to NULL, or if the specified key size is not 32 bytes (ed25519 has 32 byte keys)

MEMORY_E Returned if there is an error allocating memory during function execution

Parameters

rng	pointer to an initialized RNG object with which to generate the key
keysize	length of key to generate. Should always be 32 for ed25519
key	pointer to the ed25519_key for which to generate a key

Example

ed25519_key key;
wc_ed25519_init(&key);
WC_RNG rng;
wc_InitRng(&rng);
wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key

See also

wc_ed25519_init

wc_ed25519_priv_size()

WOLFSSL_API int wc_ed25519_priv_size

(

ed25519_key *

key

)

Returns the private key size (secret + public) in bytes.

Returns

BAD_FUNC_ARG Returns if key argument is null.

ED25519_PRV_KEY_SIZE The size of the private key.

Parameters

key	The ed25119_key struct

Example

ed25519_key key;
wc_ed25519_init(&key);
 
WC_RNG rng;
wc_InitRng(&rng);
 
wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key
int key_size = wc_ed25519_priv_size(&key);

See also

wc_ed25119_pub_size

wc_ed25519_pub_size()

WOLFSSL_API int wc_ed25519_pub_size

(

ed25519_key *

key

)

Returns the compressed key size in bytes (public key).

Returns

BAD_FUNC_ARG returns if key is null.

ED25519_PUB_KEY_SIZE Size of key.

Parameters

key	Pointer to the ed25519_key struct.

Example

ed25519_key key;
wc_ed25519_init(&key);
WC_RNG rng;
wc_InitRng(&rng);
 
wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key
int key_size = wc_ed25519_pub_size(&key);

See also

wc_ed25519_priv_size

wc_ed25519_sig_size()

WOLFSSL_API int wc_ed25519_sig_size

(

ed25519_key *

key

)

This function returns the size of an ed25519 signature (64 in bytes).

Returns

Success Given a valid key, returns ED25519_SIG_SIZE (64 in bytes)

0 Returned if the given key is NULL

Parameters

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

Example

int sigSz;
ed25519_key key;
// initialize key, make key
 
sigSz = wc_ed25519_sig_size(&key);
if ( sigSz == 0) {
    // error determining sig size
}

See also

wc_ed25519_sign_msg

wc_ed25519_sign_msg()

WOLFSSL_API int wc_ed25519_sign_msg	(	const byte *	in,
		word32	inlen,
		byte *	out,
		word32 *	outlen,
		ed25519_key *	key )

This function signs a message digest using an ed25519_key object to guarantee authenticity.

Returns

0 Returned upon successfully generating a signature for the message digest

BAD_FUNC_ARG Returned any of the input parameters evaluate to NULL, or if the output buffer is too small to store the generated signature

MEMORY_E Returned if there is an error allocating memory during function execution

Parameters

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

Example

ed25519_key key;
WC_RNG rng;
int ret, sigSz;
 
byte sig[64]; // will hold generated signature
sigSz = sizeof(sig);
byte message[] = { // initialize with message };
 
wc_InitRng(&rng); // initialize rng
wc_ed25519_init(&key); // initialize key
wc_ed25519_make_key(&rng, 32, &key); // make public/private key pair
ret = wc_ed25519_sign_msg(message, sizeof(message), sig, &sigSz, &key);
if ( ret != 0 ) {
    // error generating message signature
}

See also

wc_ed25519_verify_msg

wc_ed25519_size()

WOLFSSL_API int wc_ed25519_size

(

ed25519_key *

key

)

This function returns the key size of an ed25519_key structure, or 32 bytes.

Returns

Success Given a valid key, returns ED25519_KEY_SIZE (32 bytes)

BAD_FUNC_ARGS Returned if the given key is NULL

Parameters

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

Example

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

See also

wc_ed25519_make_key

wc_ed25519_verify_msg()

WOLFSSL_API int wc_ed25519_verify_msg	(	const byte *	sig,
		word32	siglen,
		const byte *	msg,
		word32	msglen,
		int *	stat,
		ed25519_key *	key )

This function verifies the ed25519 signature of a message 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 if any of the input parameters evaluate to NULL, or if the siglen does not match the actual length of a signature

1 Returned if verification completes, but the signature generated does not match the signature provided

Parameters

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

Example

ed25519_key key;
int ret, verified = 0;
 
byte sig[] { // initialize with received signature };
byte msg[] = { // initialize with message };
// initialize key with received public key
ret = wc_ed25519_verify_msg(sig, sizeof(sig), msg, sizeof(msg),
&verified, &key);
 
if ( return < 0 ) {
    // error performing verification
} else if ( verified == 0  )
    // the signature is invalid
}

See also

wc_ed25519_sign_msg