Functions
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. More...
 
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. More...
 
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. More...
 
WOLFSSL_API int wc_ed25519_init (ed25519_key *key)
 This function initializes an ed25519_key object for future use with message verification. More...
 
WOLFSSL_API void wc_ed25519_free (ed25519_key *key)
 This function frees an ed25519 object after it has been used. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
WOLFSSL_API int wc_ed25519_export_private (ed25519_key *key, byte *out, word32 *outLen)
 Export the private key, including public part. More...
 
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. More...
 
WOLFSSL_API int wc_ed25519_size (ed25519_key *key)
 This function returns the key size of an ed25519_key structure, or 32 bytes. More...
 
WOLFSSL_API int wc_ed25519_priv_size (ed25519_key *key)
 Returns the private key size (secret + public) in bytes. More...
 
WOLFSSL_API int wc_ed25519_pub_size (ed25519_key *key)
 Returns the compressed key size in bytes (public key). More...
 
WOLFSSL_API int wc_ed25519_sig_size (ed25519_key *key)
 This function returns the size of an ed25519 signature (64 in bytes). More...
 

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
keyThe ed25519_key structure to export to.
privByte array to store private key.
privSzSize of priv buffer.
pubByte array to store public key.
pubSzSize of pub buffer.

Example

int ret;
// 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
keyed25519_key struct to export from.
outDestination for private key.
outLenMax length of output, set to the length of the exported private key.

Example

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
keypointer to an ed25519_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;
// 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 ,
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
keypointer to an ed25519_key structure from which to export the public key
outpointer to the buffer in which to store the public 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;
// 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
keypointer to the ed25519_key object to free

Example

// 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
privpointer to the buffer containing the private key
privSzsize of the private key
pubpointer to the buffer containing the public key
pubSzlength of the public key
keypointer 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 };
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
inpointer to the buffer containing the public key
inLenlength of the buffer containing the public key
keypointer 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
keypointer to the ed25519_key object to initialize

Example

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.

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
rngpointer to an initialized RNG object with which to generate the key
keysizelength of key to generate. Should always be 32 for ed25519
keypointer to the ed25519_key for which to generate a key

Example

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
keyThe ed25119_key struct

Example

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
keyPointer to the ed25519_key struct.

Example

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
keypointer to an ed25519_key structure for which to get the signature size

Example

int sigSz;
// 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
inpointer to the buffer containing the message to sign
inlenlength of the message 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 ed25519_key with which to generate the signature

Example

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
keypointer to an ed25519_key structure for which to get the key size

Example

int keySz;
// 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
sigpointer to the buffer containing the signature to verify
siglenlength of the signature to verify
msgpointer to the buffer containing the message to verify
msglenlength of the message to verify
statpointer to the result of the verification. 1 indicates the message was successfully verified
keypointer to a public ed25519 key with which to verify the signature

Example

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