WOLFSSL MANUAL: CHAPTER 18
Chapter 18: wolfCrypt API Reference
March, 2016
Version 3.9.0
Table of Contents
18.1 Initialization & Shutdown
18.20 Random Number Generation
18.1 Initialization & Shutdown
wolfCrypt_Init
Synopsis:
#include <wolfssl/wolfcrypt/wc_port.h>
int wolfCrypt_Init();
Description:
Used to initialize state for wolfcrypt.
Return Values:
0: wolfCrypt successfully initialized.
Parameters:
None
Example:
if (wolfCrypt_Init() != 0)
{
/* wolfCrypt Initialization Error */
}
See Also:
18.2 AES
wc_AesSetKey
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
int wc_AesSetKey(Aes* aes, const byte* key, word32 len, const byte* iv, int dir);
Description:
This function initializes an AES structure by setting the key and then setting the initialization vector.
Return Values:
0: On successfully setting key and initialization vector.
BAD_FUNC_ARG: Returned if key length is invalid.
Parameters:
aes - pointer to the AES structure to modify
key - 16, 24, or 32 byte secret key for encryption and decryption
len - length of the key passed in
iv – pointer to the initialization vector used to initialize the key
dir - Cipher direction. Set AES_ENCRYPTION to encrypt, or AES_DECRYPTION to decrypt. (See enum in wolfssl/wolfcrypt/aes.h)
Example:
Aes enc;
int ret = 0;
byte key[] = { /* some 16, 24 or 32 byte key */ };
byte iv[] = { /* some 16 byte iv */ };
if (ret = wc_AesSetKey(&enc, key, AES_BLOCK_SIZE, iv, AES_ENCRYPTION) != 0) {
// failed to set aes key
}
See Also:
wc_AesSetKeyDirect, wc_AesSetIV
wc_AesSetIV
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
int wc_AesSetIV(Aes* aes, const byte* iv);
Description:
This function sets the initialization vector for a particular AES object. The AES object should be initialized before calling this function.
Return Values:
0: On successfully setting initialization vector.
BAD_FUNC_ARG: Returned if AES pointer is NULL.
Parameters:
aes - pointer to the AES structure on which to set the initialization vector
iv - initialization vector used to initialize the AES structure. If the value is NULL, the default action initializes the iv to 0.
Example:
Aes enc;
// set enc key
byte iv[] = { /* some 16 byte iv */ };
if (ret = wc_AesSetIV(&enc, iv) != 0) {
// failed to set aes iv
}
See Also:
wc_AesSetKeyDirect, wc_AesSetKey
wc_AesCbcEncrypt
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
int wc_AesCbcEncrypt(Aes* aes, byte* out, const byte* in, word32 sz)
Description:
Encrypts a plaintext message from the input buffer in, and places the resulting cipher text in the output buffer out using cipher block chaining with AES. This function requires that the AES object has been initialized by calling AesSetKey before a message is able to be encrypted.
This function assumes that the input message is AES block length aligned. PKCS#7 style padding should be added beforehand. This differs from the OpenSSL AES-CBC methods which add the padding for you.
To make the wolfSSL function and equivalent OpenSSL functions interoperate, one should specify the -nopad option in the OpenSSL command line function so that it behaves like the wolfSSL AesCbcEncrypt method and does not add extra padding during encryption.
Return Values:
0: On successfully encrypting message.
BAD_ALIGN_E: Returned on block align error
Parameters:
aes - pointer to the AES object used to encrypt data
out - pointer to the output buffer in which to store the ciphertext of the encrypted message
in - pointer to the input buffer containing message to be encrypted
sz - size of input message
Example:
Aes enc;
int ret = 0;
// initialize enc with AesSetKey, using direction AES_ENCRYPTION
byte msg[AES_BLOCK_SIZE * n]; // multiple of 16 bytes
// fill msg with data
byte cipher[AES_BLOCK_SIZE * n]; // Some multiple of 16 bytes
if ((ret = wc_AesCbcEncrypt(&enc, cipher, message, sizeof(msg))) != 0 ) {
// block align error
}
See Also:
wc_AesSetKey, wc_AesSetIV, wc_AesCbcDecrypt
wc_AesCbcDecrypt
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
int wc_AesCbcDecrypt(Aes* aes, byte* out, const byte* in, word32 sz);
Description:
Decrypts a cipher from the input buffer in, and places the resulting plain text in the output buffer out using cipher block chaining with AES. This function requires that the AES structure has been initialized by calling AesSetKey before a message is able to be decrypted.
This function assumes that the original message was AES block length aligned. This differs from the OpenSSL AES-CBC methods which do not require alignment as it adds PKCS#7 padding automatically.
To make the wolfSSL function and equivalent OpenSSL functions interoperate, one should specify the -nopad option in the OpenSSL command line function so that it behaves like the wolfSSL AesCbcEncrypt method and does not create errors during decryption.
Return Values:
0: On successfully decrypting message.
BAD_ALIGN_E: Returned on block align error
Parameters:
aes - pointer to the AES object used to decrypt data
out - pointer to the output buffer in which to store the plain text of the decrypted message
in - pointer to the input buffer containing cipher text to be decrypted
sz - size of input message
Example:
Aes dec;
int ret = 0;
// initialize dec with AesSetKey, using direction AES_DECRYPTION
byte cipher[AES_BLOCK_SIZE * n]; // some multiple of 16 bytes
// fill cipher with cipher text
byte plain [AES_BLOCK_SIZE * n];
if ((ret = wc_AesCbcDecrypt(&dec, plain, cipher, sizeof(cipher))) != 0 ) {
// block align error
}
See Also:
wc_AesSetKey, wc_AesCbcEncrypt
wc_AesCbcDecryptWithKey
Synopsis:
#include <wolfssl/wolfcrypt/wc_encrypt.h>
int wc_AesCbcDecryptWithKey(byte* out, const byte* in, word32 inSz, const byte* key, word32 keySz, const byte* iv);
Description:
Decrypts a cipher from the input buffer in, and places the resulting plain text in the output buffer out using cipher block chaining with AES. This function does not require an AES structure to be initialized. Instead, it takes in a key and an iv (initialization vector) and uses these to initialize an AES object and then decrypt the cipher text.
Return Values:
0: On successfully decrypting message
BAD_ALIGN_E: Returned on block align error
BAD_FUNC_ARG: Returned if key length is invalid or AES object is null during AesSetIV
MEMORY_E: Returned if WOLFSSL_SMALL_STACK is enabled and XMALLOC fails to instantiate an AES object.
Parameters:
out - pointer to the output buffer in which to store the plain text of the decrypted message
in - pointer to the input buffer containing cipher text to be decrypted
inSz - size of input message
key - 16, 24, or 32 byte secret key for decryption
keySz - size of key used for decryption
Example:
int ret = 0;
byte key[] = { /* some 16, 24, or 32 byte key */ };
byte iv[] = { /* some 16 byte iv */ };
byte cipher[AES_BLOCK_SIZE * n]; //n being a positive integer making cipher some multiple of 16 bytes
// fill cipher with cipher text
byte plain [AES_BLOCK_SIZE * n];
if ((ret = wc_AesCbcDecryptWithKey(plain, cipher, AES_BLOCK_SIZE, key, AES_BLOCK_SIZE, iv)) != 0 ) {
// Decrypt Error
}
See Also:
wc_AesSetKey, wc_AesSetIV, wc_AesCbcEncrypt, wc_AesCbcDecrypt
wc_AesCtrEncrypt
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
void wc_AesCtrEncrypt(Aes* aes, byte* out, const byte* in, word32 sz);
Description:
Encrypts/Decrypts a message from the input buffer in, and places the resulting cipher text in the output buffer out using CTR mode with AES. This function is only enabled if WOLFSSL_AES_COUNTER is enabled at compile time. The AES structure should be initialized through AesSetKey before calling this function. Note that this function is used for both decryption and encryption.
Return Values:
No return value for this function.
Parameters:
aes - pointer to the AES object used to decrypt data
out - pointer to the output buffer in which to store the cipher text of the encrypted message
in - pointer to the input buffer containing plain text to be encrypted
sz - size of the input plain text
NOTE: Regarding using same API for encryption and decryption.
User should differentiate between Aes structures for encrypt/decrypt.
Example:
Aes enc;
Aes dec;
/* initialize enc and dec with AesSetKeyDirect, using direction AES_ENCRYPTION
* since the underlying API only calls Encrypt and by default calling encrypt on
* a cipher results in a decryption of the cipher
*/
byte msg[AES_BLOCK_SIZE * n]; //n being a positive integer making msg some multiple of 16 bytes
// fill plain with message text
byte cipher[AES_BLOCK_SIZE * n];
byte decrypted[AES_BLOCK_SIZE * n];
wc_AesCtrEncrypt(&enc, cipher, msg, sizeof(msg)); // encrypt plain
wc_AesCtrEncrypt(&dec, decrypted, cipher, sizeof(cipher)); // decrypt cipher text
See Also:
wc_AesSetKey
wc_AesEncryptDirect
Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
void wc_AesEncryptDirect(Aes* aes, byte* out, const byte* in)
Description:
This function is a one-block encrypt of the input block, in, into the output block, out. It uses the key and iv (initialization vector) of the provided AES structure, which should be initialized with wc_AesSetKey before calling this function. It is only enabled if the configure option WOLFSSL_AES_DIRECT is enabled.
Return Values:
No return value for this function.
Parameters:
aes - pointer to the AES object used to encrypt data
out - pointer to the output buffer in which to store the cipher text of the encrypted message
in - pointer to the input buffer containing plain text to be encrypted
Example:
Aes enc;
// initialize enc with AesSetKey, using direction AES_ENCRYPTION
byte msg [AES_BLOCK_SIZE]; // 16 bytes
// initialize msg with plain text to encrypt
byte cipher[AES_BLOCK_SIZE];
wc_AesEncryptDirect(&enc, cipher, msg);
See Also:
wc_AesDecryptDirect, wc_AesSetKeyDirect
wc_AesDecryptDirect
Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
void wc_AesDecryptDirect(Aes* aes, byte* out, const byte* in);
Description:
This function is a one-block decrypt of the input block, in, into the output block, out. It uses the key and iv (initialization vector) of the provided AES structure, which should be initialized with wc_AesSetKey before calling this function. It is only enabled if the configure option WOLFSSL_AES_DIRECT is enabled, and there is support for direct AES encryption on the system in question.
Return Values:
No return value for this function.
Parameters:
aes - pointer to the AES object used to encrypt data
out - pointer to the output buffer in which to store the plain text of the decrypted cipher text
in - pointer to the input buffer containing cipher text to be decrypted
Example:
Aes dec;
// initialize enc with AesSetKey, using direction AES_DECRYPTION
byte cipher [AES_BLOCK_SIZE]; // 16 bytes
// initialize cipher with cipher text to decrypt
byte msg[AES_BLOCK_SIZE];
wc_AesDecryptDirect(&dec, msg, cipher);
See Also:
wc_AesEncryptDirect, wc_AesSetKeyDirect
wc_AesSetKeyDirect
Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
int wc_AesSetKeyDirect(Aes* aes, const byte* key, word32 len, const byte* iv, int dir);
Description:
This function is used to set the AES keys for CTR mode with AES. It initializes an AES object with the given key, iv (initialization vector), and encryption dir (direction). It is only enabled if the configure option WOLFSSL_AES_DIRECT is enabled. Currently wc_AesSetKeyDirect uses wc_AesSetKey internally.
Return Values:
0: On successfully setting the key.
BAD_FUNC_ARG: Returned if the given key is an invalid length
Parameters:
aes - pointer to the AES object used to encrypt data
key - 16, 24, or 32 byte secret key for encryption and decryption
len - length of the key passed in
iv - initialization vector used to initialize the key
dir - Cipher direction. Set AES_ENCRYPTION to encrypt, or AES_DECRYPTION to decrypt. (See enum in wolfssl/wolfcrypt/aes.h) (NOTE: If using wc_AesSetKeyDirect with Aes Counter mode (Stream cipher) only use AES_ENCRYPTION for both encrypting and decrypting)
Example:
Aes enc;
int ret = 0;
byte key[] = { /* some 16, 24, or 32 byte key */ };
byte iv[] = { /* some 16 byte iv */ };
if (ret = wc_AesSetKeyDirect(&enc, key, sizeof(key), iv, AES_ENCRYPTION) != 0) {
// failed to set aes key
}
See Also:
wc_AesEncryptDirect, wc_AesDecryptDirect, wc_AesSetKey
wc_AesGcmSetKey
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
int wc_AesGcmSetKey(Aes* aes, const byte* key, word32 len);
Description:
This function is used to set the key for AES GCM (Galois/Counter Mode). It initializes an AES object with the given key. It is only enabled if the configure option HAVE_AESGCM is enabled at compile time.
Return Values:
0: On successfully setting the key.
BAD_FUNC_ARG: Returned if the given key is an invalid length.
Parameters:
aes - pointer to the AES object used to encrypt data
key - 16, 24, or 32 byte secret key for encryption and decryption
len - length of the key passed in
Example:
Aes enc;
int ret = 0;
byte key[] = { /* some 16, 24,32 byte key */ };
if (ret = wc_AesGcmSetKey(&enc, key, sizeof(key)) != 0) {
// failed to set aes key
}
See Also:
wc_AesGcmEncrypt, wc_AesGcmDecrypt
wc_AesGcmEncrypt
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
int wc_AesGcmEncrypt(Aes* aes, byte* out, const byte* in, word32 sz, const byte* iv,
word32 ivSz, byte* authTag, word32 authTagSz, const byte* authIn,
word32 authInSz);
Description:
This function encrypts the input message, held in the buffer in, and stores the resulting cipher text in the output buffer out. It requires a new iv (initialization vector) for each call to encrypt. It also encodes the input authentication vector, authIn, into the authentication tag, authTag.
Return Values:
0: On successfully encrypting the input message
Parameters:
aes - pointer to the AES object used to encrypt data
out - pointer to the output buffer in which to store the cipher text
in - pointer to the input buffer holding the message to encrypt
sz - length of the input message to decrypt
iv - pointer to the buffer containing the initialization vector
ivSz - length of the initialization vector
authTag - pointer to the buffer in which to store the authentication tag
authTagSz - length of the desired authentication tag
authIn - pointer to the buffer containing the input authentication vector
authInSz - length of the input authentication vector
Example:
Aes enc;
// initialize aes structure by calling wc_AesGcmSetKey
byte plain[AES_BLOCK_LENGTH * n]; //n being a positive integer making plain some multiple of 16 bytes
// initialize plain with msg to encrypt
byte cipher[sizeof(plain)];
byte iv[] = // some 16 byte iv
byte authTag[AUTH_TAG_LENGTH];
byte authIn[] = // Authentication Vector
wc_AesGcmEncrypt(&enc, cipher, plain, sizeof(cipher), iv, sizeof(iv),
authTag, sizeof(authTag), authIn, sizeof(authIn));
See Also:
wc_AesGcmSetKey, wc_AesGcmDecrypt
wc_AesGcmDecrypt
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
int wc_AesGcmDecrypt(Aes* aes, byte* out, const byte* in, word32 sz, const byte* iv,
word32 ivSz, const byte* authTag, word32 authTagSz, const byte* authIn, word32 authInSz);
Description:
This function decrypts the input cipher text, held in the buffer in, and stores the resulting message text in the output buffer out. It also checks the input authentication vector, authIn, against the supplied authentication tag, authTag.
Return Values:
0: On successfully decrypting the input message
AES_GCM_AUTH_E: If the authentication tag does not match the supplied authentication code vector, authTag.
Parameters:
aes - pointer to the AES object used to encrypt data
out - pointer to the output buffer in which to store the message text
in - pointer to the input buffer holding the cipher text to decrypt
sz - length of the cipher text to decrypt
iv - pointer to the buffer containing the initialization vector
ivSz - length of the initialization vector
authTag - pointer to the buffer containing the authentication tag
authTagSz - length of the desired authentication tag
authIn - pointer to the buffer containing the input authentication vector
authInSz - length of the input authentication vector
Example:
Aes enc; /* can use the same struct as was passed to wc_AesGcmEncrypt */
// initialize aes structure by calling wc_AesGcmSetKey if not already done
byte cipher[AES_BLOCK_LENGTH * n]; //n being a positive integer making cipher some multiple of 16 bytes
// initialize cipher with cipher text to decrypt
byte output[sizeof(cipher)];
byte iv[] = // some 16 byte iv
byte authTag[AUTH_TAG_LENGTH];
byte authIn[] = // Authentication Vector
wc_AesGcmDecrypt(&enc, output, cipher, sizeof(cipher), iv, sizeof(iv),
authTag, sizeof(authTag), authIn, sizeof(authIn));
See Also:
wc_AesGcmSetKey, wc_AesGcmEncrypt
wc_GmacSetKey
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
int wc_GmacSetKey(Gmac* gmac, const byte* key, word32 len);
Description:
This function initializes and sets the key for a GMAC object to be used for Galois Message Authentication.
Return Values:
0: On successfully setting the key
BAD_FUNC_ARG: Returned if key length is invalid.
Parameters:
gmac - pointer to the gmac object used for authentication
key - 16, 24, or 32 byte secret key for authentication
len - length of the key
Example:
Gmac gmac;
key[] = { /* some 16, 24, or 32 byte length key */ };
wc_GmacSetKey(&gmac, key, sizeof(key));
See Also:
wc_GmacUpdate
wc_GmacUpdate
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
int wc_GmacUpdate(Gmac* gmac, const byte* iv, word32 ivSz, const byte* authIn,
word32 authInSz, byte* authTag, word32 authTagSz)
Description:
This function generates the Gmac hash of the authIn input and stores the result in the authTag buffer. After running wc_GmacUpdate, one should compare the generated authTag to a known authentication tag to verify the authenticity of a message.
Return Values:
0: On successfully computing the Gmac hash.
Parameters:
gmac - pointer to the gmac object used for authentication
iv - initialization vector used for the hash
ivSz - size of the initialization vector used
authIn - pointer to the buffer containing the authentication vector to verify
authInSz - size of the authentication vector
authTag - pointer to the output buffer in which to store the Gmac hash
authTagSz - the size of the output buffer used to store the Gmac hash
Example:
Gmac gmac;
key[] = { /* some 16, 24, or 32 byte length key */ };
iv[] = { /* some 16 byte length iv */ };
wc_GmacSetKey(&gmac, key, sizeof(key));
authIn[] = { /* some 16 byte authentication input */ };
tag[AES_BLOCK_SIZE]; // will store authentication code
wc_GmacUpdate(&gmac, iv, sizeof(iv), authIn, sizeof(authIn), tag, sizeof(tag));
See Also:
wc_GmacSetKey
wc_AesCcmSetKey
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
void wc_AesCcmSetKey(Aes* aes, const byte* key, word32 keySz);
Description:
This function sets the key for an AES object using CCM (Counter with CBC-MAC). It takes a pointer to an AES structure and initializes it with supplied key.
Return Values:
No return value for this function.
Parameters:
aes - aes structure in which to store the supplied key
key - 16, 24, or 32 byte secret key for encryption and decryption
keySz - size of the supplied key
Example:
Aes enc;
key[] = { /* some 16, 24, or 32 byte length key */ };
wc_AesCcmSetKey(&aes, key, sizeof(key));
See Also:
wc_AesCcmEncrypt, wc_AesCcmDecrypt
wc_AesCcmEncrypt
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
void wc_AesCcmEncrypt(Aes* aes, byte* out, const byte* in, word32 inSz, const byte* nonce, word32 nonceSz, byte* authTag, word32 authTagSz, byte* authIn,
word32 authInSz);
Description:
This function encrypts the input message, in, into the output buffer, out, using CCM (Counter with CBC-MAC). It subsequently calculates and stores the authorization tag, authTag, from the authIn input.
Return Values:
No return value for this function.
Parameters:
aes - pointer to the AES object used to encrypt data
out - pointer to the output buffer in which to store the cipher text
in - pointer to the input buffer holding the message to encrypt
sz - length of the input message to encrypt
nonce - pointer to the buffer containing the nonce (number only used once)
nonceSz - length of the nonce
authTag - pointer to the buffer in which to store the authentication tag
authTagSz - length of the desired authentication tag
authIn - pointer to the buffer containing the input authentication vector
authInSz - length of the input authentication vector
Example:
Aes enc;
// initialize enc with wc_AesCcmSetKey
nonce[] = { /* initialize nonce */ };
plain[] = { /* some plain text message */ };
cipher[sizeof(plain)];
authIn[] = { /* some 16 byte authentication input */ };
tag[AES_BLOCK_SIZE]; // will store authentication code
wc_AesCcmEncrypt(&enc, cipher, plain, sizeof(plain), nonce, sizeof(nonce),
tag, sizeof(tag), authIn, sizeof(authIn));
See Also:
wc_AesCcmSetKey, wc_AesCcmDecrypt
wc_AesCcmDecrypt
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
int wc_AesCcmDecrypt(Aes* aes, byte* out, const byte* in, word32 inSz, const byte* nonce, word32 nonceSz, const byte* authTag, word32 authTagSz,
const byte* authIn, word32 authInSz)
Description:
This function decrypts the input cipher text, in, into the output buffer, out, using CCM (Counter with CBC-MAC). It subsequently calculates the authorization tag, authTag, from the authIn input. If the authorization tag is invalid, it sets the output buffer to zero and returns the error: AES_CCM_AUTH_E.
Return Values:
0: On successfully decrypting the input message
AES_CCM_AUTH_E: If the authentication tag does not match the supplied authentication code vector, authTag.
Parameters:
aes - pointer to the AES object used to encrypt data
out - pointer to the output buffer in which to store the cipher text
in - pointer to the input buffer holding the message to encrypt
sz - length of the input cipher text to decrypt
nonce - pointer to the buffer containing the nonce (number only used once)
nonceSz - length of the nonce
authTag - pointer to the buffer in which to store the authentication tag
authTagSz - length of the desired authentication tag
authIn - pointer to the buffer containing the input authentication vector
authInSz - length of the input authentication vector
Example:
Aes dec;
// initialize dec with wc_AesCcmSetKey
nonce[] = { /* initialize nonce */ };
cipher[] = { /* encrypted message */ };
plain[sizeof(cipher)];
authIn[] = { /* some 16 byte authentication input */ };
tag[AES_BLOCK_SIZE] = { /* authentication tag received for verification */ };
int return = wc_AesCcmDecrypt(&dec, plain, cipher, sizeof(cipher), nonce, sizeof(nonce),tag, sizeof(tag), authIn, sizeof(authIn));
if(return != 0) {
// decrypt error, invalid authentication code
}
See Also:
wc_AesCcmSetKey, wc_AesCcmEncrypt
wc_AesInitCavium
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
int wc_AesInitCavium(Aes* aes, int devId)
Description:
This function initializes AES for use with Cavium Nitrox devices. It should be called before wc_AesSetKey when using Cavium hardware cryptography.
Return Values:
0: On successfully initializing cavium.
-1: Returned if the AES structure is NULL, or the call to CspAllocContext fails.
Parameters:
aes - pointer to the AES object used to encrypt data
devId - Nitrox device id
Example:
Aes enc;
wc_AesInitCavium(&aes, CAVIUM_DEV_ID);
See Also:
wc_AesFreeCavium
wc_AesFreeCavium
Synopsis:
#include <wolfssl/wolfcrypt/aes.h>
void wc_AesFreeCavium(Aes* aes)
Description:
This function frees the AES structure used with Cavium Nitrox devices.
Return Values:
No return value for this function.
Parameters:
aes - pointer to the AES structure to free
Example:
Aes enc;
... // initialize Cavium, perform encryption
wc_AesFreeCavium(&aes);
See Also:
wc_AesInit_Cavium
18.3 Arc4
wc_Arc4SetKey
Synopsis:
#include <wolfssl/wolfcrypt/arc4.h>
void wc_Arc4SetKey(Arc4* arc4, const byte* key, word32 length)
Description:
This function sets the key for a ARC4 object, initializing it for use as a cipher. It should be called before using it for encryption with wc_Arc4Process.
Return Values:
No return value for this function.
Parameters:
arc4 - pointer to an arc4 structure to be used for encryption
key - key with which to initialize the arc4 structure
length - length of the key used to initialize the arc4 structure
Example:
Arc4 enc;
byte key[] = { /* initialize with key to use for encryption */ };
wc_Arc4SetKey(&enc, key, sizeof(key));
See Also:
wc_Arc4Process
wc_Arc4Process
Synopsis:
#include <wolfssl/wolfcrypt/arc4.h>
void wc_Arc4Process(Arc4* arc4, byte* out, const byte* in, word32 length)
Description:
This function encrypts an input message from the buffer in, placing the ciphertext in the output buffer out, or decrypts a ciphertext from the buffer in, placing the plaintext in the output buffer out, using ARC4 encryption. This function is used for both encryption and decryption. Before this method may be called, one must first initialize the ARC4 structure using wc_Arc4SetKey.
Return Values:
No return value for this function.
Parameters:
arc4 - pointer to the ARC4 structure used to process the message
out - pointer to the output buffer in which to store the processed message
in - pointer to the input buffer containing the message to process
length - length of the message to process
Example:
Arc4 enc;
byte key[] = { /* key to use for encryption */ };
wc_Arc4SetKey(&enc, key, sizeof(key));
byte plain[] = { /* plain text to encode */ };
byte cipher[sizeof(plain)];
byte decrypted[sizeof(plain)];
wc_Arc4Process(&enc, cipher, plain, sizeof(plain)); // encrypt the plain into cipher
wc_Arc4Process(&enc, decrypted, cipher, sizeof(cipher)); // decrypt the cipher
See Also:
wc_Arc4SetKey
wc_Arc4InitCavium
Synopsis:
#include <wolfssl/wolfcrypt/arc4.h>
int wc_Arc4InitCavium(Arc4* arc4, int devId)
Description:
This function initializes ARC4 for use with Cavium Nitrox devices. It should be called before wc_Arc4SetKey when using Cavium hardware cryptography.
Return Values:
0: Returned on successfully initializing cavium
-1: Returned if the arc4 structure is NULL or the call to CspAllocContext fails.
Parameters:
arc4 - pointer to the ARC4 structure to initialize
devId - the id of the device to initialize with cavium
Example:
Arc4 enc;
if(wc_Arc4InitCavium(&aes, CAVIUM_DEV_ID)) != 0) {
// error initializing Cavium with ARC4
}
See Also:
wc_Arc4FreeCavium
wc_Arc4FreeCavium
Synopsis:
#include <wolfssl/wolfcrypt/arc4.h>
void wc_Arc4FreeCavium(Arc4* arc4)
Description:
This function frees the ARC4 structure used with Cavium Nitrox devices. It should be called after encryption is completed when using Cavium hardware cryptography, as the last step to free the ARC4 structure.
Return Values:
0: Returned on successfully freeing cavium
-1: Returned if the arc4 structure is NULL or the arc4 structure passed in is not Cavium enabled
Parameters:
arc4 - pointer to the ARC4 structure to free
Example:
Arc4 enc;
if(wc_Arc4InitCavium(&aes, CAVIUM_DEV_ID)) != 0) {
// error initializing Cavium with ARC4
}
See Also:
wc_Arc4InitCavium
18.4 ASN
wolfSSL_PemCertToDer
Synopsis:
#include <wolfssl/wolfcrypt/asn.h>
int wolfSSL_PemCertToDer(const char* fileName, unsigned char* derBuf, int derSz);
Description:
This function converts a pem certificate to a der certificate, and places the resulting certificate in the derBuf buffer provided.
Return Values:
On success, returns the size of the derBuf generated
BUFFER_E: Returned if the size of derBuf is too small to hold the certificate generated
MEMORY_E: Returned if the call to XMALLOC fails
Parameters:
fileName - path to the file containing a pem certificate to convert to a der certificate
derBuf - pointer to a char buffer in which to store the converted certificate
derSz - size of the char buffer in which to store the converted certificate
Example:
char * file = “./certs/client-cert.pem”;
int derSz;
byte * der = (byte*)XMALLOC(EIGHTK_BUF, NULL, DYNAMIC_TYPE_CERT);
derSz = wolfsSSL_PemCertToDer(file, der, EIGHTK_BUF);
if(derSz <= 0) {
//PemCertToDer error
}
wc_InitCert
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
void wc_InitCert(Cert* cert)
Description:
This function initializes a default cert, with the default options:
version = 3 (0x2)
serial = 0
sigType = SHA_WITH_RSA
issuer = blank
daysValid = 500
selfSigned = 1 (true) use subject as issuer
subject = blank
Return Values:
No return value for this function.
Parameters:
cert - pointer to an uninitialized cert structure to initialize
Example:
Cert myCert;
wc_InitCert(&myCert);
See Also:
wc_MakeCert, wc_MakeCertReq
wc_MakeCert
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_MakeCert(Cert* cert, byte* derBuffer, word32 derSz, RsaKey* rsaKey,
ecc_key* eccKey, RNG* rng);
Description:
Used to make CA signed certs. Called after the subject information has been entered. This function makes an x509 Certificate v3 RSA or ECC from a cert input. It then writes this cert to derBuffer. It takes in either an rsaKey or an eccKey to generate the certificate. The certificate must be initialized with wc_InitCert before this method is called.
Return Values:
On successfully making an x509 certificate from the specified input cert, returns the size of the cert generated.
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
BUFFER_E: Returned if the provided derBuffer is too small to store the generated certificate
Others:
Additional error messages may be returned if the cert generation is not successful.
Parameters:
cert - pointer to an initialized cert structure
derBuffer - pointer to the buffer in which to hold the generated cert
derSz - size of the buffer in which to store the cert
rsaKey - pointer to an RsaKey structure containing the rsa key used to generate the certificate
eccKey - pointer to an EccKey structure containing the ecc key used to generate the certificate
rng - pointer to the random number generator used to make the cert
Example:
Cert myCert;
wc_InitCert(&myCert);
RNG rng;
//initialize rng;
RsaKey key;
//initialize key;
byte * derCert = malloc(FOURK_BUF);
word32 certSz;
certSz = wc_MakeCert(&myCert, derCert, FOURK_BUF, &key, NULL, &rng);
See Also:
wc_InitCert, wc_MakeCertReq
wc_MakeCertReq
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_MakeCertReq(Cert* cert, byte* derBuffer, word32 derSz, RsaKey* rsaKey,
ecc_key* eccKey)
Description:
This function makes a certificate signing request using the input certificate and writes the output to derBuffer. It takes in either an rsaKey or an eccKey to generate the certificate request. wc_SignCert() will need to be called after this function to sign the certificate request. Please see the wolfCrypt test application (./wolfcrypt/test/test.c) for an example usage of this function.
Return Values:
On successfully making an X.509 certificate request from the specified input cert, returns the size of the certificate request generated.
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
BUFFER_E: Returned if the provided derBuffer is too small to store the generated certificate
Others:
Additional error messages may be returned if the certificate request generation is not successful.
Parameters:
cert - pointer to an initialized cert structure
derBuffer - pointer to the buffer in which to hold the generated certificate request
derSz - size of the buffer in which to store the certificate request
rsaKey - pointer to an RsaKey structure containing the rsa key used to generate the certificate request
eccKey - pointer to an EccKey structure containing the ecc key used to generate the certificate request
Example:
Cert myCert;
// initialize myCert
EccKey key;
//initialize key;
byte* derCert = (byte*)malloc(FOURK_BUF);
word32 certSz;
certSz = wc_MakeCertReq(&myCert, derCert, FOURK_BUF, NULL, &key);
See Also:
wc_InitCert, wc_MakeCert
wc_SignCert
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_SignCert(int requestSz, int sType, byte* buffer, word32 buffSz,
RsaKey* rsaKey, ecc_key* eccKey, RNG* rng)
Description:
This function signs buffer and adds the signature to the end of buffer. It takes in a signature type. Must be called after wc_MakeCert() or wc_MakeCertReq() if creating a CA signed cert.
Return Values:
On successfully signing the certificate, returns the new size of the cert (including signature).
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
BUFFER_E: Returned if the provided buffer is too small to store the generated certificate
Others:
Additional error messages may be returned if the cert generation is not successful.
Parameters:
requestSz - the size of the certificate body we’re requesting to have signed
sType - Type of signature to create. Valid options are: CTC_MD5wRSA, CTC_SHAwRSA, CTC_SHAwECDSA, CTC_SHA256wECDSA, andCTC_SHA256wRSA
buffer - pointer to the buffer containing the certificate to be signed. On success: will hold the newly signed certificate
buffSz - the (total) size of the buffer in which to store the newly signed certificate
rsaKey - pointer to an RsaKey structure containing the rsa key to used to sign the certificate
eccKey - pointer to an EccKey structure containing the ecc key to used to sign the certificate
rng - pointer to the random number generator used to sign the certificate
Example:
Cert myCert;
byte* derCert = (byte*)malloc(FOURK_BUF);
// initialize myCert, derCert
RsaKey key;
// initialize key;
RNG rng;
// initialize rng
word32 certSz;
certSz = wc_SignCert(myCert.bodySz, myCert.sigType,derCert,FOURK_BUF, &key, NULL,
&rng);
See Also:
wc_InitCert, wc_MakeCert
wc_MakeSelfCert
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_MakeSelfCert(Cert* cert, byte* buffer, word32 buffSz, RsaKey* key, RNG* rng)
Description:
This function is a combination of the previous two functions, wc_MakeCert and wc_SignCert for self signing (the previous functions may be used for CA requests). It makes a certificate, and then signs it, generating a self-signed certificate.
Return Values:
On successfully signing the certificate, returns the new size of the cert.
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
BUFFER_E: Returned if the provided buffer is too small to store the generated certificate
Others:
Additional error messages may be returned if the cert generation is not successful.
Parameters:
cert - pointer to the cert to make and sign
buffer - pointer to the buffer in which to hold the signed certificate
buffSz - size of the buffer in which to store the signed certificate
key - pointer to an RsaKey structure containing the rsa key to used to sign the certificate
rng - pointer to the random number generator used to generate and sign the certificate
Example:
Cert myCert;
byte* derCert = (byte*)malloc(FOURK_BUF);
// initialize myCert, derCert
RsaKey key;
// initialize key;
RNG rng;
// initialize rng
word32 certSz;
certSz = wc_MakeSelfCert(&myCert, derCert, FOURK_BUF, &key, NULL, &rng);
See Also:
wc_InitCert, wc_MakeCert, wc_SignCert
wc_SetIssuer
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_SetIssuer(Cert* cert, const char* issuerFile)
Description:
This function sets the issuer for a certificate to the issuer in the provided pem issuerFile. It also changes the certificate’s self-signed attribute to false. The issuer specified in issuerFile is verified prior to setting the cert issuer. This method is used to set fields prior to signing.
Return Values:
0: Returned on successfully setting the issuer for the certificate
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
ASN_PARSE_E: Returned if there is an error parsing the cert header file
ASN_OBJECT_ID_E: Returned if there is an error parsing the encryption type from the cert
ASN_EXPECT_0_E: Returned if there is a formatting error in the encryption specification of the cert file
ASN_BEFORE_DATE_E: Returned if the date is before the certificate start date
ASN_AFTER_DATE_E: Returned if the date is after the certificate expiration date
ASN_BITSTR_E: Returned if there is an error parsing a bit string from the certificate
ASN_NTRU_KEY_E: Returned if there is an error parsing the NTRU key from the certificate
ECC_CURVE_OID_E: Returned if there is an error parsing the ECC key from the certificate
ASN_UNKNOWN_OID_E: Returned if the certificate is using an unknown key object id
ASN_VERSION_E: Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate
BAD_FUNC_ARG: Returned if there is an error processing the certificate extension
ASN_CRIT_EXT_E: Returned if an unfamiliar critical extension is encountered in processing the certificate
ASN_SIG_OID_E: Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file
ASN_SIG_CONFIRM_E: Returned if confirming the certification signature fails
ASN_NAME_INVALID_E: Returned if the certificate’s name is not permitted by the CA name constraints
ASN_NO_SIGNER_E: Returned if there is no CA signer to verify the certificate’s authenticity
Parameters:
cert - pointer to the cert for which to set the issuer
issuerFile - path of the file containing the pem formatted certificate
Example:
Cert myCert;
// initialize myCert
if(wc_SetIssuer(&myCert, ”./path/to/ca-cert.pem”) != 0) {
// error setting issuer
}
See Also:
wc_InitCert, wc_SetSubject, wc_SetIssuerBuffer
wc_SetSubject
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_SetSubject(Cert* cert, const char* subjectFile)
Description:
This function sets the subject for a certificate to the subject in the provided pem subjectFile. This method is used to set fields prior to signing.
Return Values:
0: Returned on successfully setting the issuer for the certificate
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
ASN_PARSE_E: Returned if there is an error parsing the cert header file
ASN_OBJECT_ID_E: Returned if there is an error parsing the encryption type from the cert
ASN_EXPECT_0_E: Returned if there is a formatting error in the encryption specification of the cert file
ASN_BEFORE_DATE_E: Returned if the date is before the certificate start date
ASN_AFTER_DATE_E: Returned if the date is after the certificate expiration date
ASN_BITSTR_E: Returned if there is an error parsing a bit string from the certificate
ASN_NTRU_KEY_E: Returned if there is an error parsing the NTRU key from the certificate
ECC_CURVE_OID_E: Returned if there is an error parsing the ECC key from the certificate
ASN_UNKNOWN_OID_E: Returned if the certificate is using an unknown key object id
ASN_VERSION_E: Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate
BAD_FUNC_ARG: Returned if there is an error processing the certificate extension
ASN_CRIT_EXT_E: Returned if an unfamiliar critical extension is encountered in processing the certificate
ASN_SIG_OID_E: Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file
ASN_SIG_CONFIRM_E: Returned if confirming the certification signature fails
ASN_NAME_INVALID_E: Returned if the certificate’s name is not permitted by the CA name constraints
ASN_NO_SIGNER_E: Returned if there is no CA signer to verify the certificate’s authenticity
Parameters:
cert - pointer to the cert for which to set the issuer
subjectFile - path of the file containing the pem formatted certificate
Example:
Cert myCert;
// initialize myCert
if(wc_SetSubject(&myCert, ”./path/to/ca-cert.pem”) != 0) {
// error setting subject
}
See Also:
wc_InitCert, wc_SetIssuer
wc_SetAltNames
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_SetAltNames(Cert* cert, const char* file)
Description:
This function sets the alternate names for a certificate to the alternate names in the provided pem file. This is useful in the case that one wishes to secure multiple domains with the same certificate. This method is used to set fields prior to signing.
Return Values:
0: Returned on successfully setting the alt names for the certificate
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
ASN_PARSE_E: Returned if there is an error parsing the cert header file
ASN_OBJECT_ID_E: Returned if there is an error parsing the encryption type from the cert
ASN_EXPECT_0_E: Returned if there is a formatting error in the encryption specification of the cert file
ASN_BEFORE_DATE_E: Returned if the date is before the certificate start date
ASN_AFTER_DATE_E: Returned if the date is after the certificate expiration date
ASN_BITSTR_E: Returned if there is an error parsing a bit string from the certificate
ASN_NTRU_KEY_E: Returned if there is an error parsing the NTRU key from the certificate
ECC_CURVE_OID_E: Returned if there is an error parsing the ECC key from the certificate
ASN_UNKNOWN_OID_E: Returned if the certificate is using an unknown key object id
ASN_VERSION_E: Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate
BAD_FUNC_ARG: Returned if there is an error processing the certificate extension
ASN_CRIT_EXT_E: Returned if an unfamiliar critical extension is encountered in processing the certificate
ASN_SIG_OID_E: Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file
ASN_SIG_CONFIRM_E: Returned if confirming the certification signature fails
ASN_NAME_INVALID_E: Returned if the certificate’s name is not permitted by the CA name constraints
ASN_NO_SIGNER_E: Returned if there is no CA signer to verify the certificate’s authenticity
Parameters:
cert - pointer to the cert for which to set the alt names
file - path of the file containing the pem formatted certificate
Example:
Cert myCert;
// initialize myCert
if(wc_SetSubject(&myCert, ”./path/to/ca-cert.pem”) != 0) {
// error setting alt names
}
See Also:
wc_InitCert, wc_SetIssuer
wc_SetIssuerBuffer
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_SetIssuerBuffer(Cert* cert, const byte* der, int derSz);
Description:
This function sets the issuer for a certificate from the issuer in the provided der buffer. It also changes the certificate’s self-signed attribute to false. This method is used to set fields prior to signing.
Return Values:
0: Returned on successfully setting the issuer for the certificate
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
ASN_PARSE_E: Returned if there is an error parsing the cert header file
ASN_OBJECT_ID_E: Returned if there is an error parsing the encryption type from the cert
ASN_EXPECT_0_E: Returned if there is a formatting error in the encryption specification of the cert file
ASN_BEFORE_DATE_E: Returned if the date is before the certificate start date
ASN_AFTER_DATE_E: Returned if the date is after the certificate expiration date
ASN_BITSTR_E: Returned if there is an error parsing a bit string from the certificate
ASN_NTRU_KEY_E: Returned if there is an error parsing the NTRU key from the certificate
ECC_CURVE_OID_E: Returned if there is an error parsing the ECC key from the certificate
ASN_UNKNOWN_OID_E: Returned if the certificate is using an unknown key object id
ASN_VERSION_E: Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate
BAD_FUNC_ARG: Returned if there is an error processing the certificate extension
ASN_CRIT_EXT_E: Returned if an unfamiliar critical extension is encountered in processing the certificate
ASN_SIG_OID_E: Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file
ASN_SIG_CONFIRM_E: Returned if confirming the certification signature fails
ASN_NAME_INVALID_E: Returned if the certificate’s name is not permitted by the CA name constraints
ASN_NO_SIGNER_E: Returned if there is no CA signer to verify the certificate’s authenticity
Parameters:
cert - pointer to the cert for which to set the issuer
der - pointer to the buffer containing the der formatted certificate from which to grab the issuer
derSz - size of the buffer containing the der formatted certificate from which to grab the issuer
Example:
Cert myCert;
// initialize myCert
byte* der;
der = (byte*)malloc(FOURK_BUF);
// initialize der
if(wc_SetIssuerBuffer(&myCert, der, FOURK_BUF) != 0) {
// error setting issuer
}
See Also:
wc_InitCert, wc_SetIssuer
wc_SetSubjectBuffer
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_SetSubjectBuffer(Cert* cert, const byte* der, int derSz);
Description:
This function sets the subject for a certificate from the subject in the provided der buffer. This method is used to set fields prior to signing.
Return Values:
0: Returned on successfully setting the subject for the certificate
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
ASN_PARSE_E: Returned if there is an error parsing the cert header file
ASN_OBJECT_ID_E: Returned if there is an error parsing the encryption type from the cert
ASN_EXPECT_0_E: Returned if there is a formatting error in the encryption specification of the cert file
ASN_BEFORE_DATE_E: Returned if the date is before the certificate start date
ASN_AFTER_DATE_E: Returned if the date is after the certificate expiration date
ASN_BITSTR_E: Returned if there is an error parsing a bit string from the certificate
ASN_NTRU_KEY_E: Returned if there is an error parsing the NTRU key from the certificate
ECC_CURVE_OID_E: Returned if there is an error parsing the ECC key from the certificate
ASN_UNKNOWN_OID_E: Returned if the certificate is using an unknown key object id
ASN_VERSION_E: Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate
BAD_FUNC_ARG: Returned if there is an error processing the certificate extension
ASN_CRIT_EXT_E: Returned if an unfamiliar critical extension is encountered in processing the certificate
ASN_SIG_OID_E: Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file
ASN_SIG_CONFIRM_E: Returned if confirming the certification signature fails
ASN_NAME_INVALID_E: Returned if the certificate’s name is not permitted by the CA name constraints
ASN_NO_SIGNER_E: Returned if there is no CA signer to verify the certificate’s authenticity
Parameters:
cert - pointer to the cert for which to set the subject
der - pointer to the buffer containing the der formatted certificate from which to grab the subject
derSz - size of the buffer containing the der formatted certificate from which to grab the subject
Example:
Cert myCert;
// initialize myCert
byte* der;
der = (byte*)malloc(FOURK_BUF);
// initialize der
if(wc_SetSubjectBuffer(&myCert, der, FOURK_BUF) != 0) {
// error setting subject
}
See Also:
wc_InitCert, wc_SetSubject
wc_SetAltNamesBuffer
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_SetAltNamesBuffer(Cert* cert, const byte* der, int derSz)
Description:
This function sets the alternate names for a certificate from the alternate names in the provided der buffer. This is useful in the case that one wishes to secure multiple domains with the same certificate. This method is used to set fields prior to signing.
Return Values:
0: Returned on successfully setting the alternate names for the certificate
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
ASN_PARSE_E: Returned if there is an error parsing the cert header file
ASN_OBJECT_ID_E: Returned if there is an error parsing the encryption type from the cert
ASN_EXPECT_0_E: Returned if there is a formatting error in the encryption specification of the cert file
ASN_BEFORE_DATE_E: Returned if the date is before the certificate start date
ASN_AFTER_DATE_E: Returned if the date is after the certificate expiration date
ASN_BITSTR_E: Returned if there is an error parsing a bit string from the certificate
ASN_NTRU_KEY_E: Returned if there is an error parsing the NTRU key from the certificate
ECC_CURVE_OID_E: Returned if there is an error parsing the ECC key from the certificate
ASN_UNKNOWN_OID_E: Returned if the certificate is using an unknown key object id
ASN_VERSION_E: Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate
BAD_FUNC_ARG: Returned if there is an error processing the certificate extension
ASN_CRIT_EXT_E: Returned if an unfamiliar critical extension is encountered in processing the certificate
ASN_SIG_OID_E: Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file
ASN_SIG_CONFIRM_E: Returned if confirming the certification signature fails
ASN_NAME_INVALID_E: Returned if the certificate’s name is not permitted by the CA name constraints
ASN_NO_SIGNER_E: Returned if there is no CA signer to verify the certificate’s authenticity
Parameters:
cert - pointer to the cert for which to set the alternate names
der - pointer to the buffer containing the der formatted certificate from which to grab the alternate names
derSz - size of the buffer containing the der formatted certificate from which to grab the alternate names
Example:
Cert myCert;
// initialize myCert
byte* der;
der = (byte*)malloc(FOURK_BUF);
// initialize der
if(wc_SetAltNamesBuffer(&myCert, der, FOURK_BUF) != 0) {
// error setting subject
}
See Also:
wc_InitCert, wc_SetAltNames
wc_SetDatesBuffer
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_SetDatesBuffer(Cert* cert, const byte* der, int derSz)
Description:
This function sets the dates for a certificate from the date range in the provided der buffer. This method is used to set fields prior to signing.
Return Values:
0: Returned on successfully setting the dates for the certificate
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
ASN_PARSE_E: Returned if there is an error parsing the cert header file
ASN_OBJECT_ID_E: Returned if there is an error parsing the encryption type from the cert
ASN_EXPECT_0_E: Returned if there is a formatting error in the encryption specification of the cert file
ASN_BEFORE_DATE_E: Returned if the date is before the certificate start date
ASN_AFTER_DATE_E: Returned if the date is after the certificate expiration date
ASN_BITSTR_E: Returned if there is an error parsing a bit string from the certificate
ASN_NTRU_KEY_E: Returned if there is an error parsing the NTRU key from the certificate
ECC_CURVE_OID_E: Returned if there is an error parsing the ECC key from the certificate
ASN_UNKNOWN_OID_E: Returned if the certificate is using an unknown key object id
ASN_VERSION_E: Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate
BAD_FUNC_ARG: Returned if there is an error processing the certificate extension
ASN_CRIT_EXT_E: Returned if an unfamiliar critical extension is encountered in processing the certificate
ASN_SIG_OID_E: Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file
ASN_SIG_CONFIRM_E: Returned if confirming the certification signature fails
ASN_NAME_INVALID_E: Returned if the certificate’s name is not permitted by the CA name constraints
ASN_NO_SIGNER_E: Returned if there is no CA signer to verify the certificate’s authenticity
Parameters:
cert - pointer to the cert for which to set the dates
der - pointer to the buffer containing the der formatted certificate from which to grab the date range
derSz - size of the buffer containing the der formatted certificate from which to grab the date range
Example:
Cert myCert;
// initialize myCert
byte* der;
der = (byte*)malloc(FOURK_BUF);
// initialize der
if(wc_SetDatesBuffer(&myCert, der, FOURK_BUF) != 0) {
// error setting subject
}
See Also:
wc_InitCert
wc_MakeNtruCert
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_MakeNtruCert(Cert* cert, byte* derBuffer, word32 derSz, const byte* ntruKey,
word16 keySz, RNG* rng)
Description:
Used to make CA signed certs. Called after the subject information has been entered. This function makes an NTRU Certificate from a cert input. It then writes this cert to derBuffer. It takes in an ntruKey and a rng to generate the certificate. The certificate must be initialized with wc_InitCert before this method is called.
Return Values:
On successfully making a NTRU certificate from the specified input cert, returns the size of the cert generated.
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
BUFFER_E: Returned if the provided derBuffer is too small to store the generated certificate
Others:
Additional error messages may be returned if the cert generation is not successful.
Parameters:
cert - pointer to an initialized cert structure
derBuffer - pointer to the buffer in which to store the generated certificate
derSz - size of the buffer in which to store the generated certificate
ntruKey - pointer to the key to be used to generate the NTRU certificate
keySz - size of the key used to generate the NTRU certificate
rng - pointer to the random number generator used to generate the NTRU certificate
Example:
Cert myCert;
// initialize myCert
RNG rng;
//initialize rng;
byte ntruPublicKey[NTRU_KEY_SIZE];
//initialize ntruPublicKey;
byte * derCert = malloc(FOURK_BUF);
word32 certSz;
certSz = wc_MakeNtruCert(&myCert, derCert, FOURK_BUF, &ntruPublicKey, NTRU_KEY_SIZE, &rng);
See Also:
wc_InitCert, wc_MakeCert
wc_DerToPem
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_DerToPem(const byte* der, word32 derSz, byte* output, word32 outSz, int type)
Description:
This function converts a der formatted input certificate, contained in the der buffer, into a pem formatted output certificate, contained in the output buffer. It should be noted that this is not an in place conversion, and a separate buffer must be utilized to store the pem formatted output.
Return Values:
On successfully making a pem certificate from the input der cert, returns the size of the pem cert generated.
BAD_FUNC_ARG: Returned if there is an error parsing the der file and storing it as a pem file
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
ASN_INPUT_E: Returned in the case of a base 64 encoding error
BUFFER_E: May be returned if the output buffer is too small to store the pem formatted certificate
Parameters:
der - pointer to the buffer of the certificate to convert
derSz - size of the the certificate to convert
output - pointer to the buffer in which to store the pem formatted certificate
outSz - size of the buffer in which to store the pem formatted certificate
type - the type of certificate to generate. Valid types are: CERT_TYPE, PRIVATEKEY_TYPE, ECC_PRIVATEKEY_TYPE, and CERTREQ_TYPE.
Example:
byte* der;
// initialize der with certificate
byte* pemFormatted[FOURK_BUF];
word32 pemSz;
pemSz = wc_DerToPem(der, derSz,pemFormatted,FOURK_BUF, CERT_TYPE);
See Also:
wolfSSL_PemCertToDer
wc_DerToPemEx
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_DerToPemEx(const byte* der, word32 derSz, byte* output, word32 outSz,
byte *cipher_info, int type)
Description:
This function converts a der formatted input certificate, contained in the der buffer, into a pem formatted output certificate, contained in the output buffer. It should be noted that this is not an in place conversion, and a separate buffer must be utilized to store the pem formatted output. Allows setting cipher info.
Return Values:
On successfully making a pem certificate from the input der cert, returns the size of the pem cert generated.
BAD_FUNC_ARG: Returned if there is an error parsing the der file and storing it as a pem file
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
ASN_INPUT_E: Returned in the case of a base 64 encoding error
BUFFER_E: May be returned if the output buffer is too small to store the pem formatted certificate
Parameters:
der - pointer to the buffer of the certificate to convert
derSz - size of the the certificate to convert
output - pointer to the buffer in which to store the pem formatted certificate
outSz - size of the buffer in which to store the pem formatted certificate
cipher_info - Additional cipher information.
type - the type of certificate to generate. Valid types are: CERT_TYPE, PRIVATEKEY_TYPE, ECC_PRIVATEKEY_TYPE, and CERTREQ_TYPE.
Example:
byte* der;
// initialize der with certificate
byte* pemFormatted[FOURK_BUF];
word32 pemSz;
byte* cipher_info[] { /* Additional cipher info. */ }
pemSz = wc_DerToPemEx(der, derSz,pemFormatted,FOURK_BUF, ,CERT_TYPE);
See Also:
wolfSSL_PemCertToDer
wc_EccPrivateKeyDecode
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_EccPrivateKeyDecode(const byte* input, word32* inOutIdx, ecc_key* key,
word32 inSz);
Description:
This function reads in an ECC private key from the input buffer, input, parses the private key, and uses it to generate an ecc_key object, which it stores in key.
Return Values:
0: On successfully decoding the private key and storing the result in the ecc_key struct
ASN_PARSE_E: Returned if there is an error parsing the der file and storing it as a pem file
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
BUFFER_E: Returned if the certificate to convert is large than the specified max certificate size
ASN_OBJECT_ID_E: Returned if the certificate encoding has an invalid object id
ECC_CURVE_OID_E: Returned if the ECC curve of the provided key is not supported
ECC_BAD_ARG_E: Returned if there is an error in the ECC key format
NOT_COMPILED_IN: Returned if the private key is compressed, and no compression key is provided
MP_MEM: Returned if there is an error in the math library used while parsing the private key
MP_VAL: Returned if there is an error in the math library used while parsing the private key
MP_RANGE:Returned if there is an error in the math library used while parsing the private key
Parameters:
input - pointer to the buffer containing the input private key
inOutIdx - pointer to a word32 object containing the index in the buffer at which to start
key - pointer to an initialized ecc object, on which to store the decoded private key
inSz - size of the input buffer containing the private key
Example:
int ret, idx=0;
ecc_key key; // to store key in
byte* tmp; // tmp buffer to read key from
tmp = (byte*) malloc(FOURK_BUF);
int inSz;
inSz = fread(tmp, 1, FOURK_BUF, privateKeyFile);
// read key into tmp buffer
wc_ecc_init(&key); // initialize key
ret = wc_Ecc_PrivateKeyDecode(tmp, &idx, &key, (word32)inSz);
if(ret < 0) {
// error decoding ecc key
}
See Also:
wc_RSA_PrivateKeyDecode
wc_EccKeyToDer
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_EccKeyToDer(ecc_key* key, byte* output, word32 inLen);
Description:
This function writes a private ECC key to der format.
Return Values:
On successfully writing the ECC key to der format, returns the length written to the buffer
BAD_FUNC_ARG: Returned if key or output is null, or inLen equals zero
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
BUFFER_E: Returned if the converted certificate is too large to store in the output buffer
ASN_UNKNOWN_OID_E: Returned if the ECC key used is of an unknown type
MP_MEM: Returned if there is an error in the math library used while parsing the private key
MP_VAL: Returned if there is an error in the math library used while parsing the private key
MP_RANGE:Returned if there is an error in the math library used while parsing the private key
Parameters:
key - pointer to the buffer containing the input ecc key
output - pointer to a buffer in which to store the der formatted key
inLen - the length of the buffer in which to store the der formatted key
Example:
int derSz;
ecc_key key;
// initialize and make key
byte der[FOURK_BUF];
// store der formatted key here
derSz = wc_EccKeyToDer(&key, der, FOURK_BUF);
if(derSz < 0) {
// error converting ecc key to der buffer
}
See Also:
wc_RsaKeyToDer
wc_EccPublicKeyToDer
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_EccPublicKeyToDer(ecc_key* key, byte* output, word32 inLen,
int with_AlgCurve)
Description:
This function converts the ECC public key to DER format. It returns the size of buffer used. The public ECC key in DER format is stored in output buffer. with_AlgCurve is a flag for when to include a header that has the Algorithm and Curve information.
Return Values:
> 0: Success, size of buffer used
BAD_FUNC_ARG: Returned if output or key is null.
LENGTH_ONLY_E: Error in getting ECC public key size.
BUFFER_E: Returned when output buffer is too small.
Parameters:
key - Pointer to ECC key
output - Pointer to output buffer to write to.
inLen - Size of buffer.
with_AlgCurve - a flag for when to include a header that has the Algorithm and Curve information.
Example:
ecc_key key;
wc_ecc_init(&key);
WC_RNG rng;
wc_InitRng(&rng);
wc_ecc_make_key(&rng, 24, &key);
int derSz = /* Some appropriate size for der */;
byte der[derSz];
if(wc_EccPublicKeyToDer(&key, der, derSz, 1) < 0)
{
/* Error converting ECC public key to der */
}
See Also:
wc_EccKeyToDer, wc_EccPrivateKeyDecode
wc_EncodeSignature
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
word32 wc_EncodeSignature(byte* out, const byte* digest, word32 digSz, int hashOID)
Description:
This function encodes a digital signature into the output buffer, and returns the size of the encoded signature created.
Return Values:
On successfully writing the encoded signature to output, returns the length written to the buffer
Parameters:
out - pointer to the buffer where the encoded signature will be written
digest - pointer to the digest to use to encode the signature
digSz - the length of the buffer containing the digest
hashOID - OID identifying the hash type used to generate the signature. Valid options, depending on build configurations, are: SHAh, SHA256h, SHA384h, SHA512h, MD2h, MD5h, DESb, DES3b, CTC_MD5wRSA, CTC_SHAwRSA, CTC_SHA256wRSA, CTC_SHA384wRSA, CTC_SHA512wRSA, CTC_SHAwECDSA, CTC_SHA256wECDSA, CTC_SHA384wECDSA, and CTC_SHA512wECDSA.
Example:
int signSz;
byte encodedSig[MAX_ENCODED_SIG_SZ];
Sha256 sha256;
// initialize sha256 for hashing
byte* dig = = (byte*)malloc(SHA256_DIGEST_SIZE);
/* perform hashing and hash updating so dig stores SHA-256 hash
(see wc_InitSha256, wc_Sha256Update and wc_Sha256Final)*/
signSz = wc_EncodeSignature(encodedSig, dig, SHA256_DIGEST_SIZE,SHA256h);
wc_GetCTC_HashOID
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_GetCTC_HashOID(int type);
Description:
This function returns the hash OID that corresponds to a hashing type. For example, when given the type: SHA512, this function returns the identifier corresponding to a SHA512 hash, SHA512h.
Return Values:
On success, returns the OID corresponding to the appropriate hash to use with that encryption type.
0: Returned if an unrecognized hash type is passed in as argument.
Parameters:
type - the hash type for which to find the OID. Valid options, depending on build configuration, include: MD2, MD5, SHA, SHA256, SHA512, SHA384, and SHA512.
Example:
int hashOID;
hashOID = wc_GetCTC_HashOID(SHA512);
if (hashOID == 0) {
// WOLFSSL_SHA512 not defined
}
wc_SetSubjectKeyId
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_SetSubjectKeyId(Cert *cert, const char* file);
Description:
Set SKID from public key file in PEM format. Both arguments are required.
Return Values:
0: Success
BAD_FUNC_ARG: Returns if cert or file is null.
MEMORY_E: Returns if there is a problem allocating memory for key.
PUBLIC_KEY_E: Returns if there is an error decoding the public key.
Parameters:
cert - Cert structure to set the SKID of.
file - Contains the PEM encoded file.
Example:
const char* file_name = "path/to/file";
Cert some_cert;
wc_InitCert(&some_cert);
if(wc_SetSubjectKeyId(&some_cert, file_name) != 0)
{
/* Handle Error */
}
See Also:
wc_SetSubjectKeyIdFromNtruPublicKey, wc_SetSubjectKeyIdFromPublicKey
wc_SetSubjectKeyIdFromNtruPublicKey
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_SetSubjectKeyIdFromNtruPublicKey(Cert *cert,
byte *ntruKey, word16 ntruKeySz);
Description:
Set SKID from NTRU public key.
Return Values:
0: Success
BAD_FUNC_ARG: Returned if cert or ntruKey is null.
MEMORY_E: Returned if there is an error allocating memory.
PUBLIC_KEY_E: Returned if there is an error getting the public key.
Parameters:
cert - Pointer to a Cert structure to be used.
ntruKey - Pointer to the NTRU public key in a byte array.
ntruKeySz - Size of the NTRU byte array.
Example:
Cert some_cert;
wc_InitCert(&some_cert);
byte some_ntru_key[] = { /* Load an NTRU key */ };
word32 ntru_size = sizeof(some_ntru_key);
if(wc_SetSubjectKeyIdFromNtruPublicKey(&some_cert,
some_ntru_key, ntru_size) != 0)
{
/* Handle error */
}
See Also:
SetKeyIdFromPublicKey
wc_SetSubjectKeyIdFromPublicKey
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_SetSubjectKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey, ecc_key *eckey);
Description:
Set SKID from RSA or ECC public key.
Return Values:
0: Success
BAD_FUNC_ARG: Returned if cert or rsakey and eckey is null.
MEMORY_E: Returned if there is an error allocating memory.
PUBLIC_KEY_E: Returned if there is an error getting the public key.
Parameters:
cert - Pointer to a Cert structure to be used.
rsakey - Pointer to an RsaKey structure
eckey - Pointer to an ecc_key structure
Example:
Cert some_cert;
RsaKey some_key;
wc_InitCert(&some_cert);
wc_InitRsaKey(&some_key);
if(wc_SetSubjectKeyIdFromPublicKey(&some_cert,&some_key, NULL) != 0)
{
/* Handle Error */
}
See Also:
wc_SetSubjectKeyId, wc_SetSubjectKeyIdFromNtruPublicKey
wc_SetAuthKeyIdFromPublicKey
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_SetAuthKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey, ecc_key *eckey)
Description:
Set AKID from either an RSA or ECC public key.
Return Values:
0: Success
BAD_FUNC_ARG: Either cert is null or both rsakey and eckey are null.
MEMORY_E: Error allocating memory.
PUBLIC_KEY_E: Error writing to the key.
Parameters:
cert - Pointer to the certificate to set the SKID.
rsakey - Pointer to the RsaKey struct to read from.
eckey - Pointer to the ecc_key to read from.
note: Only set one of rsakey or eckey, not both.
Example:
Cert myCert;
RsaKey keypub;
wc_InitRsaKey(&keypub, 0);
if (wc_SetAuthKeyIdFromPublicKey(&myCert, &keypub, NULL) != 0)
{
/* Handle error */
}
See Also:
wc_SetSubjectKeyId, wc_SetAuthKeyId, wc_SetAuthKeyIdFromCert
wc_SetAuthKeyId
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_SetAuthKeyId(Cert *cert, const char* file)
Description:
Set AKID from certificate file in PEM format.
Return Values:
0: Success
BAD_FUNC_ARG: Error if cert or file is null.
MEMORY_E: Error if problem allocating memory.
Parameters:
cert - Cert struct you want to set the AKID of.
file - Buffer containing PEM cert file.
Example:
char* file_name = "/path/to/file";
cert some_cert;
wc_InitCert(&some_cert);
if(wc_SetAuthKeyId(&some_cert, file_name) != 0)
{
/* Handle Error */
}
See Also:
wc_SetAuthKeyIdFromPublicKey, wc_SetAuthKeyIdFromCert
wc_SetAuthKeyIdFromCert
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_SetAuthKeyIdFromCert(Cert *cert, const byte *der, int derSz)
Description:
Set AKID from from DER encoded certificate.
Return Values:
0: Success
BAD_FUNC_ARG: Error if any argument is null or derSz is less than 0.
MEMORY_E: Error if problem allocating memory.
ASN_NO_SKID: No subject key ID found.
Parameters:
cert - The Cert struct to write to.
der - The DER encoded certificate buffer.
derSz - Size of der in bytes.
Example:
Cert some_cert;
byte some_der[] = { /* Initialize a DER buffer */ };
wc_InitCert(&some_cert);
if(wc_SetAuthKeyIdFromCert(&some_cert, some_der, sizeof(some_der) != 0)
{
/* Handle error */
}
See Also:
wc_SetAuthKeyIdFromPublicKey, wc_SetAuthKeyId
wc_EccPublicKeyDecode
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_EccPublicKeyDecode(const byte* input, word32* inOutIdx,
ecc_key* key, word32 inSz)
Description:
Decodes an ECC public key from an input buffer. It will parse an ASN sequence to retrieve the ECC key.
Return Values:
0: Success
BAD_FUNC_ARG: Returns if any arguments are null.
ASN_PARSE_E: Returns if there is an error parsing
ASN_ECC_KEY_E: Returns if there is an error importing the key. See wc_ecc_import_x963 for possible reasons.
Parameters:
input - Buffer containing DER encoded key to decode.
inOutIdx - Index to start reading input buffer from. On output, index is set to last position parsed of input buffer.
key - Pointer to ecc_key struct to store the public key.
inSz - Size of the input buffer.
Example:
int ret;
word32 idx = 0;
byte buff[] = { /* initialize with key */ };
ecc_key pubKey;
wc_ecc_init_key(&pubKey);
if ( wc_EccPublicKeyDecode(buff, &idx, &pubKey, sizeof(buff)) != 0) {
// error decoding key
}
See Also:
wc_ecc_import_x963
18.5 BLAKE2b
wc_InitBlake2b
Synopsis:
#include <wolfssl/wolfcrypt/blake2.h>
int wc_InitBlake2b(Blake2b* b2b, word32 digestSz);
Description:
This function initializes a Blake2b structure for use with the Blake2 hash function.
Return Values:
0: Returned upon successfully initializing the Blake2b structure and setting the digest size.
Parameters:
b2b: pointer to the Blake2b structure to initialize
digestSz: length of the blake 2 digest to implement
Example:
Blake2b b2b;
wc_InitBlake2b(&b2b, 64); // initialize Blake2b structure with 64 byte digest
See Also:
wc_Blake2bUpdate
wc_Blake2bUpdate
Synopsis:
#include <wolfssl/wolfcrypt/blake2.h>
int wc_Blake2bUpdate(Blake2b* b2b, const byte* data, word32 sz);
Description:
This function updates the Blake2b hash with the given input data. This function should be called after wc_InitBlake2b, and repeated until one is ready for the final hash: wc_Blake2bFinal.
Return Values:
0: Returned upon successfully update the Blake2b structure with the given data
-1: Returned if there is a failure while compressing the input data
Parameters:
b2b: pointer to the Blake2b structure to update
data: pointer to a buffer containing the data to append
sz: length of the input data to append
Example:
int ret;
Blake2b b2b;
wc_InitBlake2b(&b2b, 64); // initialize Blake2b structure with 64 byte digest
byte plain[] = { // initialize input };
ret = wc_Blake2bUpdate(&b2b, plain, sizeof(plain));
if( ret != 0) {
// error updating blake2b
}
See Also:
wc_InitBlake2b, wc_Blake2bFinal
wc_Blake2bFinal
Synopsis:
#include <olfssl/wolfcrypt/blake2.h>
int wc_Blake2bFinal(Blake2b* b2b, byte* final, word32 requestSz);
Description:
This function computes the Blake2b hash of the previously supplied input data. The output hash will be of length requestSz, or, if requestSz==0, the digestSz of the b2b structure. This function should be called after wc_InitBlake2b and wc_Blake2bUpdate has been processed for each piece of input data desired.
Return Values:
0: Returned upon successfully computing the Blake2b hash
-1: Returned if there is a failure while parsing the Blake2b hash
Parameters:
b2b: pointer to the Blake2b structure to update
final: pointer to a buffer in which to store the blake2b hash. Should be of length requestSz
requestSz: length of the digest to compute. When this is zero, b2b->digestSz will be used instead
Example:
int ret;
Blake2b b2b;
byte hash[64];
wc_InitBlake2b(&b2b, 64); // initialize Blake2b structure with 64 byte digest
... // call wc_Blake2bUpdate to add data to hash
ret = 2c_Blake2bFinal(&b2b, hash, 64);
if( ret != 0) {
// error generating blake2b hash
}
See Also:
wc_InitBlake2b, wc_Blake2bUpdate
18.6 Camellia
wc_CamelliaSetKey
Synopsis:
#include <wolfssl/wolfcrypt/camellia.h>
int wc_CamelliaSetKey(Camellia* cam, const byte* key, word32 len, const byte* iv);
Description:
This function sets the key and initialization vector for a camellia object, initializing it for use as a cipher.
Return Values:
0: Returned upon successfully setting the key and initialization vector
BAD_FUNC_ARG: returned if there is an error processing one of the input arguments
MEMORY_E: returned if there is an error allocating memory with XMALLOC
Parameters:
cam: pointer to the camellia structure on which to set the key and iv
key: pointer to the buffer containing the 16, 24, or 32 byte key to use for encryption and decryption
len: length of the key passed in
iv: pointer to the buffer containing the 16 byte initialization vector for use with this camellia structure
Example:
Camellia cam;
byte key[32];
// initialize key
byte iv[16];
// initialize iv
if( wc_CamelliaSetKey(&cam, key, sizeof(key), iv) != 0) {
// error initializing camellia structure
}
See Also:
wc_CamelliaEncryptDirect, wc_CamelliaDecryptDirect, wc_CamelliaCbcEncrypt, wc_CamelliaCbcDecrypt
wc_CamelliaSetIV
Synopsis:
#include <wolfssl/wolfcrypt/camellia.h>
int wc_CamelliaSetIV(Camellia* cam, const byte* iv);
Description:
This function sets the initialization vector for a camellia object.
Return Values:
0: Returned upon successfully setting the key and initialization vector
BAD_FUNC_ARG: returned if there is an error processing one of the input arguments
Parameters:
cam: pointer to the camellia structure on which to set the iv
iv: pointer to the buffer containing the 16 byte initialization vector for use with this camellia structure
Example:
Camellia cam;
byte iv[16];
// initialize iv
if( wc_CamelliaSetIV(&cam, iv) != 0) {
// error initializing camellia structure
}
See Also:
wc_CamelliaSetKey
wc_CamelliaEncryptDirect
Synopsis:
#include <wolfssl/wolfcrypt/camellia.h>
void wc_CamelliaEncryptDirect(Camellia* cam, byte* out, const byte* in);
Description:
This function does a one-block encrypt using the provided camellia object. It parses the first 16 byte block from the buffer in and stores the encrypted result in the buffer out. Before using this function, one should initialize the camellia object using wc_CamelliaSetKey.
Return Values:
No return value for this function.
Parameters:
cam: pointer to the camellia structure to use for encryption
out: pointer to the buffer in which to store the encrypted block
in: pointer to the buffer containing the plaintext block to encrypt
Example:
Camellia cam;
// initialize cam structure with key and iv
byte plain[] = { /* initialize with message to encrypt */ };
byte cipher[16];
wc_CamelliaEncrypt(&ca, cipher, plain);
See Also:
wc_CamelliaDecryptDirect
wc_CamelliaDecryptDirect
Synopsis:
#include <wolfssl/wolfcrypt/camellia.h>
void wc_CamelliaDecryptDirect(Camellia* cam, byte* out, const byte* in);
Description:
This function does a one-block decrypt using the provided camellia object. It parses the first 16 byte block from the buffer in, decrypts it, and stores the result in the buffer out. Before using this function, one should initialize the camellia object using wc_CamelliaSetKey.
Return Values:
No return value for this function.
Parameters:
cam: pointer to the camellia structure to use for encryption
out: pointer to the buffer in which to store the decrypted plaintext block
in: pointer to the buffer containing the ciphertext block to decrypt
Example:
Camellia cam;
// initialize cam structure with key and iv
byte cipher[] = { /* initialize with encrypted message to decrypt */ };
byte decrypted[16];
wc_CamelliaDecryptDirect(&cam, decrypted, cipher);
See Also:
wc_CamelliaEncryptDirect
wc_CamelliaCbcEncrypt
Synopsis:
#include <wolfssl/wolfcrypt/camellia.h>
void wc_CamelliaCbcEncrypt(Camellia* cam, byte* out, const byte* in, word32 sz);
Description:
This function encrypts the plaintext from the buffer in and stores the output in the buffer out. It performs this encryption using Camellia with Cipher Block Chaining (CBC).
Return Values:
No return value for this function.
Parameters:
cam: pointer to the camellia structure to use for encryption
out: pointer to the buffer in which to store the encrypted ciphertext
in: pointer to the buffer containing the plaintext to encrypt
sz: the size of the message to encrypt
Example:
Camellia cam;
// initialize cam structure with key and iv
byte plain[] = { /* initialize with encrypted message to decrypt */ };
byte cipher[sizeof(plain)];
wc_CamelliaCbcEncrypt(&cam, cipher, plain, sizeof(plain));
See Also:
wc_CamelliaCbcDecrypt
wc_CamelliaCbcDecrypt
Synopsis:
#include <wolfssl/wolfcrypt/camellia.h>
void wc_CamelliaCbcDecrypt(Camellia* cam, byte* out, const byte* in, word32 sz);
Description:
This function decrypts the ciphertext from the buffer in and stores the output in the buffer out. It performs this decryption using Camellia with Cipher Block Chaining (CBC).
Return Values:
No return value for this function.
Parameters:
cam: pointer to the camellia structure to use for encryption
out: pointer to the buffer in which to store the decrypted message
in: pointer to the buffer containing the encrypted ciphertext
sz: the size of the message to encrypt
Example:
Camellia cam;
// initialize cam structure with key and iv
byte cipher[] = { /* initialize with encrypted message to decrypt */ };;
byte decrypted[sizeof(cipher)];
wc_CamelliaCbcDecrypt(&cam, decrypted, cipher, sizeof(cipher));
See Also:
wc_CamelliaCbcEncrypt
18.7 ChaCha
wc_Chacha_SetKey
Synopsis:
#include <wolfssl/wolfcrypt/chacha.h>
int wc_Chacha_SetKey(ChaCha* ctx, const byte* key, word32 keySz);
Description:
This function sets the key for a ChaCha object, initializing it for use as a cipher. It should be called before setting the nonce with wc_Chacha_SetIV, and before using it for encryption with wc_Chacha_Process.
Return Values:
0: Returned upon successfully setting the key
BAD_FUNC_ARG: returned if there is an error processing the ctx input argument or if the key is not 16 or 32 bytes long
Parameters:
ctx: pointer to the ChaCha structure in which to set the key
key: pointer to a buffer containing the 16 or 32 byte key with which to initialize the ChaCha structure
keySz: the length of the key passed in
Example:
ChaCha enc;
byte key[] = { /* initialize key */ };
if( wc_Chacha_SetKey(&enc, key, sizeof(key)) != 0) {
// error initializing ChaCha structure
}
See Also:
wc_Chacha_SetIV, wc_Chacha_Process
wc_Chacha_SetIV
Synopsis:
#include <wolfssl/wolfcrypt/chacha.h>
int wc_Chacha_SetIV(ChaCha* ctx, const byte* inIv, word32 counter);
Description:
This function sets the initialization vector (nonce) for a ChaCha object, initializing it for use as a cipher. It should be called after the key has been set, using wc_Chacha_SetKey. A difference nonce should be used for each round of encryption.
Return Values:
0: Returned upon successfully setting the initialization vector
BAD_FUNC_ARG: returned if there is an error processing the ctx input argument
Parameters:
ctx: pointer to the ChaCha structure on which to set the iv
inIv: pointer to a buffer containing the 12 byte initialization vector with which to initialize the ChaCha structure
counter: the value at which the block counter should start--usually zero.
Example:
ChaCha enc;
// initialize enc with wc_Chacha_SetKey
byte iv[12];
// initialize iv
if( wc_Chacha_SetIV(&enc, iv, 0) != 0) {
// error initializing ChaCha structure
}
See Also:
wc_Chacha_SetKey, wc_Chacha_Process
wc_Chacha_Process
Synopsis:
#include <wolfssl/wolfcrypt/chacha.h>
int wc_Chacha_Process(ChaCha* ctx, byte* output, const byte* input, word32 msglen);
Description:
This function processes the text from the buffer input, encrypts or decrypts it, and stores the result in the buffer output.
Return Values:
0: Returned upon successfully encrypting or decrypting the input
BAD_FUNC_ARG: returned if there is an error processing the ctx input argument
Parameters:
ctx: pointer to the ChaCha structure on which to set the iv
output: pointer to a buffer in which to store the output ciphertext or decrypted plaintext
input: pointer to the buffer containing the input plaintext to encrypt or the input ciphertext to decrypt
msglen: length of the message to encrypt or the ciphertext to decrypt
Example:
ChaCha enc;
// initialize enc with wc_Chacha_SetKey and wc_Chacha_SetIV
byte plain[] = { /* initialize plaintext */ };
byte cipher[sizeof(plain)];
if( wc_Chacha_Process(&enc, cipher, plain, sizeof(plain)) != 0) {
// error processing ChaCha cipher
}
See Also:
wc_Chacha_SetKey, wc_Chacha_Process
18.8 ChaCha20 with Poly1305
wc_ChaCha20Poly1305_Encrypt
Synopsis:
#include <wolfssl/wolfcrypt/chacha20_poly1305.h>
int wc_ChaCha20Poly1305_Encrypt(
const byte inKey[CHACHA20_POLY1305_AEAD_KEYSIZE],
const byte inIV[CHACHA20_POLY1305_AEAD_IV_SIZE],
const byte* inAAD, const word32 inAADLen,
const byte* inPlaintext, const word32 inPlaintextLen,
byte* outCiphertext,
byte outAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE]);
Description:
This function encrypts an input message, inPlaintext, using the ChaCha20 stream cipher, into the output buffer, outCiphertext. It also performs Poly-1305 authentication (on the cipher text), and stores the generated authentication tag in the output buffer, outAuthTag.
Return Values:
0: Returned upon successfully encrypting the message
BAD_FUNC_ARG: returned if there is an error during the encryption process
Parameters:
inKey: pointer to a buffer containing the 32 byte key to use for encryption
inIv: pointer to a buffer containing the 12 byte iv to use for encryption
inAAD: pointer to the buffer containing arbitrary length additional authenticated data (AAD)
inAADLen: length of the input AAD
inPlaintext: pointer to the buffer containing the plaintext to encrypt
inPlaintextLen: the length of the plain text to encrypt
outCiphertext: pointer to the buffer in which to store the ciphertext
outAuthTag: pointer to a 16 byte wide buffer in which to store the authentication tag
Example:
byte key[] = { /* initialize 32 byte key */ };
byte iv[] = { /* initialize 12 byte key */ };
byte inAAD[] = { /* initialize AAD */ };
byte plain[] = { /* initialize message to encrypt */ };
byte cipher[sizeof(plain)];
byte authTag[16];
int ret = wc_ChaCha20Poly1305_Encrypt(key, iv, inAAD, sizeof(inAAD),
plain, sizeof(plain), cipher, authTag);
if(ret != 0) {
// error running encrypt
}
See Also:
wc_ChaCha20Poly1305_Decrypt, wc_ChaCha_*, wc_Poly1305*
wc_ChaCha20Poly1305_Decrypt
Synopsis:
#include <wolfssl/wolfcrypt/chacha20_poly1305.h>
int wc_ChaCha20Poly1305_Decrypt(
const byte inKey[CHACHA20_POLY1305_AEAD_KEYSIZE],
const byte inIV[CHACHA20_POLY1305_AEAD_IV_SIZE],
const byte* inAAD, const word32 inAADLen,
const byte* inCiphertext, const word32 inCiphertextLen,
const byte inAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE],
byte* outPlaintext);
Description:
This function decrypts input ciphertext, inCiphertext, using the ChaCha20 stream cipher, into the output buffer, outPlaintext. It also performs Poly-1305 authentication, comparing the given inAuthTag to an authentication generated with the inAAD (arbitrary length additional authentication data). Note: If the generated authentication tag does not match the supplied authentication tag, the text is not decrypted.
Return Values:
0: Returned upon successfully decrypting the message
BAD_FUNC_ARG: Returned if any of the function arguments do not match what is expected
MAC_CMP_FAILED_E: Returned if the generated authentication tag does not match the supplied inAuthTag.
Parameters:
inKey: pointer to a buffer containing the 32 byte key to use for decryption
inIv: pointer to a buffer containing the 12 byte iv to use for decryption
inAAD: pointer to the buffer containing arbitrary length additional authenticated data (AAD)
inAADLen: length of the input AAD
inCiphertext: pointer to the buffer containing the ciphertext to decrypt
outCiphertextLen: the length of the ciphertext to decrypt
inAuthTag: pointer to the buffer containing the 16 byte digest for authentication
outPlaintext: pointer to the buffer in which to store the plaintext
Example:
byte key[] = { /* initialize 32 byte key */ };
byte iv[] = { /* initialize 12 byte key */ };
byte inAAD[] = { /* initialize AAD */ };
byte cipher[] = { /* initialize with received ciphertext */ };
byte authTag[16] = { /* initialize with received authentication tag */ };
byte plain[sizeof(cipher)];
int ret = wc_ChaCha20Poly1305_Decrypt(key, iv, inAAD, sizeof(inAAD),
cipher, sizeof(cipher), plain, authTag);
if(ret == MAC_CMP_FAILED_E) {
// error during authentication
} else if( ret != 0) {
// error with function arguments
}
See Also:
wc_ChaCha20Poly1305_Encrypt, wc_ChaCha_*, wc_Poly1305*
18.9 Coding
Base64_Decode
Synopsis:
#include <wolfssl/wolfcrypt/coding.h>
int Base64_Decode(const byte* in, word32 inLen, byte* out, word32* outLen);
Description:
This function decodes the given Base64 encoded input, in, and stores the result in the output buffer out. It also sets the size written to the output buffer in the variable outLen.
Return Values:
0: Returned upon successfully decoding the Base64 encoded input
BAD_FUNC_ARG: Returned if the output buffer is too small to store the decoded input
ASN_INPUT_E: Returned if a character in the input buffer falls outside of the Base64 range ([A-Za-z0-9+/=]) or if there is an invalid line ending in the Base64 encoded input
Parameters:
in: pointer to the input buffer to decode
inLen: length of the input buffer to decode
out: pointer to the output buffer in which to store the decoded message
outLen: pointer to the length of the output buffer. Updated with the bytes written at the end of the function call
Example:
byte encoded[] = { /* initialize text to decode */ };
byte decoded[sizeof(encoded)];
// requires at least (sizeof(encoded) * 3 + 3) / 4 room
int outLen = sizeof(decoded);
if( Base64_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) {
// error decoding input buffer
}
See Also:
Base64_Encode, Base16_Decode
Base64_Encode
Synopsis:
#include <wolfssl/wolfcrypt/coding.h>
int Base64_Encode(const byte* in, word32 inLen, byte* out, word32* outLen);
Description:
This function encodes the given input, in, and stores the Base64 encoded result in the output buffer out. It writes the data with the traditional ‘\n’ line endings, instead of escaped %0A line endings. Upon successfully completing, this function also sets outLen to the number of bytes written to the output buffer
Return Values:
0: Returned upon successfully decoding the Base64 encoded input
BAD_FUNC_ARG: Returned if the output buffer is too small to store the encoded input
BUFFER_E: Returned if the output buffer runs out of room while encoding
Parameters:
in: pointer to the input buffer to encode
inLen: length of the input buffer to encode
out: pointer to the output buffer in which to store the encoded message
outLen: pointer to the length of the output buffer in which to store the encoded message
Example:
byte plain[] = { /* initialize text to encode */ };
byte encoded[MAX_BUFFER_SIZE];
int outLen = sizeof(encoded);
if( Base64_Encode(plain, sizeof(plain), encoded, &outLen) != 0 ) {
// error encoding input buffer
}
See Also:
Base64_EncodeEsc, Base64_Decode
Base64_EncodeEsc
Synopsis:
#include <wolfssl/wolfcrypt/coding.h>
int Base64_EncodeEsc(const byte* in, word32 inLen, byte* out, word32* outLen);
Description:
This function encodes the given input, in, and stores the Base64 encoded result in the output buffer out. It writes the data with %0A escaped line endings instead of ‘\n’ line endings. Upon successfully completing, this function also sets outLen to the number of bytes written to the output buffer
Return Values:
0: Returned upon successfully decoding the Base64 encoded input
BAD_FUNC_ARG: Returned if the output buffer is too small to store the encoded input
BUFFER_E: Returned if the output buffer runs out of room while encoding
ASN_INPUT_E: Returned if there is an error processing the decode on the input message
Parameters:
in: pointer to the input buffer to encode
inLen: length of the input buffer to encode
out: pointer to the output buffer in which to store the encoded message
outLen: pointer to the length of the output buffer in which to store the encoded message
Example:
byte plain[] = { /* initialize text to encode */ };
byte encoded[MAX_BUFFER_SIZE];
int outLen = sizeof(encoded);
if( Base64_EncodeEsc(plain, sizeof(plain), encoded, &outLen) != 0 ) {
// error encoding input buffer
}
See Also:
Base64_Encode, Base64_Decode
Base64_Encode_NoNl
Synopsis:
#include <wolfssl/wolfcrypt/coding.h>
int Base64_Encode_NoNl(const byte* in, word32 inLen, byte* out, word32* outLen);
Description:
This function encodes the given input, in, and stores the Base64 encoded result in the output buffer out. It writes the data with no new lines. Upon successfully completing, this function also sets outLen to the number of bytes written to the output buffer
Return Values:
0: Returned upon successfully decoding the Base64 encoded input
BAD_FUNC_ARG: Returned if the output buffer is too small to store the encoded input
BUFFER_E: Returned if the output buffer runs out of room while encoding
ASN_INPUT_E: Returned if there is an error processing the decode on the input message
Parameters:
in: pointer to the input buffer to encode
inLen: length of the input buffer to encode
out: pointer to the output buffer in which to store the encoded message
outLen: pointer to the length of the output buffer in which to store the encoded message
Example:
byte plain[] = { /* initialize text to encode */ };
byte encoded[MAX_BUFFER_SIZE];
int outLen = sizeof(encoded);
if( Base64_Encode_NoNl(plain, sizeof(plain), encoded, &outLen) != 0 ) {
// error encoding input buffer
}
See Also:
Base64_Encode, Base64_Decode
Base16_Encode
Synopsis:
#include <wolfssl/wolfcrypt/coding.h>
int Base16_Encode(const byte* in, word32 inLen, byte* out, word32* outLen)
Description:
Encode input to base16 output.
Return Values:
0: Success
BAD_FUNC_ARG: Returns if in, out, or outLen is null or if outLen is less than 2 times inLen plus 1.
Parameters:
in - Pointer to input buffer to be encoded.
inLen - Length of input buffer.
out - Pointer to output buffer.
outLen - Length of output buffer. Is set to len of encoded output.
Example:
byte in[] = { /* Contents of something to be encoded /* };
byte out[NECESSARY_OUTPUT_SIZE];
word32 outSz = sizeof(out);
if(Base16_Encode(in, sizeof(in), out, &outSz) != 0)
{
/* Handle encode error */
}
See Also:
Base64_Encode, Base64_Decode, Base16_Decode
Base16_Decode
Synopsis:
#include <wolfssl/wolfcrypt/coding.h>
int Base16_Decode(const byte* in, word32 inLen, byte* out, word32* outLen)
Description:
This function decodes the given Base16 encoded input, in, and stores the result in the output buffer out. It also sets the size written to the output buffer in the variable outLen.
Return Values:
0: Returned upon successfully decoding the Base16 encoded input
BAD_FUNC_ARG: Returned if the output buffer is too small to store the decoded input or if the input length is not a multiple of two
ASN_INPUT_E: Returned if a character in the input buffer falls outside of the Base16 range ([0-9A-F])
Parameters:
in: pointer to the input buffer to decode
inLen: length of the input buffer to decode
out: pointer to the output buffer in which to store the decoded message
outLen: pointer to the length of the output buffer. Updated with the bytes written at the end of the function call
Example:
byte encoded[] = { /* initialize text to decode */ };
byte decoded[sizeof(encoded)];
int outLen = sizeof(decoded);
if( Base16_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) {
// error decoding input buffer
}
See Also:
Base64_Encode, Base64_Decode, Base16_Encode
18.10 Compression
wc_Compress
Synopsis:
#include <wolfssl/wolfcrypt/compress.h>
int wc_Compress(byte* out, word32 outSz, const byte* in, word32 inSz, word32 flags);
Description:
This function compresses the given input data using Huffman coding and stores the output in out. Note that the output buffer should still be larger than the input buffer because there exists a certain input for which there will be no compression possible, which will still require a lookup table. It is recommended that one allocate srcSz + 0.1% + 12 for the output buffer.
Return Values:
On successfully compressing the input data, returns the number of bytes stored in the output buffer
COMPRESS_INIT_E: Returned if there is an error initializing the stream for compression
COMPRESS_E: Returned if an error occurs during compression
Parameters:
out - pointer to the output buffer in which to store the compressed data
outSz - size available in the output buffer for storage
in - pointer to the buffer containing the message to compress
inSz - size of the input message to compress
flags - flags to control how compression operates. Use 0 for normal decompression
Example:
byte message[] = { /* initialize text to compress */ };
byte compressed[(sizeof(message) + sizeof(message) * .001 + 12 )];
// Recommends at least srcSz + .1% + 12
if( wc_Compress(compressed, sizeof(compressed), message, sizeof(message), 0) != 0){
// error compressing data
}
See Also:
wc_DeCompress
wc_DeCompress
Synopsis:
#include <wolfssl/wolfcrypt/compress.h>
int wc_DeCompress(byte* out, word32 outSz, const byte* in, word32 inSz)
Description:
This function decompresses the given compressed data using Huffman coding and stores the output in out.
Return Values:
On successfully decompressing the input data, returns the number of bytes stored in the output buffer
COMPRESS_INIT_E: Returned if there is an error initializing the stream for compression
COMPRESS_E: Returned if an error occurs during compression
Parameters:
out - pointer to the output buffer in which to store the decompressed data
outSz - size available in the output buffer for storage
in - pointer to the buffer containing the message to decompress
inSz - size of the input message to decompress
Example:
byte compressed[] = { /* initialize compressed message */ };
byte decompressed[MAX_MESSAGE_SIZE];
if( wc_DeCompress(decompressed, sizeof(decompressed),
compressed, sizeof(compressed)) != 0 ) {
// error decompressing data
}
See Also:
wc_Compress
18.11 Curve25519
wc_curve25519_init
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_init(curve25519_key* key)
Description:
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.
Return Values:
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
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_make_key(RNG* rng, int keysize, curve25519_key* key);
Description:
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.
Return Values:
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
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
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_shared_secret(curve25519_key* private_key,
curve25519_key* public_key,
byte* out, word32* outlen);
Description:
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.
Return Values:
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
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_shared_secret_ex(curve25519_key* private_key,
curve25519_key* public_key,
byte* out, word32* outlen, int endian)
Description:
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.
Return Values:
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_free
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
void wc_curve25519_free(curve25519_key* key);
Description:
This function frees a curve 25519 object.
Return Values:
No return values for this function.
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_raw
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_import_private_raw(const byte* priv, word32 privSz,
const byte* pub, word32 pubSz, curve25519_key* key);
Description:
This function imports a public-private key pair into a curve25519_key structure. Big endian only.
Return Values:
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
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_import_private_raw_ex(const byte* priv, word32 privSz,
const byte* pub, word32 pubSz,
curve25519_key* key, int endian);
Description:
This function imports a public-private key pair into a curve25519_key structure. Supports both big and little endian.
Return Values:
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_export_private_raw
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_export_private_raw(curve25519_key* key, byte* out, word32* outLen);
Description:
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.
Return Values:
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
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_export_private_raw_ex(curve25519_key* key, byte* out,
word32* outLen, int endian)
Description:
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.
Return Values:
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_import_public
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_import_public(const byte* in, word32 inLen, curve25519_key* key);
Description:
This function imports a public key from the given in buffer and stores it in the curve25519_key structure.
Return Values:
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
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_import_public_ex(const byte* in, word32 inLen, curve25519_key* key, int endian);
Description:
This function imports a public key from the given in buffer and stores it in the curve25519_key structure.
Return Values:
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_export_public
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_export_public(curve25519_key* key, byte* out, word32* outLen);
Description:
This function exports a public key from the given key structure and stores the result in the out buffer. Big endian only.
Return Values:
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
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_export_public(curve25519_key* key, byte* out, word32* outLen, int endian);
Description:
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.
Return Values:
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_size
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_size(curve25519_key* key);
Description:
This function returns the key size of the given key structure.
Return Values:
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
wc_curve25519_import_private
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_import_private(const byte* priv, word32 privSz,
curve25519_key* key);
Description:
This function imports a curve25519 private key only. (Big endian).
Return Values:
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
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_import_private_ex(const byte* priv, word32 privSz,
curve25519_key* key, int endian);
Description:
curve25519 private key import only. (Big or Little endian)
Return Values:
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 - 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_export_key_raw
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_export_key_raw(curve25519_key* key,
byte* priv, word32 *privSz,
byte* pub, word32 *pubSz)
Description:
Export curve25519 key pair. Big endian only.
Return Values:
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
Synopsis:
#include <wolfssl/wolfcrypt/curve25519.h>
int wc_curve25519_export_key_raw_ex(curve25519_key* key,
byte* priv, word32 *privSz,
byte* pub, word32 *pubSz,
int endian)
Description:
Export curve25519 key pair. Big or little endian.
Return Values:
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
18.12 3DES
wc_Des_SetKey
Synopsis:
#include <wolfssl/wolfcrypt/des3.h>
int wc_Des_SetKey(Des* des, const byte* key, const byte* iv, int dir)
Description:
This function sets the key and initialization vector (iv) for the Des structure given as argument. It also initializes and allocates space for the buffers needed for encryption and decryption, if these have not yet been initialized. Note: If no iv is provided (i.e. iv == NULL) the initialization vector defaults to an iv of 0.
Return Values:
0: On successfully setting the key and initialization vector for the Des structure
Parameters:
des - pointer to the Des structure to initialize
key - pointer to the buffer containing the 8 byte key with which to initialize the Des structure
iv - pointer to the buffer containing the 8 byte iv with which to initialize the Des structure. If this is not provided, the iv defaults to 0
dir - direction of encryption. Valid options are: DES_ENCRYPTION, and DES_DECRYPTION
Example:
Des enc; // Des structure used for encryption
int ret;
byte key[] = { /* initialize with 8 byte key */ };
byte iv[] = { /* initialize with 8 byte iv */ };
ret = wc_Des_SetKey(&des, key, iv, DES_ENCRYPTION);
if (ret != 0) {
// error initializing des structure
}
See Also:
wc_Des_SetIV, wc_Des3_SetKey
wc_Des_SetIV
Synopsis:
#include <wolfssl/wolfcrypt/des3.h>
void wc_Des_SetIV(Des* des, const byte* iv);
Description:
This function sets the initialization vector (iv) for the Des structure given as argument. When passed a NULL iv, it sets the initialization vector to 0.
Return Values:
No return value for this function.
Parameters:
des - pointer to the Des structure for which to set the iv
iv - pointer to the buffer containing the 8 byte iv with which to initialize the Des structure. If this is not provided, the iv defaults to 0
Example:
Des enc; // Des structure used for encryption
// initialize enc with wc_Des_SetKey
byte iv[] = { /* initialize with 8 byte iv */ };
wc_Des_SetIV(&enc, iv);
}
See Also:
wc_Des_SetKey
wc_Des_CbcEncrypt
Synopsis:
#include <wolfssl/wolfcrypt/des3.h>
int wc_Des_CbcEncrypt(Des* des, byte* out, const byte* in, word32 sz);
Description:
This function encrypts the input message, in, and stores the result in the output buffer, out. It uses DES encryption with cipher block chaining (CBC) mode.
Return Values:
0: Returned upon successfully encrypting the given input message
Parameters:
des - pointer to the Des structure to use for encryption
out - pointer to the buffer in which to store the encrypted ciphertext
in - pointer to the input buffer containing the message to encrypt
sz - length of the message to encrypt
Example:
Des enc; // Des structure used for encryption
// initialize enc with wc_Des_SetKey, use mode DES_ENCRYPTION
byte plain[] = { /* initialize with message */ };
byte cipher[sizeof(plain)];
if ( wc_Des_CbcEncrypt(&enc, cipher, plain, sizeof(plain)) != 0) {
// error encrypting message
}
See Also:
wc_Des_SetKey, wc_Des_CbcDecrypt
wc_Des_CbcDecrypt
Synopsis:
#include <wolfssl/wolfcrypt/des3.h>
int wc_Des_CbcDecrypt(Des* des, byte* out, const byte* in, word32 sz);
Description:
This function decrypts the input ciphertext, in, and stores the resulting plaintext in the output buffer, out. It uses DES encryption with cipher block chaining (CBC) mode.
Return Values:
0: Returned upon successfully decrypting the given ciphertext
Parameters:
des - pointer to the Des structure to use for decryption
out - pointer to the buffer in which to store the decrypted plaintext
in - pointer to the input buffer containing the encrypted ciphertext
sz - length of the ciphertext to decrypt
Example:
Des dec; // Des structure used for decryption
// initialize dec with wc_Des_SetKey, use mode DES_DECRYPTION
byte cipher[] = { /* initialize with ciphertext */ };
byte decoded[sizeof(cipher)];
if ( wc_Des_CbcDecrypt(&dec, decoded, cipher, sizeof(cipher)) != 0) {
// error decrypting message
}
See Also:
wc_Des_SetKey, wc_Des_CbcEncrypt
wc_Des_EcbEncrypt
Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible
Synopsis:
#include <wolfssl/wolfcrypt/des3.h>
int wc_Des_EcbEncrypt(Des* des, byte* out, const byte* in, word32 sz);
Description:
This function encrypts the input message, in, and stores the result in the output buffer, out. It uses Des encryption with Electronic Codebook (ECB) mode.
Return Values:
0: Returned upon successfully encrypting the given plaintext
Parameters:
des - pointer to the Des structure to use for encryption
out - pointer to the buffer in which to store the encrypted message
in - pointer to the input buffer containing the plaintext to encrypt
sz - length of the plaintext to encrypt
Example:
Des enc; // Des structure used for encryption
// initialize enc with wc_Des_SetKey, use mode DES_ENCRYPTION
byte plain[] = { /* initialize with message to encrypt */ };
byte cipher[sizeof(plain)];
if ( wc_Des_EcbEncrypt(&enc,cipher, plain, sizeof(plain)) != 0) {
// error encrypting message
}
See Also:
wc_Des_SetKe
wc_Des_CbcEncryptWithKey
Synopsis:
#include <wolfssl/wolfcrypt/wc_encrypt.h>
int wc_Des_CbcEncryptWithKey(byte* out, const byte* in, word32 sz,
const byte* key, const byte* iv)
Description:
This function encrypts the input plaintext, in, and stores the resulting ciphertext in the output buffer, out. It uses DES encryption with cipher block chaining (CBC) mode. This function is a substitute for wc_Des_CbcEncrypt, allowing the user to encrypt a message without directly instantiating a Des structure.
Return Values:
0: Returned after successfully encrypting data.
MEMORY_E: Returned if there's an error allocating memory for a Des structure.
< 0: Returned on any error during encryption.
Parameters:
out - Final encrypted data
in - Data to be encrypted, must be padded to Des block size.
sz - Size of input buffer.
key - Pointer to the key to use for encryption.
iv - Initialization vector
Example:
byte key[] = { /* initialize with 8 byte key */ };
byte iv[] = { /* initialize with 8 byte iv */ };
byte in[] = { /* Initialize with plaintext */ };
byte out[sizeof(in)];
if ( wc_Des_CbcEncryptWithKey(&out, in, sizeof(in), key, iv) != 0)
{
/* error encrypting message */
}
See Also:
wc_Des_CbcDecryptWithKey, wc_Des_CbcEncrypt
wc_Des_CbcDecryptWithKey
Synopsis:
#include <wolfssl/wolfcrypt/wc_encrypt.h>
int wc_Des_CbcDecryptWithKey(byte* out, const byte* in, word32 sz, const byte* key,
const byte* iv);
Description:
This function decrypts the input ciphertext, in, and stores the resulting plaintext in the output buffer, out. It uses DES encryption with cipher block chaining (CBC) mode. This function is a substitute for wc_Des_CbcDecrypt, allowing the user to decrypt a message without directly instantiating a Des structure.
Return Values:
0: Returned upon successfully decrypting the given ciphertext
MEMORY_E: Returned if there is an error allocating space for a Des structure
Parameters:
out - pointer to the buffer in which to store the decrypted plaintext
in - pointer to the input buffer containing the encrypted ciphertext
sz - length of the ciphertext to decrypt
key - pointer to the buffer containing the 8 byte key to use for decryption
iv - pointer to the buffer containing the 8 byte iv to use for decryption. If no iv is provided, the iv defaults to 0
Example:
int ret;
byte key[] = { /* initialize with 8 byte key */ };
byte iv[] = { /* initialize with 8 byte iv */ };
byte cipher[] = { /* initialize with ciphertext */ };
byte decoded[sizeof(cipher)];
if ( wc_Des_CbcDecryptWithKey(decoded, cipher, sizeof(cipher), key, iv) != 0) {
// error decrypting message
}
See Also:
wc_Des_CbcDecrypt
wc_Des3_SetKey
Synopsis:
#include <wolfssl/wolfcrypt/des3.h>
int wc_Des3_SetKey(Des3* des3, const byte* key, const byte* iv, int dir);
Description:
This function sets the key and initialization vector (iv) for the Des3 structure given as argument. It also initializes and allocates space for the buffers needed for encryption and decryption, if these have not yet been initialized. Note: If no iv is provided (i.e. iv == NULL) the initialization vector defaults to an iv of 0.
Return Values:
0: On successfully setting the key and initialization vector for the Des structure
Parameters:
des3 - pointer to the Des3 structure to initialize
key - pointer to the buffer containing the 24 byte key with which to initialize the Des3 structure
iv - pointer to the buffer containing the 8 byte iv with which to initialize the Des3 structure. If this is not provided, the iv defaults to 0
dir - direction of encryption. Valid options are: DES_ENCRYPTION, and DES_DECRYPTION
Example:
Des3 enc; // Des3 structure used for encryption
int ret;
byte key[] = { /* initialize with 24 byte key */ };
byte iv[] = { /* initialize with 8 byte iv */ };
ret = wc_Des3_SetKey(&des, key, iv, DES_ENCRYPTION);
if (ret != 0) {
// error initializing des structure
}
See Also:
wc_Des3_SetIV, wc_Des3_CbcEncrypt, wc_Des3_CbcDecrypt
wc_Des3_EcbEncrypt
Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible
Synopsis:
#include <wolfssl/wolfcrypt/des3.h>
int wc_Des3_EcbEncrypt(Des* des, byte* out, const byte* in, word32 sz);
Description:
This function encrypts the input message, in, and stores the result in the output buffer, out. It uses Des3 encryption with Electronic Codebook (ECB) mode.
Return Values:
0: Returned upon successfully encrypting the given plaintext
Parameters:
des3 - pointer to the Des3 structure to use for encryption
out - pointer to the buffer in which to store the encrypted message
in - pointer to the input buffer containing the plaintext to encrypt
sz - length of the plaintext to encrypt
Example:
Des3 enc; // Des3 structure used for encryption
// initialize enc with wc_Des3_SetKey, use mode DES_ENCRYPTION
byte plain[] = { /* initialize with message to encrypt */ };
byte cipher[sizeof(plain)];
if ( wc_Des3_EcbEncrypt(&enc,cipher, plain, sizeof(plain)) != 0) {
// error encrypting message
}
See Also: wc_Des3_SetKey
wc_Des3_EcbDecrypt
Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible
Synopsis:
#include <wolfssl/wolfcrypt/des3.h>
int wc_Des3_EcbDecrypt(Des* des, byte* out, const byte* in, word32 sz);
Description:
This function decrypts the input message, in, and stores the result in the output buffer, out. It uses Des3 decryption with Electronic Codebook (ECB) mode.
Return Values:
0: Returned upon successfully encrypting the given plaintext
Parameters:
des3 - pointer to the Des3 structure to use for decrytion
out - pointer to the buffer in which will store the decrypted message
in - pointer to the input buffer containing the ciphertext to decrypt
sz - length of the ciphertext to decrypt
Example:
Des3 dec; // Des3 structure used for decryption
// initialize dec with wc_Des3_SetKey, use mode DES_DECRYPTION
byte cipher[] = { /* initialize with message to decrypt */ };
byte plain[sizeof(cipher)];
if ( wc_Des3_EcbDecrypt(&dec,plain, cipher, sizeof(cipher)) != 0) {
// error decrypting message
}
See Also: wc_Des3_SetKey
wc_Des3_SetIV
Synopsis:
#include <wolfssl/wolfcrypt/des3.h>
int wc_Des3_SetIV(Des3* des, const byte* iv);
Description:
This function sets the initialization vector (iv) for the Des3 structure given as argument. When passed a NULL iv, it sets the initialization vector to 0.
Return Values:
No return value for this function.
Parameters:
des - pointer to the Des3 structure for which to set the iv
iv - pointer to the buffer containing the 8 byte iv with which to initialize the Des3 structure. If this is not provided, the iv defaults to 0
Example:
Des3 enc; // Des3 structure used for encryption
// initialize enc with wc_Des3_SetKey
byte iv[] = { /* initialize with 8 byte iv */ };
wc_Des3_SetIV(&enc, iv);
}
See Also:
wc_Des3_SetKey
wc_Des3_CbcEncrypt
Synopsis:
#include <wolfssl/wolfcrypt/des3.h>
int wc_Des3_CbcEncrypt(Des3* des, byte* out, const byte* in, word32 sz)
Description:
This function encrypts the input message, in, and stores the result in the output buffer, out. It uses Triple Des (3DES) encryption with cipher block chaining (CBC) mode.
Return Values:
0: Returned upon successfully encrypting the given input message
Parameters:
des - pointer to the Des3 structure to use for encryption
out - pointer to the buffer in which to store the encrypted ciphertext
in - pointer to the input buffer containing the message to encrypt
sz - length of the message to encrypt
Example:
Des3 enc; // Des3 structure used for encryption
// initialize enc with wc_Des3_SetKey, use mode DES_ENCRYPTION
byte plain[] = { /* initialize with message */ };
byte cipher[sizeof(plain)];
if ( wc_Des3_CbcEncrypt(&enc, cipher, plain, sizeof(plain)) != 0) {
// error encrypting message
}
See Also:
wc_Des3_SetKey, wc_Des3_CbcDecrypt
wc_Des3_CbcDecrypt
Synopsis:
#include <wolfssl/wolfcrypt/des3.h>
int wc_Des3_CbcDecrypt(Des3* des, byte* out, const byte* in, word32 sz)
Description:
This function decrypts the input ciphertext, in, and stores the resulting plaintext in the output buffer, out. It uses Triple Des (3DES) encryption with cipher block chaining (CBC) mode.
Return Values:
0: Returned upon successfully decrypting the given ciphertext
Parameters:
des - pointer to the Des3 structure to use for decryption
out - pointer to the buffer in which to store the decrypted plaintext
in - pointer to the input buffer containing the encrypted ciphertext
sz - length of the ciphertext to decrypt
Example:
Des3 dec; // Des structure used for decryption
// initialize dec with wc_Des3_SetKey, use mode DES_DECRYPTION
byte cipher[] = { /* initialize with ciphertext */ };
byte decoded[sizeof(cipher)];
if ( wc_Des3_CbcDecrypt(&dec, decoded, cipher, sizeof(cipher)) != 0) {
// error decrypting message
}
See Also:
wc_Des3_SetKey, wc_Des3_CbcEncrypt
wc_Des3_CbcEncryptWithKey
Synopsis:
#include <wolfssl/wolfcrypt/wc_encrypt.h>
int wc_Des3_CbcEncryptWithKey(byte* out, const byte* in, word32 sz,
const byte* key, const byte* iv)
Description:
This function encrypts the input plaintext, in, and stores the resulting ciphertext in the output buffer, out. It uses Triple DES (3DES) encryption with cipher block chaining (CBC) mode. This function is a substitute for wc_Des3_CbcEncrypt, allowing the user to encrypt a message without directly instantiating a Des3 structure.
Return Values:
0: Returned after successfully encrypting data.
MEMORY_E: Returned if there's an error allocating memory for a Des structure.
< 0: Returned on any error during encryption.
Parameters:
out - Final encrypted data
in - Data to be encrypted, must be padded to Des block size.
sz - Size of input buffer.
key - Pointer to the key to use for encryption.
iv - Initialization vector
Example:
byte key[] = { /* initialize with 8 byte key */ };
byte iv[] = { /* initialize with 8 byte iv */ };
byte in[] = { /* Initialize with plaintext */ };
byte out[sizeof(in)];
if ( wc_Des3_CbcEncryptWithKey(&out, in, sizeof(in), key, iv) != 0)
{
/* error encrypting message */
}
See Also:
wc_Des3_CbcDecryptWithKey, wc_Des_CbcEncryptWithKey, wc_Des_CbcDecryptWithKey
wc_Des3_CbcDecryptWithKey
Synopsis:
#include <wolfssl/wolfcrypt/wc_encrypt.h>
int wc_Des3_CbcDecryptWithKey(byte* out, const byte* in, word32 sz, const byte* key,
const byte* iv)
Description:
This function decrypts the input ciphertext, in, and stores the resulting plaintext in the output buffer, out. It uses Triple Des (3DES) encryption with cipher block chaining (CBC) mode. This function is a substitute for wc_Des3_CbcDecrypt, allowing the user to decrypt a message without directly instantiating a Des3 structure.
Return Values:
0: Returned upon successfully decrypting the given ciphertext
MEMORY_E: Returned if there is an error allocating space for a Des structure
Parameters:
out - pointer to the buffer in which to store the decrypted plaintext
in - pointer to the input buffer containing the encrypted ciphertext
sz - length of the ciphertext to decrypt
key - pointer to the buffer containing the 24 byte key to use for decryption
iv - pointer to the buffer containing the 8 byte iv to use for decryption. If no iv is provided, the iv defaults to 0
Example:
int ret;
byte key[] = { /* initialize with 24 byte key */ };
byte iv[] = { /* initialize with 8 byte iv */ };
byte cipher[] = { /* initialize with ciphertext */ };
byte decoded[sizeof(cipher)];
if ( wc_Des3_CbcDecryptWithKey(decoded, cipher, sizeof(cipher), key, iv) != 0) {
// error decrypting message
}
See Also:
wc_Des3_CbcDecrypt
wc_Des3_InitCavium
Synopsis:
#include <wolfssl/wolfcrypt/des3.h>
int wc_Des3_InitCavium(Des3* des3, int devId);
Description:
This function initializes Triple Des (3DES) for use with Cavium Nitrox devices. It should be called before wc_Des3_SetKey when using Cavium hardware cryptography.
Return Values:
0: Returned upon successfully initializing the Cavium device for use with Triple Des
-1: Returned if the Des3 structure evaluates to NULL or the call to CspAllocContext fails
Parameters:
des3 - pointer to Des3 structure on which to enable Cavium
devid - Id number of the device on which to enable Cavium
Example:
Des3 enc;
if (wc_Des3_InitCavium(&enc, CAVIUM_DEV_ID) != 0 ) {
// error initializing cavium device for use with 3DES
}
See Also:
wc_Des3_FreeCavium
wc_Des3_FreeCavium
Synopsis:
#include <wolfssl/wolfcrypt/des3.h>
void wc_Des3_FreeCavium(Des3* des3);
Description:
This function frees Triple Des (3DES) after use with Cavium Nitrox devices.
Return Values:
No return value for this function
Parameters:
des3 - pointer to Des3 structure to free
Example:
Des3 enc;
// initialize enc, perform encryption
...
wc_Des3_FreeCavium(&enc);
See Also:
wc_Des3_InitCavium
18.13 Diffie-Hellman
wc_InitDhKey
Synopsis:
#include <wolfssl/wolfcrypt/dh.h>
void wc_InitDhKey(DhKey* key);
Description:
This function initializes a Diffie-Hellman key for use in negotiating a secure secret key with the Diffie-Hellman exchange protocol.
Return Values:
No return value for this function.
Parameters:
key - pointer to the DhKey structure to initialize for use with secure key exchanges
Example:
DhKey key;
wc_InitDhKey(&key); // initialize DH key
See Also:
wc_FreeDhKey, wc_DhGenerateKeyPair
wc_FreeDhKey
Synopsis:
#include <wolfssl/wolfcrypt/dh.h>
void wc_FreeDhKey(DhKey* key);
Description:
This function frees a Diffie-Hellman key after it has been used to negotiate a secure secret key with the Diffie-Hellman exchange protocol.
Return Values:
No return value for this function.
Parameters:
key - pointer to the DhKey structure to free
Example:
DhKey key;
// initialize key, perform key exchange
wc_FreeDhKey(&key); // free DH key to avoid memory leaks
See Also:
wc_InitDhKey
wc_DhGenerateKeyPair
Synopsis:
#include <wolfssl/wolfcrypt/dh.h>
int wc_DhGenerateKeyPair(DhKey* key, RNG* rng, byte* priv, word32* privSz,
byte* pub, word32* pubSz);
Description:
This function generates a public/private key pair based on the Diffie-Hellman public parameters, storing the private key in priv and the public key in pub. It takes an initialized Diffie-Hellman key and an initialized rng structure.
Return Values:
BAD_FUNC_ARG: Returned if there is an error parsing one of the inputs to this function
RNG_FAILURE_E: Returned if there is an error generating a random number using rng
MP_INIT_E, MP_READ_E, MP_EXPTMOD_E, and MP_TO_E: May be returned if there is an error in the math library while generating the public key
Parameters:
key - pointer to the DhKey structure from which to generate the key pair
rng - pointer to an initialized random number generator (rng) with which to generate the keys
priv - pointer to a buffer in which to store the private key
privSz - will store the size of the private key written to priv
pub - pointer to a buffer in which to store the public key
pubSz - will store the size of the private key written to pub
Example:
DhKey key;
int ret;
byte priv[256];
byte pub[256];
word32 privSz, pubSz;
wc_InitDhKey(&key); // initialize key
// Set DH parameters using wc_DhSetKey or wc_DhKeyDecode
RNG rng;
wc_InitRng(&rng); // initialize rng
ret = wc_DhGenerateKeyPair(&key, &rng, priv, &privSz, pub, &pubSz);
See Also:
wc_InitDhKey, wc_DhSetKey, wc_DhKeyDecode
wc_DhAgree
Synopsis:
#include <wolfssl/wolfcrypt/dh.h>
int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz, const byte* priv, word32 privSz,
const byte* otherPub, word32 pubSz);
Description:
This function generates an agreed upon secret key based on a local private key and a received public key. If completed on both sides of an exchange, this function generates an agreed upon secret key for symmetric communication. On successfully generating a shared secret key, the size of the secret key written will be stored in agreeSz.
Return Values:
0: Returned on successfully generating an agreed upon secret key
MP_INIT_E, MP_READ_E, MP_EXPTMOD_E, and MP_TO_E: May be returned if there is an error while generating the shared secret key
Parameters:
key - pointer to the DhKey structure to use to compute the shared key
agree - pointer to the buffer in which to store the secret key
agreeSz - will hold the size of the secret key after successful generation
priv - pointer to the buffer containing the local secret key
privSz - size of the local secret key
otherPub - pointer to a buffer containing the received public key
pubSz - size of the received public key
Example:
DhKey key;
int ret;
byte priv[256];
byte agree[256];
word32 agreeSz;
// initialize key, set key prime and base
// wc_DhGenerateKeyPair -- store private key in priv
byte pub[] = { /* initialized with the received public key */ };
ret = wc_DhAgree(&key, agree, &agreeSz, priv, sizeof(priv), pub, sizeof(pub));
if ( ret != 0 ) {
// error generating shared key
}
See Also:
wc_DhGenerateKeyPair
wc_DhKeyDecode
Synopsis:
#include <wolfssl/wolfcrypt/dh.h>
int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key, word32 inSz);
Description:
This function decodes a Diffie-Hellman key from the given input buffer containing the key in DER format. It stores the result in the DhKey structure.
Return Values:
0: Returned on successfully decoding the input key
ASN_PARSE_E: Returned if there is an error parsing the sequence of the input
ASN_DH_KEY_E: Returned if there is an error reading the private key parameters from the parsed input
Parameters:
input - pointer to the buffer containing the DER formatted Diffie-Hellman key
inOutIdx - pointer to an integer in which to store the index parsed to while decoding the key
key - pointer to the DhKey structure to initialize with the input key
inSz - length of the input buffer. Gives the max length that may be read
Example:
DhKey key;
word32 idx = 0;
byte keyBuff[1024];
// initialize with DER formatted key
wc_DhKeyInit(&key);
ret = wc_DhKeyDecode(keyBuff, &idx, &key, sizeof(keyBuff));
if ( ret != 0 ) {
// error decoding key
}
See Also:
wc_DhSetKey
wc_DhSetKey
Synopsis:
#include <wolfssl/wolfcrypt/dh.h>
int wc_DhSetKey(DhKey* key, const byte* p, word32 pSz, const byte* g, word32 gSz);
Description:
This function sets the key for a DhKey structure using the input private key parameters. Unlike wc_DhKeyDecode, this function does not require that the input key be formatted in DER format, and instead simply accepts the parsed input parameters p (prime) and g (base).
Return Values:
0: Returned on successfully setting the key
BAD_FUNC_ARG: Returned if any of the input parameters evaluate to NULL
MP_INIT_E: Returned if there is an error initializing the key parameters for storage
ASN_DH_KEY_E: Returned if there is an error reading in the DH key parameters p and g
Parameters:
key - pointer to the DhKey structure on which to set the key
p - pointer to the buffer containing the prime for use with the key
pSz - length of the input prime
g - pointer to the buffer containing the base for use with the key
gSz - length of the input base
Example:
DhKey key;
byte p[] = { /* initialize with prime */ };
byte g[] = { /* initialize with base */ };
wc_DhKeyInit(&key);
ret = wc_DhSetKey(key, p, sizeof(p), g, sizeof(g));
if ( ret != 0 ) {
// error setting key
}
See Also:
wc_DhKeyDecode
wc_DhParamsLoad
Synopsis:
#include <wolfssl/wolfcrypt/dh.h>
int wc_DhParamsLoad(const byte* input, word32 inSz, byte* p, word32* pInOutSz, byte* g,
word32* gInOutSz);
Description:
This function loads the Diffie-Hellman parameters, p (prime) and g (base) out of the given input buffer, DER formatted.
Return Values:
0: Returned on successfully extracting the DH parameters
ASN_PARSE_E: Returned if an error occurs while parsing the DER formatted DH certificate
BUFFER_E: Returned if there is inadequate space in p or g to store the parsed parameters
Parameters:
input - pointer to a buffer containing a DER formatted Diffie-Hellman certificate to parse
inSz - size of the input buffer
p - pointer to a buffer in which to store the parsed prime
pInOutSz - pointer to a word32 object containing the available size in the p buffer. Will be overwritten with the number of bytes written to the buffer after completing the function call
g - pointer to a buffer in which to store the parsed base
gInOutSz - pointer to a word32 object containing the available size in the g buffer. Will be overwritten with the number of bytes written to the buffer after completing the function call
Example:
byte dhCert[] = { /* initialize with DER formatted certificate /* };
byte p[MAX_DH_SIZE];
byte g[MAX_DH_SIZE];
word32 pSz = MAX_DH_SIZE;
word32 gSz = MAX_DH_SIZE;
ret = wc_DhParamsLoad(dhCert, sizeof(dhCert), p, &pSz, g, &gSz);
if ( ret != 0 ) {
// error parsing inputs
}
See Also:
wc_DhSetKey, wc_DhKeyDecode
18.14 DSA
wc_InitDsaKey
Synopsis:
#include <wolfssl/wolfcrypt/dsa.h>
int wc_InitDsaKey(DsaKey* key);
Description:
This function initializes a DsaKey object in order to use it for authentication via the Digital Signature Algorithm (DSA).
Return Values:
0: Returned on success.
BAD_FUNC_ARG: Returned if a NULL key is passed in.
Parameters:
key - pointer to the DsaKey structure to initialize
Example:
DsaKey key;
int ret;
ret = wc_InitDsaKey(&key); // initialize DSA key
See Also:
wc_FreeDsaKey
wc_FreeDsaKey
Synopsis:
#include <wolfssl/wolfcrypt/dsa.h>
void wc_FreeDsaKey(DsaKey* key);
Description:
This function frees a DsaKey object after it has been used.
Return Values:
No return value for this function.
Parameters:
key - pointer to the DsaKey structure to free
Example:
DsaKey key;
// initialize key, use for authentication
...
wc_FreeDsaKey(&key); // free DSA key
See Also:
wc_FreeDsaKey
wc_DsaSign
Synopsis:
#include <wolfssl/wolfcrypt/dsa.h>
int wc_DsaSign(const byte* digest, byte* out, DsaKey* key, RNG* rng);
Description:
This function signs the input digest and stores the result in the output buffer, out.
Return Values:
0: Returned on successfully signing the input digest
MP_INIT_E, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error in processing the DSA signature.
Parameters:
digest - pointer to the hash to sign
out - pointer to the buffer in which to store the signature
key - pointer to the initialized DsaKey structure with which to generate the signature
rng - pointer to an initialized RNG to use with the signature generation
Example:
DsaKey key;
// initialize DSA key, load private Key
int ret;
RNG rng;
wc_InitRng(&rng);
byte hash[] = { /* initialize with hash digest */ };
byte signature[40]; // signature will be 40 bytes (320 bits)
ret = wc_DsaSign(hash, signature, &key, &rng);
if (ret != 0) {
// error generating DSA signature
}
See Also:
wc_DsaVerify
wc_DsaVerify
Synopsis:
#include <wolfssl/wolfcrypt/dsa.h>
int wc_DsaVerify(const byte* digest, const byte* sig, DsaKey* key, int* answer);
Description:
This function verifies the signature of a digest, given a private key. It stores whether the key properly verifies in the answer parameter, with 1 corresponding to a successful verification, and 0 corresponding to failed verification.
Return Values:
0: Returned on successfully processing the verify request. Note: this does not mean that the signature is verified, only that the function succeeded
MP_INIT_E, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error in verifying the DSA signature
Parameters:
digest - pointer to the digest containing the subject of the signature
sig - pointer to the buffer containing the signature to verify
key - pointer to the initialized DsaKey structure with which to verify the signature
answer - pointer to an integer which will store whether the verification was successful
Example:
DsaKey key;
// initialize DSA key, load public Key
int ret;
int verified;
byte hash[] = { /* initialize with hash digest */ };
byte signature[] = { /* initialize with signature to verify */ };
ret = wc_DsaVerify(hash, signature, &key, &verified);
if (ret != 0) {
// error processing verify request
} else if (answer == 0) {
// invalid signature
}
See Also:
wc_DsaSign
wc_DsaPublicKeyDecode
Synopsis:
#include <wolfssl/wolfcrypt/dsa.h>
int wc_DsaPublicKeyDecode(const byte* input, word32* inOutIdx, DsaKey* key,
word32 inSz);
Description:
This function decodes a DER formatted certificate buffer containing a DSA public key, and stores the key in the given DsaKey structure. It also sets the inOutIdx parameter according to the length of the input read.
Return Values:
0: Returned on successfully setting the public key for the DsaKey object
ASN_PARSE_E: Returned if there is an error in the encoding while reading the certificate buffer
ASN_DH_KEY_E: Returned if one of the DSA parameters is incorrectly formatted
Parameters:
input - pointer to the buffer containing the DER formatted DSA public key
inOutIdx - pointer to an integer in which to store the final index of the certificate read
key - pointer to the DsaKey structure in which to store the public key
inSz - size of the input buffer
Example:
int ret, idx=0;
DsaKey key;
wc_InitDsaKey(&key);
byte derBuff[] = { /* DSA public key */ };
ret = wc_DsaPublicKeyDecode(derBuff, &idx, &key, inSz);
if (ret != 0) {
// error reading public key
}
See Also:
wc_InitDsaKey, wc_DsaPrivateKeyDecode
wc_DsaPrivateKeyDecode
Synopsis:
#include <wolfssl/wolfcrypt/dsa.h>
int wc_DsaPrivateKeyDecode(const byte* input, word32* inOutIdx, DsaKey* key,
word32 inSz)
Description:
This function decodes a DER formatted certificate buffer containing a DSA private key, and stores the key in the given DsaKey structure. It also sets the inOutIdx parameter according to the length of the input read.
Return Values:
0: Returned on successfully setting the private key for the DsaKey object
ASN_PARSE_E: Returned if there is an error in the encoding while reading the certificate buffer
ASN_DH_KEY_E: Returned if one of the DSA parameters is incorrectly formatted
Parameters:
input - pointer to the buffer containing the DER formatted DSA private key
inOutIdx - pointer to an integer in which to store the final index of the certificate read
key - pointer to the DsaKey structure in which to store the private key
inSz - size of the input buffer
Example:
int ret, idx=0;
DsaKey key;
wc_InitDsaKey(&key);
byte derBuff[] = { /* DSA private key */ };
ret = wc_DsaPrivateKeyDecode(derBuff, &idx, &key, inSz);
if (ret != 0) {
// error reading private key
}
See Also:
wc_InitDsaKey, wc_DsaPublicKeyDecode
wc_MakeDsaKey
Synopsis:
#include <wolfssl/wolfcrypt/dsa.h>
int wc_MakeDsaKey(WC_RNG *rng, DsaKey *dsa)
Description:
Create a DSA key.
Return Values:
MP_OKAY: Success
BAD_FUNC_ARG: Either rng or dsa is null.
MEMORY_E: Couldn't allocate memory for buffer.
MP_INIT_E: Error initializing mp_int
Parameters:
rng - Pointer to WC_RNG structure.
dsa - Pointer to DsaKey structure.
Example:
WC_RNG rng;
DsaKey dsa;
wc_InitRng(&rng);
wc_InitDsa(&dsa);
if(wc_MakeDsaKey(&rng, &dsa) != 0)
{
/* Error creating key */
}
See Also:
wc_InitDsaKey, wc_FreeDsaKey, wc_DsaSign
wc_MakeDsaParameters
Synopsis:
#include <wolfssl/wolfcrypt/dsa.h>
int wc_MakeDsaParameters(WC_RNG *rng, int modulus_size, DsaKey *dsa)
Description:
FIPS 186-4 defines valid for modulus_size values as (1024, 160) (2048, 256) (3072, 256)
Return Values:
0: Success
BAD_FUNC_ARG: rng or dsa is null or modulus_size is invalid.
MEMORY_E: Error attempting to allocate memory.
Parameters:
rng - pointer to wolfCrypt rng.
modulus_size - 1024, 2048, or 3072 are valid values.
dsa - Pointer to a DsaKey structure.
Example:
DsaKey key;
WC_RNG rng;
wc_InitDsaKey(&key);
wc_InitRng(&rng);
if(wc_MakeDsaParameters(&rng, 1024, &genKey) != 0)
{
/* Handle error */
}
See Also:
wc_MakeDsaKey, wc_DsaKeyToDer, wc_InitDsaKey
wc_DsaKeyToDer
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_DsaKeyToDer(DsaKey* key, byte* output, word32 inLen)
Description:
Convert DsaKey key to DER format, write to output (inLen), return bytes written.
Return Values:
outLen: Success, number of bytes written
BAD_FUNC_ARG: key or output are null or key->type is not DSA_PRIVATE.
MEMORY_E: Error allocating memory.
Parameters:
key - Pointer to DsaKey structure to convert.
output - Pointer to output buffer for converted key.
inLen - Length of key input.
Example:
DsaKey key;
WC_RNG rng;
int derSz;
int bufferSize = /* Sufficient buffer size */;
byte der[bufferSize];
wc_InitDsaKey(&key);
wc_InitRng(&rng);
wc_MakeDsaKey(&rng, &key);
derSz = wc_DsaKeyToDer(&key, der, bufferSize);
See Also:
wc_InitDsaKey, wc_FreeDsaKey, wc_MakeDsaKey
18.15 ECC
wc_ecc_make_key
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_make_key(RNG* rng, int keysize, ecc_key* key);
Description:
This function generates a new ecc_key and stores it in key.
Return Values:
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, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error while computing the ecc key
Parameters:
rng - pointer to an initialized RNG object with which to generate the key
keysize - desired length for the ecc_key
key - pointer to the ecc_key for which to generate a key
Example:
ecc_key key;
wc_ecc_init(&key);
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_shared_secret
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_shared_secret(ecc_key* private_key, ecc_key* public_key, byte* out,
word32* outlen);
Description:
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.
Return Values:
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, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error while computing the shared key
Parameters:
private_key - pointer to the ecc_key structure containing the local private key
public_key - pointer to the ecc_key structure containing the received public key
out - pointer to an output buffer in which to store the generated shared secret key
outlen - pointer to the word32 object containing the length of the output buffer. Will be overwritten with the length written to the output buffer upon successfully generating a shared secret key
Example:
ecc_key priv, pub;
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
}
See Also:
wc_ecc_init, wc_ecc_make_key
wc_ecc_sign_hash
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_sign_hash(const byte* in, word32 inlen, byte* out, word32 *outlen, RNG* rng,
ecc_key* key)
Description:
This function signs a message digest using an ecc_key object to guarantee authenticity.
Return Values:
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, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error while computing the message signature
Parameters:
in - pointer to the buffer containing the message hash to sign
inlen - length of the message hash to sign
out - buffer in which to store the generated signature
outlen - max length of the output buffer. Will store the bytes written to out upon successfully generating a message signature
key - pointer to a private ECC key with which to generate the signature
Example:
ecc_key key;
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
}
See Also:
wc_ecc_verify_hash
wc_ecc_verify_hash
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_verify_hash(const byte* sig, word32 siglen, const byte* hash, word32 hashlen,
int* stat, ecc_key* key);
Description:
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.
Return Values:
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, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error while computing the message signature
Parameters:
sig - pointer to the buffer containing the signature to verify
siglen - length of the signature to verify
hash - pointer to the buffer containing the hash of the message verified
hashlen - length of the hash of the message verified
stat - pointer to the result of the verification. 1 indicates the message was successfully verified
key - pointer to a public ECC key with which to verify the signature
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
}
See Also:
wc_ecc_sign_hash, wc_ecc_verify_hash_ex
wc_ecc_init
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_init(ecc_key* key);
Description:
This function initializes an ecc_key object for future use with message verification or key negotiation.
Return Values:
0: Returned upon successfully initializing the ecc_key object
MEMORY_E: Returned if there is an error allocating memory
Parameters:
key - pointer to the ecc_key object to initialize
Example:
ecc_key key;
wc_ecc_init(&key);
See Also:
wc_ecc_make_key, wc_ecc_free
wc_ecc_free
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
void wc_ecc_free(ecc_key* key)
Description:
This function frees an ecc_key object after it has been used.
Return Values:
No return value for this function.
Parameters:
key - pointer to the ecc_key object to free
Example:
ecc_key key;
// initialize key and perform secure exchanges
...
wc_ecc_free(&key);
See Also:
wc_ecc_init
wc_ecc_fp_free
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
void wc_ecc_fp_free(void);
Description:
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.
Return Values:
No return value for this function.
Parameters:
No parameters for this function.
Example:
ecc_key key;
// initialize key and perform secure exchanges
...
wc_ecc_fp_free();
See Also:
wc_ecc_free
wc_ecc_export_x963
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_export_x963(ecc_key* key, byte* out, word32* outLen);
Description:
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.
Return Values:
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, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error processing the ecc_key
Parameters:
key - pointer to the ecc_key object to export
out - pointer to the buffer in which to store the ANSI X9.63 formatted key
outLen - size of the output buffer. On successfully storing the key, will hold the bytes written to the output buffer
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
}
See Also:
wc_ecc_export_x963_ex, wc_ecc_import_x963
wc_ecc_export_x963_ex
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_export_x963_ex(ecc_key* key, byte* out, word32* outLen, int compressed);
Description:
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.
Return Values:
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, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error processing the ecc_key
Parameters:
key - pointer to the ecc_key object to export
out - pointer to the buffer in which to store the ANSI X9.63 formatted key
outLen - size of the output buffer. On successfully storing the key, will hold the bytes written to the output buffer
compressed - indicator 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
}
See Also:
wc_ecc_export_x963, wc_ecc_import_x963
wc_ecc_import_x963
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_import_x963(const byte* in, word32 inLen, ecc_key* key);
Description:
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.
Return Values:
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, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error processing the ecc_key
Parameters:
in - pointer to the buffer containing the ANSI x9.63 formatted ECC key
inLen - length of the input buffer
key - pointer to the ecc_key object in which to store the imported key
Example:
int ret;
byte buff[] = { /* initialize with ANSI X9.63 formatted key */ };
ecc_key pubKey;
wc_ecc_init_key(&pubKey);
ret = wc_ecc_import_x963(buff, sizeof(buff), &pubKey);
if ( ret != 0) {
// error importing key
}
See Also:
wc_ecc_export_x963, wc_ecc_import_private_key
wc_ecc_import_private_key
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_import_private_key(const byte* priv, word32 privSz, const byte* pub,
word32 pubSz, ecc_key* key)
Description:
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.
Return Values:
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, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error processing the ecc_key
Parameters:
priv - pointer to the buffer containing the raw private key
privSz - size of the private key buffer
pub - pointer to the buffer containing the ANSI x9.63 formatted ECC public key
pubSz - length of the public key input buffer
key - pointer to the ecc_key object in which to store the imported private/public key pair
Example:
int ret;
byte pub[] = { /* initialize with ANSI X9.63 formatted key */ };
byte priv[] = { /* initialize with the raw private key*/ };
ecc_key key;
wc_ecc_init_key(&key);
ret = wc_ecc_import_private_key(priv, sizeof(priv), pub, sizeof(pub), &key);
if ( ret != 0) {
// error importing key
}
See Also:
wc_ecc_export_x963, wc_ecc_import_private_key
wc_ecc_rs_to_sig
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_rs_to_sig(const char* r, const char* s, byte* out, word32* outlen)
Description:
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.
Return Values:
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, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error processing the ecc_key
Parameters:
r - pointer to the buffer containing the R portion of the signature as a string
s - pointer to the buffer containing the S portion of the signature as a string
out - pointer to the buffer in which to store the DER-encoded ECDSA signature
outlen - length of the output buffer available. Will store the bytes written to the buffer after successfully converting the signature to ECDSA format
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
}
See Also:
wc_ecc_sign_hash, wc_ecc_sig_size
wc_ecc_import_raw
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_import_raw(ecc_key* key, const char* qx, const char* qy, const char* d,
const char* curveName);
Description:
This function fills an ecc_key structure with the raw components of an ECC signature.
Return Values:
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, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error processing the input parameters
Parameters:
key - pointer to an ecc_key structure to fill
qx - pointer to a buffer containing the x component of the base point as an ASCII hex string
qy - pointer to a buffer containing the y component of the base point as an ASCII hex string
d - pointer to a buffer containing the private key as an ASCII hex string
curveName - pointer to a string containing the ECC curve name, as found in ecc_sets
Example:
int ret;
ecc_key key;
wc_ecc_init(&key);
char qx[] = { /* initialize with x component of base point */ };
char qy[] = { /* initialize with y component of base point */ };
char d[] = { /* initialize with private key */ };
ret = wc_ecc_import_raw(&key,qx, qy, d, "ECC-256");
if ( ret != 0) {
// error initializing key with given inputs
}
See Also:
wc_ecc_import_private_key
wc_ecc_export_private_only
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_export_private_only(ecc_key* key, byte* out, word32* outLen);
Description:
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.
Return Values:
0: Returned upon successfully exporting the private key
ECC_BAD_ARG_E: Returned if any of the input values evaluate to NULL, or the key's index is invalid
BUFFER_E: Returned if the buffer provided is not large enough to store the private key
MP_INIT_E, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error storing the private key in the given buffer
Parameters:
key - pointer to an ecc_key structure from which to export the private key
out - pointer to the buffer in which to store the private key
outLen - pointer to a word32 object with the size available in out. Set with the number of bytes written to out after successfully exporting the private key
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
}
See Also:
wc_ecc_import_private_key
wc_ecc_size
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_size(ecc_key* key);
Description:
This function returns the key size of an ecc_key structure in octets.
Return Values:
Given a valid key, returns the key size in octets
0: Returned if the given key is NULL
Parameters:
key - pointer 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
}
See Also:
wc_ecc_make_key
wc_ecc_sig_size
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_sig_size(ecc_key* key);
Description:
This function returns the worst case size for an ECC signature, given by:
keySz * 2 + SIG_HEADER_SZ + 4
The actual signature size can be computed with wc_ecc_sign_hash.
Return Values:
Given a valid key, returns the maximum signature size, in octets
0: Returned if the given key is NULL
Parameters:
key - pointer 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_ctx_new
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
ecEncCtx* wc_ecc_ctx_new(int flags, RNG* rng);
Description:
This function allocates and initializes space for a new ECC context object to allow secure message exchange with ECC.
Return Values:
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:
flags - indicate whether this is a server or client context
Options are: REQ_RESP_CLIENT, and REQ_RESP_SERVER
rng - pointer to a RNG object with which to generate a salt
Example:
ecEncCtx* ctx;
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_decrypt
wc_ecc_ctx_free
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
void wc_ecc_ctx_free(ecEncCtx* ctx)
Description:
This function frees the ecEncCtx object used for encrypting and decrypting messages.
Return Values:
No return values for this function
Parameters:
ctx - pointer to the ecEncCtx object to free
Example:
ecEncCtx* ctx;
RNG rng;
wc_InitRng(&rng);
ctx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng);
// do secure communication
...
wc_ecc_ctx_free(&ctx);
See Also:
wc_ecc_ctx_new
wc_ecc_ctx_reset
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_ctx_reset(ecEncCtx* ctx, RNG* rng);
Description:
This function resets an ecEncCtx structure to avoid having to free and allocate a new context object.
Return Values:
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:
ctx - pointer to the ecEncCtx object to reset
rng - pointer to an RNG object with which to generate a new salt
Example:
ecEncCtx* ctx;
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_get_own_salt
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
const byte* wc_ecc_ctx_get_own_salt(ecEncCtx* ctx);
Description:
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.
Return Values:
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:
ctx - pointer to the ecEncCtx object from which to get the salt
Example:
ecEncCtx* ctx;
RNG rng;
const byte* salt;
wc_InitRng(&rng);
ctx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng);
salt = wc_ecc_ctx_get_own_salt(&ctx);
if(salt == NULL) {
// error getting salt
}
See Also:
wc_ecc_ctx_new, wc_ecc_ctx_set_peer_salt
wc_ecc_ctx_set_peer_salt
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_ctx_set_peer_salt(ecEncCtx* ctx, const byte* salt);
Description:
This function sets the peer salt of an ecEncCtx object.
Return Values:
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:
ctx - pointer to the ecEncCtx for which to set the salt
salt - pointer to the peer's salt
Example:
ecEncCtx* cliCtx, srvCtx;
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);
See Also:
wc_ecc_ctx_get_own_salt
wc_ecc_ctx_set_info
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_ctx_set_info(ecEncCtx* ctx, const byte* info, int sz);
Description:
This function can optionally be called before or after wc_ecc_ctx_set_peer_salt. It sets optional information for an ecEncCtx object.
Return Values:
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:
ctx - pointer to the ecEncCtx for which to set the info
info - pointer to a buffer containing the info to set
sz - size of the info buffer
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
}
See Also:
wc_ecc_ctx_new
wc_ecc_encrypt
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_encrypt(ecc_key* privKey, ecc_key* pubKey, const byte* msg, word32 msgSz,
byte* out, word32* outSz, ecEncCtx* ctx);
Description:
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.
Return Values:
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:
privKey - pointer to the ecc_key object containing the private key to use for encryption
pubKey - pointer to the ecc_key object containing the public key of the peer with whom one wishes to communicate
msg- pointer to the buffer holding the message to encrypt
msgSz - size of the buffer to encrypt
out - pointer to the buffer in which to store the encrypted ciphertext
outSz - pointer to a word32 object containing the available size in the out buffer. Upon successfully encrypting the message, holds the number of bytes written to the output buffer
ctx - Optional: pointer to an ecEncCtx object specifying different encryption algorithms to use
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
}
See Also:
wc_ecc_decrypt
wc_ecc_decrypt
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_decrypt(ecc_key* privKey, ecc_key* pubKey, const byte* msg, word32 msgSz,
byte* out, word32* outSz, ecEncCtx* ctx);
Description:
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.
Return Values:
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:
privKey - pointer to the ecc_key object containing the private key to use for decryption
pubKey - pointer to the ecc_key object containing the public key of the peer with whom one wishes to communicate
msg- pointer to the buffer holding the ciphertext to decrypt
msgSz - size of the buffer to decrypt
out - pointer to the buffer in which to store the decrypted plaintext
outSz - pointer to a word32 object containing the available size in the out buffer. Upon successfully decrypting the ciphertext, holds the number of bytes written to the output buffer
ctx - Optional: pointer to an ecEncCtx object specifying different decryption algorithms to use
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
}
See Also:
Wc_ecc_encrypt
wc_ecc_del_point
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
void wc_ecc_del_point(ecc_point* p);
Description:
Free an ECC point from memory.
Return Values:
Parameters:
p - The point to free.
Example:
ecc_point* point;
point = wc_ecc_new_point();
if (point == NULL)
{
/* Handle point creation error */
}
/* Do stuff with point */
wc_ecc_del_point(point);
See Also:
wc_ecc_new_point
wc_ecc_cmp_point
wc_ecc_copy_point
wc_ecc_point_is_at_infinity
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_point_is_at_infinity(ecc_point* p);
Description:
Checks if a point is at infinity. Returns 1 if point is at infinity, 0 if not, < 0 on error
Return Values:
1: p is at infinity.
0: p is not at infinity.
< 0: Error.
Parameters:
p - The 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 */
}
See Also:
wc_ecc_new_point
wc_ecc_del_point
wc_ecc_cmp_point
wc_ecc_copy_point
wc_ecc_sign_hash_ex
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_sign_hash_ex(const byte* in, word32 inlen, WC_RNG* rng,
ecc_key* key, mp_int *r, mp_int *s)
Description:
Sign a message digest.
Return Values:
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, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM: may be returned if there is an error while computing the message signature
Parameters:
in - The message digest to sign.
inlen - The length of the digest.
rng - Pointer to WC_RNG struct.
key - A private ECC key.
r - The destination for r component of the signature.
s - The destination for s component of the signature.
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
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
}
See Also:
wc_ecc_verify_hash_ex
wc_ecc_copy_point
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_copy_point(ecc_point* p, ecc_point *r);
Description:
Copy the value of one point to another one.
Return Values:
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:
p - The point to copy.
r - The 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 */
}
See Also:
wc_ecc_new_point
wc_ecc_cmp_point
wc_ecc_del_point
wc_ecc_shared_secret_ssh
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_shared_secret_ssh(ecc_key* private_key, ecc_point* point,
byte* out, word32 *outlen);
Description:
Create an ECC shared secret between private key and public point.
Return Values:
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, and MP_MEM possible when an initialization failure occurs.
Parameters:
private_key - The private ECC key.
point - The point to use (public key).
out - Output destination of the shared secret. Conforms to EC-DH from ANSI X9.63.
outlen - Input the max size and output the resulting size of the shared secret.
Example:
ecc_key key;
ecc_point* point;
byte shared_secret[];
int secret_size; /* set size */
int result;
point = wc_ecc_new_point();
result = wc_ecc_shared_secret_ssh(&key, point, &shared_secret, &secret_size);
if (result != MP_OKAY)
{
/* Handle error */
}
See Also:
wc_ecc_verify_hash_ex
wc_ecc_new_point
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
ecc_point* wc_ecc_new_point(void);
Description:
Allocate a new ECC point.
Return Values:
p: A newly allocated point.
NULL: Returns NULL on error.
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_import_point_der
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_import_point_der(byte* in, word32 inLen, const int curve_idx,
ecc_point* point);
Description:
Import point from der format.
Return Values:
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:
in - der buffer to import point from.
inLen - Length of der buffer.
curve_idx - Index of curve.
point - Destination for point.
Example:
byte in[];
word32 inLen;
int curve_idx;
ecc_point* point;
wc_ecc_import_point_der(in, inLen, curve_idx, point);
See Also:
wc_ecc_export_point_der
wc_ecc_export_point_der
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_export_point_der(const int curve_idx, ecc_point* point, byte* out,
word32* outLen)
Description:
Export point to der.
Return Values:
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_idx - Index of the curve used from ecc_sets.
point - Point to export to der.
out - Destination for the output.
outLen - Maxsize allowed for output, destination for final size of output
Example:
int curve_idx;
ecc_point* point;
byte out[];
word32 outLen;
wc_ecc_export_point_der(curve_idx, point, out, &outLen);
See Also:
wc_ecc_import_point_der
wc_ecc_verify_hash_ex
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_verify_hash_ex(mp_int *r, mp_int *s, const byte* hash,
word32 hashlen, int* stat, ecc_key* key);
Description:
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.
Return Values:
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:
r - The signature R component to verify
s - The signature S component to verify
hash - The hash (message digest) that was signed
hashlen - The length of the hash (octets)
stat - Result of signature, 1==valid, 0==invalid
key - The corresponding public ECC key
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
wc_ecc_is_valid_idx
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_is_valid_idx(int n);
Description:
Checks if an ECC idx is valid.
Return Values:
1: Return if valid.
0: Return if not valid.
Parameters:
n - The idx number to check.
Example:
ecc_key key;
RNG rng;
int is_valid;
wc_ecc_init(&key);
wc_InitRng(&rng);
wc_ecc_make_key(&rng, 32, &key);
is_valid = wc_ecc_is_valid_idx(key.idx);
if (is_valid == 1)
{
/* idx is valid */
}
else if (is_valid == 0)
{
/* idx is not valid */
}
See Also:
wc_ecc_check_key
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_check_key(ecc_key* key);
Description:
Perform sanity checks on ecc key validity.
Return Values:
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:
key - Pointer to key to check.
Example:
ecc_key key;
RNG rng;
int check_result;
wc_ecc_init(&key);
wc_InitRng(&rng);
wc_ecc_make_key(&rng, 32, &key);
check_result = wc_ecc_check_key(&key);
if (check_result == MP_OKAY)
{
/* key check succeeded */
}
else
{
/* key check failed */
}
See Also:
wc_ecc_point_is_at_infinity
wc_ecc_cmp_point
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_cmp_point(ecc_point* a, ecc_point *b);
Description:
Compare the value of a point with another one.
Return Values:
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:
a - First point to compare.
b - Second 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 */
}
See Also:
wc_ecc_new_point
wc_ecc_del_point
wc_ecc_copy_point
wc_ecc_mulmod
Synopsis:
#include <wolfssl/wolfcrypt/ecc.h>
int wc_ecc_mulmod(mp_int* k, ecc_point *G, ecc_point *R, mp_int* modulus,
int map);
Description:
Perform ECC Fixed Point multiplication.
Return Values:
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:
k - The multiplicand.
G - Base point to multiply.
R - Destination of product.
modulus - The modulus for the curve.
map - If non-zero maps the point back to affine coordinates, otherwise it's left in jacobian-montgomery form.
Example:
ecc_point* base;
ecc_point* destination;
/* Initialize points */
base = wc_ecc_new_point();
destination = wc_ecc_new_point();
/* Setup other arguments */
mp_int multiplicand;
mp_int modulus;
int map;
if(wc_ecc_mulmod(&multiplicand, base, destination, &modulus, map) == MP_OKAY)
{
/* Successful operation */
}
See Also:
18.16 Ed25519
wc_ed25519_make_key
Synopsis:
#include <wolfssl/wolfcrypt/ed25519.h>
int wc_ed25519_make_key(RNG* rng, int keySz, ed25519_key* key);
Description:
This function generates a new ed25519_key and stores it in key.
Return Values:
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);
RNG rng;
wc_InitRng(&rng);
wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key
See Also:
wc_ed25519_init
wc_ed25519_sign_msg
Synopsis:
#include <wolfssl/wolfcrypt/ed25519.h>
int wc_ed25519_sign_msg(const byte* in, word32 inlen, byte* out, word32 *outlen,
ed25519_key* key);
Description:
This function signs a message digest using an ed25519_key object to guarantee authenticity.
Return Values:
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;
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_verify_msg
Synopsis:
#include <wolfssl/wolfcrypt/ed25519.h>
int wc_ed25519_verify_msg(byte* sig, word32 siglen, const byte* msg, word32 msglen,
int* stat, ed25519_key* key);
Description:
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.
Return Values:
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
wc_ed25519_init
Synopsis:
#include <wolfssl/wolfcrypt/ed25519.h>
int wc_ed25519_init(ed25519_key* key);
Description:
This function initializes an ed25519_key object for future use with message verification.
Return Values:
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_free
Synopsis:
#include <wolfssl/wolfcrypt/ed25519.h>
void wc_ed25519_free(ed25519_key* key);
Description:
This function frees an ed25519 object after it has been used.
Return Values:
No return value for this function.
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_public
Synopsis:
#include <wolfssl/wolfcrypt/ed25519.h>
int wc_ed25519_import_public(const byte* in, word32 inLen, ed25519_key* key);
Description:
This function imports a public ed25519_key pair from a buffer containing the public key. This function will handle both compressed and uncompressed keys.
Return Values:
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_import_private_key
Synopsis:
#include <wolfssl/wolfcrypt/ed25519.h>
int wc_ed25519_import_private_key(const byte* priv, word32 privSz, const byte* pub,
word32 pubSz, ed25519_key* key);
Description:
This function imports a public/private ed25519 key pair from a pair of buffers. This function will handle both compressed and uncompressed keys.
Return Values:
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_export_public
Synopsis:
#include <wolfssl/wolfcrypt/ed25519.h>
int wc_ed25519_export_public(ed25519_key* key, byte* out, word32* outLen);
Description:
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.
Return Values:
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_export_private_only
Synopsis:
#include <wolfssl/wolfcrypt/ed25519.h>
int wc_ed25519_export_private_only(ed25519_key* key, byte* out, word32* outLen);
Description:
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.
Return Values:
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_size
Synopsis:
#include <wolfssl/wolfcrypt/ed25519.h>
int wc_ed25519_size(ed25519_key* key);
Description:
This function returns the key size of an ed25519_key structure, or 32 bytes.
Return Values:
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_sig_size
Synopsis:
#include <wolfssl/wolfcrypt/ed25519.h>
int wc_ed25519_sig_size(ed25519_key* key);
Description:
This function returns the size of an ed25519 signature (64 in bytes).
Return Values:
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_pub_size
Synopsis:
#include <wolfssl/wolfcrypt/ed25519.h>
int wc_ed25519_pub_size(ed25519_key* key)
Description:
Returns the compressed key size in bytes (public key).
Return Values:
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);
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_priv_size
Synopsis:
#include <wolfssl/wolfcrypt/ed25519.h>
int wc_ed25519_priv_size(ed25519_key* key);
Description:
Returns the private key size (secret + public) in bytes.
Return Values:
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);
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_export_private
Synopsis:
#include <wolfssl/wolfcrypt/ed25519.h>
int wc_ed25519_export_private(ed25519_key* key, byte* out, word32* outLen);
Description:
Export the private key, including public part.
Return Values:
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);
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:
wc_ed25519_export_key
Synopsis:
#include <wolfssl/wolfcrypt/ed25519.h>
int wc_ed25519_export_key(ed25519_key* key,
byte* priv, word32 *privSz,
byte* pub, word32 *pubSz);
Description:
Export full private key and public key.
Return Values:
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
18.17 Error Handling
wc_ErrorString
Synopsis:
#include <wolfssl/wolfcrypt/error-crypt.h>
void wc_ErrorString(int error, char* buffer);
Description:
This function stores the error string for a particular error code in the given buffer.
Return Values:
No return values for this function.
Parameters:
error - error code for which to get the string
buffer - buffer in which to store the error string. Buffer should be at least WOLFSSL_MAX_ERROR_SZ (80 bytes) long
Example:
char errorMsg[WOLFSSL_MAX_ERROR_SZ];
int err = wc_some_function();
if( err != 0) { // error occurred
wc_ErrorString(err, errorMsg);
}
See Also:
wc_GetErrorString
wc_GetErrorString
Synopsis:
#include <wolfssl/wolfcrypt/error-crypt.h>
const char* wc_GetErrorString(int error)
Description:
This function returns the error string for a particular error code.
Return Values:
Returns the error string for an error code as a string literal.
Parameters:
error - error code for which to get the string
Example:
char * errorMsg;
int err = wc_some_function();
if( err != 0) { // error occurred
errorMsg = wc_GetErrorString(err);
}
See Also:
wc_ErrorString
18.18 HC-128
wc_Hc128_Process
Synopsis:
#include <wolfssl/wolfcrypt/hc128.h>
int wc_Hc128_Process(HC128* ctx, byte* output, const byte* input, word32 msglen);
Description:
This function encrypts or decrypts a message of any size from the input buffer input, and stores the resulting plaintext/ciphertext in the output buffer output.
Return Values:
0: Returned upon successfully encrypting/decrypting the given input
When XSTREAM_ALIGN is defined, the following may be returned:
MEMORY_E: Returned if the input and output buffers are not aligned along a 4-byte boundary, and there is an error allocating memory
BAD_ALIGN_E: Returned if the input or output buffers are not aligned along a 4-byte boundary, and NO_WOLFSSL_ALLOC_ALIGN is defined
Parameters:
ctx - pointer to a HC-128 context object with an initialized key to use for encryption or decryption
output - buffer in which to store the processed input
input - buffer containing the plaintext to encrypt or the ciphertext to decrypt
msglen - length of the plaintext to encrypt or the ciphertext to decrypt
Example:
HC128 enc;
byte key[] = { /* initialize with key */ };
byte iv[] = { /* initialize with iv */ };
wc_Hc128_SetKey(&enc, key, iv);
byte msg[] = { /* initialize with message */ };
byte cipher[sizeof(msg)];
if (wc_Hc128_Process(*enc, cipher, plain, sizeof(plain)) != 0) {
// error encrypting msg
}
See Also:
wc_Hc128_SetKey
wc_Hc128_SetKey
Synopsis:
#include <wolfssl/wolfcrypt/hc128.h>
int wc_Hc128_SetKey(HC128* ctx, const byte* key, const byte* iv);
Description:
This function initializes an HC128 context object by setting its key and iv.
Return Values:
0: Returned upon successfully setting the key and iv for the HC128 context object
Parameters:
ctx - pointer to an HC-128 context object to initialize
key - pointer to the buffer containing the 16 byte key to use with encryption/decryption
iv - pointer to the buffer containing the 16 byte iv (nonce) with which to initialize the HC128 object
Example:
HC128 enc;
byte key[] = { /* initialize with key */ };
byte iv[] = { /* initialize with iv */ };
wc_Hc128_SetKey(&enc, key, iv);
See Also:
wc_Hc128_Process
18.19 HMAC
wc_HmacSetKey
Synopsis:
#include <wolfssl/wolfcrypt/hmac.h>
int wc_HmacSetKey(Hmac* hmac, int type, const byte* key, word32 length);
Description:
This function initializes an Hmac object, setting its encryption type, key and HMAC length.
Return Values:
0: Returned on successfully initializing the Hmac object
BAD_FUNC_ARG: Returned if the input type is invalid. Valid options are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID
MEMORY_E: Returned if there is an error allocating memory for the structure to use for hashing
HMAC_MIN_KEYLEN_E: May be returned when using a FIPS implementation and the key length specified is shorter than the minimum acceptable FIPS standard
Parameters:
hmac - pointer to the Hmac object to initialize
type - type specifying which encryption method the Hmac object should use. Valid options are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID
key - pointer to a buffer containing the key with which to initialize the Hmac object
length - length of the key
Example:
Hmac hmac;
byte key[] = { /* initialize with key to use for encryption */ };
if (wc_HmacSetKey(&hmac, MD5, key, sizeof(key)) != 0) {
// error initializing Hmac object
}
See Also:
wc_HmacUpdate, wc_HmacFinal
wc_HmacUpdate
Synopsis:
#include <wolfssl/wolfcrypt/hmac.h>
int wc_HmacUpdate(Hmac* hmac, const byte* msg, word32 length);
Description:
This function updates the message to authenticate using HMAC. It should be called after the Hmac object has been initialized with wc_HmacSetKey. This function may be called multiple times to update the message to hash. After calling wc_HmacUpdate as desired, one should call wc_HmacFinal to obtain the final authenticated message tag.
Return Values:
0: Returned on successfully updating the message to authenticate
MEMORY_E: Returned if there is an error allocating memory for use with a hashing algorithm
Parameters:
hmac - pointer to the Hmac object for which to update the message
msg - pointer to the buffer containing the message to append
length - length of the message to append
Example:
Hmac hmac;
byte msg[] = { /* initialize with message to authenticate */ };
byte msg2[] = { /* initialize with second half of message */ };
// initialize hmac
if( wc_HmacUpdate(&hmac, msg, sizeof(msg)) != 0) {
// error updating message
}
if( wc_HmacUpdate(&hmac, msg2, sizeof(msg)) != 0) {
// error updating with second message
}
See Also:
wc_HmacSetKey, wc_HmacFinal
wc_HmacFinal
Synopsis:
#include <wolfssl/wolfcrypt/hmac.h>
int wc_HmacFinal(Hmac* hmac, byte* hash);
Description:
This function computes the final hash of an Hmac object's message.
Return Values:
0: Returned on successfully computing the final hash
MEMORY_E: Returned if there is an error allocating memory for use with a hashing algorithm
Parameters:
hmac - pointer to the Hmac object for which to calculate the final hash
hash - pointer to the buffer in which to store the final hash. Should have room available as required by the hashing algorithm chosen
Example:
Hmac hmac;
byte hash[MD5_DIGEST_SIZE];
// initialize hmac with MD5 as type
// wc_HmacUpdate() with messages
if (wc_HmacFinal(&hmac, hash) != 0) {
// error computing hash
}
See Also:
wc_HmacSetKey, wc_HmacUpdate
wc_HmacInitCavium
Synopsis:
#include <wolfssl/wolfcrypt/hmac.h>
int wc_HmacInitCavium(Hmac* hmac, int devId)
Description:
This function initializes HMAC for use with Cavium Nitrox devices. It should be called before wc_HmacSetKey when using Cavium hardware cryptography.
Return Values:
0: On successfully initializing Cavium
-1: Returned if the Hmac structure is NULL, or the call to CspAllocContext fails
Parameters:
hmac - pointer to the Hmac object for which to initialize Cavium
devId - Nitrox device id
Example:
Hmac hmac;
if(wc_HmacInitCavium(&hmac, CAVIUM_DEVICE_ID) != 0) {
// error initializing device for harware crypto
}
See Also:
wc_HmacFreeCavium
wc_HmacFreeCavium
Synopsis:
#include <wolfssl/wolfcrypt/hmac.h>
void wc_HmacFreeCavium(Hmac* hmac);
Description:
This function frees HMAC from use with Cavium Nitrox devices.
Return Values:
No return values for this function.
Parameters:
hmac - pointer to the Hmac object to free
Example:
Hmac hmac;
wc_HmacInitCavium(&hmac, CAVIUM_DEVICE_ID) != 0); // initialize Cavium
/* init HMAC, set key *
* perform encryption */
wc_HmacFreeCavium(&hmac); // free Cavium
See Also:
wc_HmacInitCavium
wolfSSL_GetHmacMaxSize
Synopsis:
#include <wolfssl/wolfcrypt/hmac.h>
int wolfSSL_GetHmacMaxSize(void);
Description:
This function returns the largest HMAC digest size available based on the configured cipher suites.
Return Values:
Returns the largest HMAC digest size available based on the configured cipher suites
Parameters:
No parameters for this function.
Example:
int maxDigestSz = wolfSSL_GetHmacMaxSize();
See Also:
wc_HKDF
Synopsis:
#include <wolfssl/wolfcrypt/hmac.h>
int wc_HKDF(int type, const byte* inKey, word32 inKeySz, const byte* salt, word32 saltSz,
const byte* info, word32 infoSz, byte* out, word32 outSz);
Description:
This function provides access to a HMAC Key Derivation Function (HKDF). It utilizes HMAC to convert inKey, with an optional salt and optional info into a derived key, which it stores in out. The hash type defaults to MD5 if 0 or NULL is given.
Return Values:
0: Returned upon successfully generating a key with the given inputs
BAD_FUNC_ARG: Returned if an invalid hash type is given as argument. Valid types are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID
MEMORY_E: Returned if there is an error allocating memory
HMAC_MIN_KEYLEN_E: May be returned when using a FIPS implementation and the key length specified is shorter than the minimum acceptable FIPS standard
Parameters:
type - hash type to use for the HKDF. Valid types are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID
inKey - pointer to the buffer containing the key to use for KDF
inKeySz - length of the input key
salt - pointer to a buffer containing an optional salt. Use NULL instead if not using a salt
saltSz - length of the salt. Use 0 if not using a salt
info - pointer to a buffer containing optional additional info. Use NULL if not appending extra info
infoSz - length of additional info. Use 0 if not using additional info
out - pointer to the buffer in which to store the derived key
outSz - space available in the output buffer to store the generated key
Example:
byte key[] = { /* initialize with key */ };
byte salt[] = { /* initialize with salt */ };
byte derivedKey[MAX_DIGEST_SIZE];
int ret = wc_HKDF(SHA512, key, sizeof(key), salt, sizeof(salt),
NULL, 0, derivedKey, sizeof(derivedKey));
if ( ret != 0 ) {
// error generating derived key
}
See Also:
wc_HmacSetKey
18.20 Random Number Generation
wc_InitRngCavium
Synopsis:
#include <wolfssl/wolfcrypt/random.h>
int wc_InitRngCavium(RNG* rng, int devId);
Description:
Initializes RNG for use with Nitrox device. HAVE_CAVIUM Must be set for use.
Return Values:
-1: rng is NULL
0: Success
Parameters:
RNG* rng: random number generator to be initialized with a Nitrox device. Regular wc_InitRng should happen afterwards
int devId: nitrox device id
Example:
#ifdef HAVE_CAVIUM
ret = wc_InitRngCavium(&rng, CAVIUM_DEV_ID);
if (ret != 0)
printf(“RNG Nitrox init for device: %d failed”, CAVIUM_DEV_ID);
#endif
See also:
wc_InitRng, wc_RNG_GenerateBlock, wc_RNG_GenerateByte, wc_FreeRng, wc_RNG_HealthTest
wc_InitRng
Synopsis:
#include <wolfssl/wolfcrypt/random.h>
int wc_InitRng(RNG* rng);
Description:
Gets the seed (from OS) and key cipher for rng. rng->drbg (deterministic random bit generator) allocated (should be deallocated with wc_FreeRng). This is a blocking operation.
Return Values:
0: on success.
MEMORY_E: XMALLOC failed
WINCRYPT_E: wc_GenerateSeed: failed to acquire context
CRYPTGEN_E: wc_GenerateSeed: failed to get random
BAD_FUNC_ARG: wc_RNG_GenerateBlock input is null or sz exceeds MAX_REQUEST_LEN
DRBG_CONT_FIPS_E: wc_RNG_GenerateBlock: Hash_gen returned DRBG_CONT_FAILURE
RNG_FAILURE_E: wc_RNG_GenerateBlock: Default error. rng’s status originally not ok, or set to DRBG_FAILED
Parameters:
RNG* rng: random number generator to be initialized for use with a seed and key cipher
Example:
RNG rng;
int ret;
#ifdef HAVE_CAVIUM
ret = wc_InitRngCavium(&rng, CAVIUM_DEV_ID);
if (ret != 0){
printf(“RNG Nitrox init for device: %d failed”, CAVIUM_DEV_ID);
return -1;
}
#endif
ret = wc_InitRng(&rng);
if (ret != 0){
printf(“RNG init failed”);
return -1;
}
See also:
wc_InitRngCavium, wc_RNG_GenerateBlock, wc_RNG_GenerateByte, wc_FreeRng, wc_RNG_HealthTest
wc_RNG_GenerateBlock
Synopsis:
#include <wolfssl/wolfcrypt/random.h>
int wc_RNG_GenerateBlock(RNG* rng, byte* output, word32 sz);
Description:
Copies a sz bytes of pseudorandom data to output. Will reseed rng if needed (blocking).
Return Values:
0: on success
BAD_FUNC_ARG: an input is null or sz exceeds MAX_REQUEST_LEN
DRBG_CONT_FIPS_E: Hash_gen returned DRBG_CONT_FAILURE
RNG_FAILURE_E: Default error. rng’s status originally not ok, or set to DRBG_FAILED
Parameters:
RNG* rng: random number generator initialized with wc_InitRng
byte* output: buffer to which the block is copied
word32 sz: size of output in bytes
Example:
RNG rng;
int sz = 32;
byte block[sz];
int ret = wc_InitRng(&rng);
if (ret != 0) return -1; //init of rng failed!
ret = wc_RNG_GenerateBlock(&rng, block, sz);
if (ret != 0) return -1; //generating block failed!
See also:
wc_InitRngCavium, wc_InitRng, wc_RNG_GenerateByte, wc_FreeRng, wc_RNG_HealthTest
wc_RNG_GenerateByte
Synopsis:
#include <wolfssl/wolfcrypt/random.h>
int wc_RNG_GenerateByte(RNG* rng, byte* b);
Description:
Calls wc_RNG_GenerateBlock to copy a byte of pseudorandom data to b. Will reseed rng if needed.
Return Values:
0: on success
BAD_FUNC_ARG: an input is null or sz exceeds MAX_REQUEST_LEN
DRBG_CONT_FIPS_E: Hash_gen returned DRBG_CONT_FAILURE
RNG_FAILURE_E: Default error. rng’s status originally not ok, or set to DRBG_FAILED
Parameters:
RNG* rng: random number generator initialized with wc_InitRng
byte* b: one byte buffer to which the block is copied
Example:
RNG rng;
int sz = 32;
byte b[1];
int ret = wc_InitRng(&rng);
if (ret != 0) return -1; //init of rng failed!
ret = wc_RNG_GenerateByte(&rng, b);
if (ret != 0) return -1; //generating block failed!
See also:
wc_InitRngCavium, wc_InitRng, wc_RNG_GenerateBlock, wc_FreeRng, wc_RNG_HealthTest
wc_FreeRng
Synopsis:
#include <wolfssl/wolfcrypt/random.h>
int wc_FreeRng(RNG* rng);
Description:
Should be called when RNG no longer needed in order to securely free drgb. Zeros and XFREEs rng-drbg.
Return Values:
0: on success
BAD_FUNC_ARG: rng or rng->drgb null
RNG_FAILURE_E: Failed to deallocated drbg
Parameters:
RNG* rng: random number generator initialized with wc_InitRng
Example:
RNG rng;
int ret = wc_InitRng(&rng);
if (ret != 0) return -1; //init of rng failed!
int ret = wc_FreeRng(&rng);
if (ret != 0) return -1; //free of rng failed!
See also:
wc_InitRngCavium, wc_InitRng, wc_RNG_GenerateBlock, wc_RNG_GenerateByte, wc_RNG_HealthTest
wc_RNG_HealthTest
Synopsis:
#include <wolfssl/wolfcrypt/random.h>
int wc_RNG_HealthTest(int reseed, const byte* entropyA, word32 entropyASz,
const byte* entropyB, word32 entropyBSz,
byte* output, word32 outputSz);
Description:
Creates and tests functionality of drbg.
Return Values:
0: on success
BAD_FUNC_ARG: entropyA and output must not be null. If reseed set entropyB must not be null
-1: test failed
Parameters:
int reseed: if set, will test reseed functionality
const byte* entropyA: entropy to instantiate drgb with
word32 entropyASz: size of entropyA in bytes
const byte* entropyB: If reseed set, drbg will be reseeded with entropyB
word32 entropyBSz: size of entropyB in bytes
byte* output: initialized to random data seeded with entropyB if seedrandom is set, and entropyA otherwise
word32 outputSz: length of output in bytes
Example:
byte output[SHA256_DIGEST_SIZE * 4];
const byte test1EntropyB[] = ....; // test input for reseed false
const byte test1Output[] = ....; // testvector: expected output of
// reseed false
ret = wc_RNG_HealthTest(0, test1Entropy, sizeof(test1Entropy), NULL, 0,
output, sizeof(output));
if (ret != 0)
return -1;//healthtest without reseed failed
if (XMEMCMP(test1Output, output, sizeof(output)) != 0)
return -1; //compare to testvector failed: unexpected output
const byte test2EntropyB[] = ....; // test input for reseed
const byte test2Output[] = ....; // testvector expected output of reseed
ret = wc_RNG_HealthTest(1, test2EntropyA, sizeof(test2EntropyA),
test2EntropyB, sizeof(test2EntropyB),
output, sizeof(output));
if (XMEMCMP(test2Output, output, sizeof(output)) != 0)
return -1; //compare to testvector failed
See also:
wc_InitRngCavium, wc_InitRng, wc_RNG_GenerateBlock, wc_RNG_GenerateByte, wc_FreeRng
wc_InitNetRandom
Synopsis:
#include <wolfssl/wolfcrypt/random.h>
int wc_InitNetRandom(const char* configFile, wnr_hmac_key hmac_cb, int timeout)
Description:
Init global Whitewood netRandom context
Return Values:
0: Success
BAD_FUNC_ARG: Either configFile is null or timeout is negative.
RNG_FAILURE_E: There was a failure initializing the rng.
Parameters:
configFile - Path to configuration file
hmac_cb - Optional to create HMAC callback.
timeout - A timeout duration.
Example:
char* config = "path/to/config/example.conf";
int time = /* Some sufficient timeout value */;
if (wc_InitNetRandom(config, NULL, time) != 0)
{
/* Some error occured */
}
See Also:
wc_FreeNetRandom
wc_FreeNetRandom
Synopsis:
#include <wolfssl/wolfcrypt/random.h>
int wc_FreeNetRandom(void)
Description:
Free global Whitewood netRandom context.
Return Values:
0: Success
BAD_MUTEX_E: Error locking mutex on wnr_mutex
Parameters:
Example:
int ret = wc_FreeNetRandom();
if(ret != 0)
{
/* Handle the error */
}
See Also:
wc_InitNetRandom
18.21 RIPEMD
wc_InitRipeMd
Synopsis:
#include <wolfssl/wolfcrypt/ripemd.h>
int wc_InitRipeMd(RipeMd* ripemd);
Description:
This function initializes a ripemd structure by initializing ripemd’s digest, buffer, loLen and hiLen.
Return Values:
0: returned on successful execution of the function. The RipeMd structure is initialized.
BAD_FUNC_ARG - returned if the RipeMd structure is NULL.
Parameters:
RipeMd* ripemd - pointer to the ripemd structure to initialize
Example:
RipeMd md;
int ret;
ret = wc_InitRipeMd(&md);
if (ret != 0) {
/* Failure case. */
}
See Also:
wc_RipeMdUpdate, wc_RipeMdFinal
wc_RipeMdUpdate
Synopsis:
#include <wolfssl/wolfcrypt/ripemd.h>
int wc_RipeMdUpdate(RipeMd* ripemd, const byte* data, word32 len);
Description:
This function generates the RipeMd digest of the data input and stores the result in the ripemd->digest buffer. After running wc_RipeMdUpdate, one should compare the generated ripemd->digest to a known authentication tag to verify the authenticity of a message.
Return Values:
0: Returned on successful execution of the function.
BAD_FUNC_ARG: Returned if the RipeMd structure is NULL or if data is NULL and len is not zero. This function should execute if data is NULL and len is 0.
Parameters:
RipeMd* ripemd: pointer to the ripemd structure to be initialized with wc_InitRipeMd
const byte* data: data to be hashed
word32 len: sizeof data in bytes
Example:
const byte* data; /*The data to be hashed*/
....
RipeMd md;
int ret;
ret = wc_InitRipeMd(&md);
if (ret == 0) {
ret = wc_RipeMdUpdate(&md, plain, sizeof(plain));
if (ret != 0) {
/* Failure case */ …
See Also:
wc_InitRipeMd, wc_RipeMdFinal
wc_RipeMdFinal
Synopsis:
#include <wolfssl/wolfcrypt/ripemd.h>
int wc_RipeMdFinal(RipeMd* ripemd, byte* hash);
Description:
This function copies the computed digest into hash. If there is a partial unhashed block, this method will pad the block with 0s, and include that block’s round in the digest before copying to hash. State of ripemd is reset.
Return Values:
0: Returned on successful execution of the function. The state of the RipeMd structure has been reset.
BAD_FUNC_ARG: Returned if the RipeMd structure or hash parameters are NULL.
Parameters:
RipeMd* ripemd: pointer to the ripemd structure to be initialized with wc_InitRipeMd, and containing hashes from wc_RipeMdUpdate. State will be reset
byte* hash: buffer to copy digest to. Should be RIPEMD_DIGEST_SIZE bytes
Example:
RipeMd md;
int ret;
byte digest[RIPEMD_DIGEST_SIZE];
const byte* data; /*The data to be hashed*/
...
ret = wc_InitRipeMd(&md);
if (ret == 0) {
ret = wc_RipeMdUpdate(&md, plain, sizeof(plain));
if (ret != 0) {
/* RipeMd Update Failure Case. */
}
ret = wc_RipeMdFinal(&md, digest);
if (ret != 0) {
/* RipeMd Final Failure Case. */
}...
18.22 RSA
wc_InitRsaKey
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_InitRsaKey(RsaKey* key, void* heap);
Description:
This function initializes a provided RsaKey struct. It also takes in a heap identifier, for use with user defined memory overrides (see XMALLOC, XFREE, XREALLOC).
Return Values:
0: Returned upon successfully initializing the RSA structure for use with encryption and decryption
BAD_FUNC_ARGS: Returned if the RSA key pointer evaluates to NULL
Parameters:
key - pointer to the RsaKey structure to initialize
heap - pointer to a heap identifier, for use with memory overrides, allowing custom handling of memory allocation. This heap will be the default used when allocating memory for use with this RSA object
Example:
RsaKey enc;
int ret;
ret = wc_RsaInitKey(&enc, NULL); // not using heap hint. No custom memory
if ( ret != 0 ) {
// error initializing RSA key
}
See Also:
wc_RsaInitCavium, wc_FreeRsaKey
wc_FreeRsaKey
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_FreeRsaKey(RsaKey* key);
Description:
This function frees a provided RsaKey struct using mp_clear.
Return Values:
0: Returned upon successfully freeing the key
Parameters:
key - pointer to the RsaKey structure to free
Example:
RsaKey enc;
wc_RsaInitKey(&enc, NULL); // not using heap hint. No custom memory
... set key, do encryption
wc_FreeRsaKey(&enc);
See Also:
wc_InitRsaKey
wc_RsaPrivateKeyDecode
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaPrivateKeyDecode(const byte* input, word32* inOutIdx, RsaKey* key, word32 inSz);
Description:
This function parses a DER-formatted RSA private key, extracts the private key and stores it in the given RsaKey structure. It also sets the distance parsed in idx.
Return Values:
0: Returned upon successfully parsing the private key from the DER encoded input
ASN_PARSE_E: Returned if there is an error parsing the private key from the input buffer. This may happen if the input private key is not properly formatted according to ASN.1 standards
ASN_RSA_KEY_E: Returned if there is an error reading the private key elements of the RSA key input
Parameters:
input - pointer to the buffer containing the DER formatted private key to decode
inOutIdx - pointer to the index in the buffer at which the key begins (usually 0). As a side effect of this function, inOutIdx will store the distance parsed through the input buffer
key - pointer to the RsaKey structure in which to store the decoded private key
inSz - size of the input buffer
Example:
RsaKey enc;
word32 idx = 0;
int ret = 0;
byte der[] = { /* initialize with DER-encoded RSA private key */ };
wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
ret = wc_RsaPrivateKeyDecode(der, &idx, &enc, sizeof(der));
if( ret != 0 ) {
// error parsing private key
}
See Also
wc_RsaPublicKeyDecode, wc_MakeRsaKey
wc_RsaPublicKeyDecode
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaPublicKeyDecode(const byte* input, word32* inOutIdx, RsaKey* key, word32 inSz);
Description:
This function parses a DER-formatted RSA public key, extracts the public key and stores it in the given RsaKey structure. It also sets the distance parsed in idx.
Return Values:
0: Returned upon successfully parsing the public key from the DER encoded input
ASN_PARSE_E: Returned if there is an error parsing the public key from the input buffer. This may happen if the input public key is not properly formatted according to ASN.1 standards
ASN_OBJECT_ID_E: Returned if the ASN.1 Object ID does not match that of a RSA public key
ASN_EXPECT_0_E: Returned if the input key is not correctly formatted according to ASN.1 standards
ASN_BITSTR_E: Returned if the input key is not correctly formatted according to ASN.1 standards
ASN_RSA_KEY_E: Returned if there is an error reading the public key elements of the RSA key input
Parameters:
input - pointer to the buffer containing the input DER-encoded RSA public key to decode
inOutIdx - pointer to the index in the buffer at which the key begins (usually 0). As a side effect of this function, inOutIdx will store the distance parsed through the input buffer
key - pointer to the RsaKey structure in which to store the decoded public key
inSz - size of the input buffer
Example:
RsaKey pub;
word32 idx = 0;
int ret = 0;
byte der[] = { /* initialize with DER-encoded RSA public key */ };
wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
ret = wc_RsaPublicKeyDecode(der, &idx, &pub, sizeof(der));
if( ret != 0 ) {
// error parsing public key
}
See Also:
wc_RsaPublicKeyDecodeRaw
wc_RsaPublicKeyDecodeRaw
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaPublicKeyDecodeRaw(const byte* n, word32 nSz, const byte* e, word32 eSz,
RsaKey* key);
Description:
This function decodes the raw elements of an RSA public key, taking in the public modulus (n) and exponent (e). It stores these raw elements in the provided RsaKey structure, allowing one to use them in the encryption/decryption process.
Return Values:
0: Returned upon successfully decoding the raw elements of the public key into the RsaKey structure
BAD_FUNC_ARG: Returned if any of the input arguments evaluates to NULL
MP_INIT_E: Returned if there is an error initializing an integer for use with the multiple precision integer (mp_int) library
ASN_GETINT_E: Returned if there is an error reading one of the provided RSA key elements, n or e
Parameters:
n - pointer to a buffer containing the raw modulus parameter of the public RSA key
nSz - size of the buffer containing n
e - pointer to a buffer containing the raw exponent parameter of the public RSA key
eSz - size of the buffer containing e
key - pointer to the RsaKey struct to initialize with the provided public key elements
Example:
RsaKey pub;
int ret = 0;
byte n[] = { /* initialize with received n component of public key */ };
byte e[] = { /* initialize with received e component of public key */ };
wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
ret = wc_RsaPublicKeyDecodeRaw(n, sizeof(n), e, sizeof(e), &pub);
if( ret != 0 ) {
// error parsing public key elements
}
See Also:
wc_RsaPublicKeyDecode
wc_MakeRsaKey
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_MakeRsaKey(RsaKey* key, int size, long e, RNG* rng);
Description:
This function generates a RSA private key of length size (in bits) and given exponent (e). It then stores this key in the provided RsaKey structure, so that it may be used for encryption/decryption. A secure number to use for e is 65537. size is required to be greater than RSA_MIN_SIZE and less than RSA_MAX_SIZE.
For this function to be available, the option WOLFSSL_KEY_GEN must be enabled at compile time. This can be accomplished with --enable-keygen if using ./configure.
Return Values
0: Returned upon successfully generating a RSA private key
BAD_FUNC_ARG: Returned if any of the input arguments are NULL, the size parameter falls outside of the necessary bounds, or e is incorrectly chosen
RNG_FAILURE_E: Returned if there is an error generating a random block using the provided RNG structure
MP_INIT_E, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, MP_MEM, and MP_ZERO_E: May be returned if there is an error in the math library used while generating the RSA key
Parameters:
key- pointer to the RsaKey structure in which to store the generated private key
size - desired keylenth, in bits. Required to be greater than RSA_MIN_SIZE and less than RSA_MAX_SIZE
e - exponent parameter to use for generating the key. A secure choice is 65537
rng - pointer to an RNG structure to use for random number generation while making the key
Example:
RsaKey priv;
RNG rng;
int ret = 0;
long e = 65537; /* standard value to use for exponent */
wc_InitRsaKey(&priv, NULL); /* not using heap hint. No custom memory */
wc_InitRng(&rng);
ret = wc_MakeRsaKey(&priv, 2048, e, &rng); // generate 2048 bit long private key
if( ret != 0 ) {
// error generating private key
}
wc_SetKeyUsage
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wc_SetKeyUsage(Cert *cert, const char *value);
Description:
This function allows you to set the key usage using a comma delimited string of tokens. Accepted tokens are:
|
|
Example:
"digitalSignature,nonRepudiation"
nonRepudiation and contentCommitment are for the same usage.
Return Values:
0: Success
BAD_FUNC_ARG: Returned when either arg is null.
MEMORY_E: Returned when there is an error allocating memory.
KEYUSAGE_E: Returned if an unrecognized token is entered.
Parameters:
cert - Pointer to initialized Cert structure.
value - Comma delimited string of tokens to set usage.
Example:
Cert cert;
wc_InitCert(&cert);
if(wc_SetKeyUsage(&cert, "cRLSign,keyCertSign") != 0)
{
/* Handle error */
}
See Also:
wc_InitCert, wc_MakeRsaKey
wc_RsaKeyToDer
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaKeyToDer(RsaKey* key, byte* output, word32 inLen)
Description:
This function converts an RsaKey key to DER format. The result is written to output and it returns the number of bytes written.
Return Values:
0: Success
BAD_FUNC_ARG: Returned if key or output is null, or if key->type is not RSA_PRIVATE, or if inLen isn't large enough for output buffer.
MEMORY_E: Returned if there is an error allocating memory.
Parameters:
key - Initialized RsaKey structure.
output - Pointer to output buffer.
inLen - Size of output buffer.
Example:
byte* der;
/* Allocate memory for der */
int derSz = /* Amount of memory allocated for der */;
RsaKey key;
RNG rng;
long e = 65537; // standard value to use for exponent
ret = wc_MakeRsaKey(&key, 2048, e, &rng); // generate 2048 bit long private key
wc_InitRsaKey(&key, NULL);
wc_InitRng(&rng);
if(wc_RsaKeyToDer(&key, der, derSz) != 0)
{
/* Handle the error thrown */
}
See Also:
wc_RsaKeyToPublicDer, wc_InitRsaKey, wc_MakeRsaKey, wc_InitRng
wc_RsaKeyToPublicDer
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaKeyToPublicDer(RsaKey* key, byte* output, word32 inLen)
Description:
Convert Rsa Public key to DER format. Writes to output, and returns count of bytes written.
Return Values:
>0: Success, number of bytes written.
BAD_FUNC_ARG: Returned if key or output is null.
MEMORY_E: Returned when an error allocating memory occurs.
< 0: Error
Parameters:
key - The RSA key structure to convert.
output - Output buffer to hold DER.
inLen - Length of buffer.
Example:
RsaKey key;
wc_RsaInitKey(&key, NULL);
/* Use key */
int BUFFER_SIZE = /* Some adequate size for the buffer */
byte output[BUFFER_SIZE];
if(wc_RsaKeyToPublicDer(&key, output, sizeof(output)) != 0)
{
/* Handle Error */
}
See Also:
wc_RsaKeyToPublicDer, wc_RsaInitKey
wc_RsaPublicEncrypt
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaPublicEncrypt(const byte* in, word32 inLen, byte* out, word32 outLen,
RsaKey* key, RNG* rng);
Description:
This function encrypts a message from in and stores the result in out. It requires an initialized public key and a random number generator. As a side effect, this function will return the bytes written to out in outLen.
Return Values:
Upon successfully encrypting the input message, returns the number bytes written to out
-1: Returned if there is an error during RSA encryption and hardware acceleration via Cavium is enabled
BAD_FUNC_ARG: Returned if any of the input parameters are invalid
RSA_BUFFER_E: Returned if the output buffer is too small to store the ciphertext
RNG_FAILURE_E: Returned if there is an error generating a random block using the provided RNG structure
MP_INIT_E, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, MP_MEM, and MP_ZERO_E: May be returned if there is an error in the math library used while encrypting the message
Parameters:
in - pointer to a buffer containing the input message to encrypt
inLen - the length of the message to encrypt
out - pointer to the buffer in which to store the output ciphertext
outLen - the length of the output buffer
key - pointer to the RsaKey structure containing the public key to use for encryption
rng - The RNG structure with which to generate random block padding
Example:
RsaKey pub;
int ret = 0;
byte n[] = { /* initialize with received n component of public key */ };
byte e[] = { /* initialize with received e component of public key */ };
byte msg[] = { /* initialize with plaintext of message to encrypt */ };
byte cipher[256]; // 256 bytes is large enough to store 2048 bit RSA ciphertext
wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
wc_RsaPublicKeyDecodeRaw(n, sizeof(n), e, sizeof(e), &pub);
// initialize with received public key parameters
ret = wc_RsaPublicEncrypt(msg, sizeof(msg), out, sizeof(out), &pub, &rng);
if ( ret != 0 ) {
// error encrypting message
}
See Also:
wc_RsaPrivateDecrypt
wc_RsaPrivateDecryptInline
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaPrivateDecryptInline(byte* in, word32 inLen, byte** out,RsaKey* key);
Description:
This functions is utilized by the wc_RsaPrivateDecrypt function for decrypting.
Return Values:
RSA_PAD_E: RsaUnPad error, bad formatting
Length of decrypted data.
Parameters:
in- The byte array to be decrypted.
inLen- The length of in.
out- The byte array for the decrypted data to be stored.
key- The key to use for decryption.
Example:
NA. Internal function.
See Also:
wc_RsaPrivateDecrypt
wc_RsaPrivateDecrypt
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaPrivateDecrypt(const byte* in, word32 inLen, byte* out,word32 outLen, RsaKey* key);
Description:
This functions provides private RSA decryption.
Return Values:
MEMORY_E:
BAD_FUNC_ARG:
length of decrypted data.
Parameters:
in- The byte array to be decrypted.
inLen- The length of in.
out- The byte array for the decrypted data to be stored.
outLen- The length of out.
key- The key to use for decryption.
Example:
ret = wc_RsaPublicEncrypt(in, inLen, out, sizeof(out), &key, &rng);
if (ret < 0) {
return -1;
}
ret = wc_RsaPrivateDecrypt(out, ret, plain, sizeof(plain), &key);
if (ret < 0) {
return -1;
}
See Also:
RsaUnPad
wc_RsaFunction
wc_RsaPrivateDecryptInline
wc_RsaPublicEncrypt_ex
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaPublicEncrypt_ex(const byte* in, word32 inLen, byte* out, word32 outLen, RsaKey* key, WC_RNG* rng, int type, int hash, int mgf, byte* label, word32 labSz);
Description:
This function performs RSA encrypt while allowing the choice of which padding to use.
Return Values:
size of encrypted data: On successfully encryption the size of the encrypted buffer is returned
RSA_BUFFER_E: RSA buffer error, output too small or input too large
Parameters:
in - pointer to the buffer for encryption
inLen - length of the buffer to encrypt
out - encrypted msg created
outLen – length of buffer available to hold encrypted msg
key - initialized RSA key struct
rng - initialized WC_RNG struct
type - type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
hash – type of hash to use (choices can be found in hash.h)
mgf - type of mask generation function to use
label - an optional label to associate with encrypted message
labelSz - size of the optional label used
Example:
WC_RNG rng;
RsaKey key;
byte in[] = “I use Turing Machines to ask questions”
byte out[256];
int ret;
…
ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, &rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
if (ret < 0) {
//handle error
}
See Also:
wc_RsaPublicEncrypt, wc_RsaPrivateDecrypt_ex
wc_RsaPrivateDecrypt_ex
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaPrivateDecrypt_ex(const byte* in, word32 inLen, byte* out, word32 outLen, RsaKey* key, int type, int hash, int mgf, byte* label, word32 labSz);
Description:
This function uses RSA to decrypt a message and gives the option of what padding type.
Return Values:
size of decrypted message: On successful decryption, the size of the decrypted message is returned.
MEMORY_E: Returned if not enough memory on system to malloc a needed array.
BAD_FUNC_ARG: Returned if a bad argument was passed into the function.
Parameters:
in - pointer to the buffer for decryption
inLen - length of the buffer to decrypt
out - decrypted msg created
outLen – length of buffer available to hold decrypted msg
key - initialized RSA key struct
type - type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
hash – type of hash to use (choices can be found in hash.h)
mgf - type of mask generation function to use
label - an optional label to associate with encrypted message
labelSz - size of the optional label used
Example:
WC_RNG rng;
RsaKey key;
byte in[] = “I use Turing Machines to ask questions”
byte out[256];
byte plain[256];
int ret;
…
ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, &rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
if (ret < 0) {
//handle error
}
…
ret = wc_RsaPrivateDecrypt_ex(out, ret, plain, sizeof(plain), &key, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
if (ret < 0) {
//handle error
}
wc_RsaPrivateDecryptInline_ex
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaPrivateDecrypt_ex(const byte* in, word32 inLen, byte** out, RsaKey* key, int type, int hash, int mgf, byte* label, word32 labSz);
Description:
This function uses RSA to decrypt a message inline and gives the option of what padding type. The in buffer will contain the decrypted message after being called and the out byte pointer will point to the location in the “in” buffer where the plain text is.
Return Values:
size of decrypted message: On successful decryption, the size of the decrypted message is returned.
MEMORY_E: Returned if not enough memory on system to malloc a needed array.
RSA_PAD_E: Returned if an error in the padding was encountered.
BAD_PADDING_E: Returned if an error happened during parsing past padding.
BAD_FUNC_ARG: Returned if a bad argument was passed into the function.
Parameters:
in - pointer to the buffer for decryption
inLen - length of the buffer to decrypt
out - pointer to location of decrypted message in “in” buffer
key - initialized RSA key struct
type - type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
hash – type of hash to use (choices can be found in hash.h)
mgf - type of mask generation function to use
label - an optional label to associate with encrypted message
labelSz - size of the optional label used
Example:
WC_RNG rng;
RsaKey key;
byte in[] = “I use Turing Machines to ask questions”
byte out[256];
byte* plain;
int ret;
…
ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, &rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
if (ret < 0) {
//handle error
}
…
ret = wc_RsaPrivateDecryptInline_ex(out, ret, &plain, &key, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
if (ret < 0) {
//handle error
}
wc_RsaSSL_Sign
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaSSL_Sign(const byte* in, word32 inLen, byte* out,word32 outLen, RsaKey* key, RNG* rng);
Description:
Signs the provided array with the private key.
Return Values:
RSA_BUFFER_E:
Parameters:
in- The byte array to be encrypted.
inLen- The length of in.
out- The byte array for the encrypted data to be stored.
outLen- The length of out.
key- The key to use for encryption.
RNG- The RNG struct to use for random number purposes.
Example:
ret = wc_RsaSSL_Sign(in, inLen, out, sizeof(out), &key, &rng);
if (ret < 0) {
return -1;
}
memset(plain, 0, sizeof(plain));
ret = wc_RsaSSL_Verify(out, ret, plain, sizeof(plain), &key);
if (ret < 0) {
return -1;
}
See Also:
wc_RsaPad
wc_RsaSSL_Verify
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaSSL_Verify(const byte* in, word32 inLen, byte* out,word32 outLen, RsaKey* key);
Description:
Used to verify that the message was signed by key.
Return Values:
MEMORY_E: memory exception.
Length of text on no error.
Parameters:
in- The byte array to be decrypted.
inLen- The length of in.
out- The byte array for the decrypted data to be stored.
outLen- The length of out.
key- The key to use for verification.
Example:
ret = wc_RsaSSL_Sign(in, inLen, out, sizeof(out), &key, &rng);
if (ret < 0) {
return -1;
}
memset(plain, 0, sizeof(plain));
ret = wc_RsaSSL_Verify(out, ret, plain, sizeof(plain), &key);
if (ret < 0) {
return -1;
}
See Also:
wc_RsaSSL_Sign
wc_RsaSSL_VerifyInline
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaSSL_VerifyInline(byte* in, word32 inLen, byte** out, RsaKey* key)
Description:
Used to verify that the message was signed by RSA key. The output uses the same byte array as the input.
Return Values:
> 0: Length of text.
< 0: An error occurred.
Parameters:
in - Byte array to be decrypted.
inLen - Length of the buffer input.
out - Pointer to a pointer for decrypted information.
key - RsaKey to use.
Example:
RsaKey key;
RNG rng;
int ret = 0;
long e = 65537; /* standard value to use for exponent */
wc_InitRsaKey(&key, NULL); /* not using heap hint. No custom memory */
wc_InitRng(&rng);
wc_MakeRsaKey(&key, 2048, e, &rng);
byte in[] = { /* Initialize with some RSA encrypted information */ }
byte* out;
if(wc_RsaSSL_VerifyInline(in, sizeof(in), &out, &key) < 0)
{
/* handle error */
}
See Also:
wc_RsaSSL_Verify, wc_RsaSSL_Sign
wc_RsaEncryptSize
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaEncryptSize(RsaKey* key);
Description:
Returns the encryption size for the provided key structure.
Return Values:
Encryption size for the provided key structure.
Parameters:
key- The key to use for verification.
Example:
int sz = wc_RsaEncryptSize(&key);
See Also:
wc_InitRsaKey
wc_InitRsaKey_ex
wc_MakeRsaKey
XMEMSET
wc_RsaFlattenPublicKey
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaFlattenPublicKey(RsaKey* key, byte* e, word32* eSz, byte* n, word32* nSz);
Description:
Flattens the RsaKey structure into individual elements (e, n) used for the RSA algorithm.
Return Values:
0: Returned if the function executed normally, without error.
BAD_FUNC_ARG: Returned if any of the parameters are passed in with a null value.
RSA_BUFFER_E: Returned if the e or n buffers passed in are not the correct size.
MP_MEM: Returned if an internal function has memory errors.
MP_VAL: Returned if an internal function argument is not valid.
Parameters:
key- The key to use for verification.
e - a buffer for the value of e. e is a large positive integer in the RSA modular arithmetic operation.
eSz - the size of the e buffer.
n - a buffer for the value of n. n is a large positive integer in the RSA modular arithmetic operation.
nSz - the size of the n buffer.
Example:
Rsa key; /* A valid RSA key. */
byte e[/*buffer sz. E.g. 256 */];
byte n[256];
int ret;
word32 eSz = sizeof(e);
word32 nSz = sizeof(n);
...
ret = wc_RsaFlattenPublicKey(&key, e, &eSz, n, &nSz);
if (ret != 0) {
/* Failure case. */
}
See Also:
wc_InitRsaKey
wc_InitRsaKey_ex
wc_MakeRsaKey
XMEMSET
wc_RsaInitCavium
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaInitCavium(RsaKey*, int devId);
Description:
Initialization of RsaKey struct for use with Nitrox devices.
Return Values:
0: success
-1: error
Parameters:
key- The key to use for verification.
devId-device ID
Example:
See Also:
wc_RsaFreeCavium
wc_RsaFreeCavium
Synopsis:
#include <wolfssl/wolfcrypt/rsa.h>
int wc_RsaFreeCavium(RsaKey* key);
Description:
Frees the key for use with Nitrox devices.
Return Values:
BAD_FUNC_ARG:
0: Success
Parameters:
key- The key to free.
Example:
wc_RsaFreeCavium(&key);
See Also:
wc_RsaInitCavium
18.23 SHA
int wc_InitSha
Synopsis:
#include <wolfssl/wolfcrypt/sha.h>
int wc_InitSha(Sha* sha);
Description:
This function initializes SHA. This is automatically called by wc_ShaHash.
Return Values:
0: Returned upon successfully initializing
Parameters:
sha - pointer to the sha structure to use for encryption
Example:
Sha sha[1];
if ((ret = wc_InitSha(sha)) != 0) {
WOLFSSL_MSG("wc_InitSha failed");
}
else {
wc_ShaUpdate(sha, data, len);
wc_ShaFinal(sha, hash);
}
See Also:
wc_ShaHash
wc_ShaUpdate
wc_ShaFinal
int wc_ShaUpdate
Synopsis:
#include <wolfssl/wolfcrypt/sha.h>
int wc_ShaUpdate(Sha* sha, const byte* data, word32 len)
Description:
Can be called to continually hash the provided byte array of length len.
Return Values:
0: Returned upon successfully adding the data to the digest.
Parameters:
sha - pointer to the sha structure to use for encryption
data - the data to be hashed
len - length of data to be hashed
Example:
Sha sha[1];
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitSha(sha)) != 0) {
WOLFSSL_MSG("wc_InitSha failed");
}
else {
wc_ShaUpdate(sha, data, len);
wc_ShaFinal(sha, hash);
}
See Also:
wc_ShaHash
wc_ShaFinal
wc_InitSha
int wc_ShaHash
Synopsis:
#include <wolfssl/wolfcrypt/hash.h>
int wc_ShaHash(const byte* data, word32 len, byte* hash)
Description:
Convenience function, handles all the hashing and places the result into hash.
Return Values:
0: Returned upon successfully ….
Memory_E: memory error, unable to allocate memory. This is only possible with the small stack option enabled.
Parameters:
data - the data to hash
len - the length of data
hash - Byte array to hold hash value.
Example:
??????????????
See Also:
wc_ShaHash
wc_ShaFinal
wc_InitSha
int wc_ShaFinal
Synopsis:
#include <wolfssl/wolfcrypt/sha.h>
int wc_ShaFinal(Sha* sha, byte* hash)
Description:
Finalizes hashing of data. Result is placed into hash. Resets state of sha struct.
Return Values:
0: Returned upon successfully finalizing.
Parameters:
sha - pointer to the sha structure to use for encryption
hash - Byte array to hold hash value.
Example:
Sha sha[1];
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitSha(sha)) != 0) {
WOLFSSL_MSG("wc_InitSha failed");
}
else {
wc_ShaUpdate(sha, data, len);
wc_ShaFinal(sha, hash);
}
See Also:
wc_ShaHash
wc_InitSha
wc_ShaGetHash
int wc_ShaGetHash
Synopsis:
#include <wolfssl/wolfcrypt/hash.h>
int wc_ShaGetHash(Sha* sha, byte* hash)
Description:
Gets hash data. Result is placed into hash. Does not reset state of sha struct.
Return Values:
0: Returned upon successfully finalizing.
Parameters:
sha - pointer to the sha structure to use for encryption
hash - Byte array to hold hash value.
Example:
Sha sha[1];
if ((ret = wc_InitSha(sha)) != 0) {
WOLFSSL_MSG("wc_InitSha failed");
}
else {
wc_ShaUpdate(sha, data, len);
wc_ShaGetHash(sha, hash);
}
See Also:
wc_ShaHash
wc_ShaFinal
wc_InitSha
wc_ShaRestorePos
Synopsis:
#include <wolfssl/wolfcrypt/hash.h>
void wc_ShaRestorePos(Sha* s1, Sha* s2)
Description:
Sets the value of one Sha struct equal to another.
Return Values:
No returns.
Parameters:
s1 - Pointer to a Sha struct to be changed.
s2 - Pointer to a Sha struct to copy from.
Example:
Sha s1;
Sha s2;
/* Initialize and use s2 */
wc_ShaRestorePos(&s1, &s2);
See Also:
wc_Md5RestorePos, wc_Sha256RestorePos
wc_ShaFree
Synopsis:
#include <wolfssl/wolfcrypt/port/ti/ti-hash.h>
void wc_ShaFree(Sha* sha)
Description:
Used to clean up memory used by an initialized Sha struct. Note: this is only supported if you have WOLFSSL_TI_HASH defined.
Return Values:
No returns.
Parameters:
sha - Pointer to the Sha struct to free.
Example:
Sha sha;
wc_InitSha(&sha);
/* Use sha */
wc_ShaFree(&sha);
See Also:
wc_InitSha, wc_ShaUpdate, wc_ShaFinal
18.24 SHA-256
int wc_InitSha256
Synopsis:
#include <wolfssl/wolfcrypt/sha256.h>
int wc_InitSha256(Sha256* sha256);
Description:
This function initializes SHA256. This is automatically called by wc_Sha256Hash.
Return Values:
0: Returned upon successfully initializing
Parameters:
sha256 - pointer to the sha256 structure to use for encryption
Example:
Sha256 sha256[1];
if ((ret = wc_InitSha356(sha256)) != 0) {
WOLFSSL_MSG("wc_InitSha256 failed");
}
else {
wc_Sha256Update(sha256, data, len);
wc_Sha256Final(sha256, hash);
}
See Also:
wc_Sha256Hash
wc_Sha256Update
wc_Sha256Final
int wc_Sha256Update
Synopsis:
#include <wolfssl/wolfcrypt/sha256.h>
int wc_Sha256Update(Sha256* sha256, const byte* data, word32 len)
Description:
Can be called to continually hash the provided byte array of length len.
Return Values:
0: Returned upon successfully adding the data to the digest.
Parameters:
sha256 - pointer to the sha256 structure to use for encryption
data - the data to be hashed
len - length of data to be hashed
Example:
Sha256 sha256[1];
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitSha256(sha256)) != 0) {
WOLFSSL_MSG("wc_InitSha256 failed");
}
else {
wc_Sha256Update(sha256, data, len);
wc_Sha256Final(sha256, hash);
}
See Also:
wc_Sha256Hash
wc_Sha256Final
wc_InitSha256
int wc_Sha256Hash
Synopsis:
#include <wolfssl/wolfcrypt/hash.h>
int wc_Sha256Hash(const byte* data, word32 len, byte* hash)
Description:
Convenience function, handles all the hashing and places the result into hash.
Return Values:
0: Returned upon successfully ….
Memory_E: memory error, unable to allocate memory. This is only possible with the small stack option enabled.
Parameters:
data - the data to hash
len - the length of data
hash - Byte array to hold hash value.
Example:
??????????????
See Also:
wc_Sha256Hash
wc_Sha256Final
wc_InitSha256
int wc_Sha256Final
Synopsis:
#include <wolfssl/wolfcrypt/sha256.h>
int wc_Sha256Final(Sha256* sha256, byte* hash)
Description:
Finalizes hashing of data. Result is placed into hash. Resets state of sha256 struct.
Return Values:
0: Returned upon successfully finalizing.
Parameters:
sha256 - pointer to the sha256 structure to use for encryption
hash - Byte array to hold hash value.
Example:
Sha256 sha256[1];
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitSha356(sha256)) != 0) {
WOLFSSL_MSG("wc_InitSha256 failed");
}
else {
wc_Sha256Update(sha256, data, len);
wc_Sha256Final(sha256, hash);
}
See Also:
wc_Sha256Hash
wc_Sha256GetHash
wc_InitSha256
int wc_Sha256GetHash
Synopsis:
#include <wolfssl/wolfcrypt/hash.h>
int wc_Sha256GetHash(Sha256* sha256, byte* hash)
Description:
Gets hash data. Result is placed into hash. Does not reset state of sha256 struct.
Return Values:
0: Returned upon successfully finalizing.
Parameters:
sha256 - pointer to the sha256 structure to use for encryption
hash - Byte array to hold hash value.
Example:
Sha256 sha256[1];
if ((ret = wc_InitSha356(sha256)) != 0) {
WOLFSSL_MSG("wc_InitSha256 failed");
}
else {
wc_Sha256Update(sha256, data, len);
wc_Sha256GetHash(sha256, hash);
}
See Also:
wc_Sha256Hash
wc_Sha256Final
wc_InitSha256
wc_Sha256RestorePos
Synopsis:
#include <wolfssl/wolfcrypt/hash.h>
void wc_Sha256RestorePos(Sha256* s1, Sha256* s2)
Description:
Sets the value of one Sha256 struct equal to another.
Return Values:
No returns.
Parameters:
s1 - Pointer to a Sha256 struct to be changed.
s2 - Pointer to a Sha256 struct to copy from.
Example:
Sha256 s1;
Sha256 s2;
/* Initialize and use s2 */
wc_Sha256RestorePos(&s1, &s2);
See Also:
wc_ShaRestorePos, wc_Md5RestorePos
wc_Sha256Free
Synopsis:
#include <wolfssl/wolfcrypt/hash.h>
void wc_Sha256Free(Sha256* sha256)
Description:
Resets the Sha256 structure. Note: this is only supported if you have WOLFSSL_TI_HASH defined.
Return Values:
No returns.
Parameters:
sha256 - Pointer to the sha256 structure to be freed.
Example:
Sha256 sha256;
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitSha256(&sha256)) != 0) {
WOLFSSL_MSG("wc_InitSha256 failed");
}
else {
wc_Sha256Update(&sha256, data, len);
wc_Sha256Final(&sha256, hash);
wc_Sha256Free(&sha256);
}
See Also:
wc_InitSha256, wc_Sha256Update, wc_Sha256Final
18.25 SHA-512
int wc_InitSha512
Synopsis:
#include <wolfssl/wolfcrypt/sha512.h>
int wc_InitSha512(Sha512* sha512);
Description:
This function initializes SHA512. This is automatically called by wc_Sha512Hash.
Return Values:
0: Returned upon successfully initializing
Parameters:
sha512 - pointer to the sha512 structure to use for encryption
Example:
Sha512 sha512[1];
if ((ret = wc_InitSha512(sha512)) != 0) {
WOLFSSL_MSG("wc_InitSha512 failed");
}
else {
wc_Sha512Update(sha512, data, len);
wc_Sha512Final(sha512, hash);
}
See Also:
wc_Sha512Hash
wc_Sha512Update
wc_Sha512Final
int wc_Sha512Update
Synopsis:
#include <wolfssl/wolfcrypt/sha512.h>
int wc_Sha512Update(Sha512* sha512, const byte* data, word32 len)
Description:
Can be called to continually hash the provided byte array of length len.
Return Values:
0: Returned upon successfully adding the data to the digest.
Parameters:
sha512 - pointer to the sha512 structure to use for encryption
data - the data to be hashed
len - length of data to be hashed
Example:
Sha512 sha512[1];
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitSha512(sha512)) != 0) {
WOLFSSL_MSG("wc_InitSha512 failed");
}
else {
wc_Sha512Update(sha512, data, len);
wc_Sha512Final(sha512, hash);
}
See Also:
wc_Sha512Hash
wc_Sha512Final
wc_InitSha512
int wc_Sha512Hash
Synopsis:
#include <wolfssl/wolfcrypt/hash.h>
int wc_Sha512Hash(const byte* data, word32 len, byte* hash)
Description:
Convenience function, handles all the hashing and places the result into hash.
Return Values:
0: Returned upon successfully hashing the inputted data
Memory_E: memory error, unable to allocate memory. This is only possible with the small stack option enabled.
Parameters:
data - the data to hash
len - the length of data
hash - Byte array to hold hash value.
Example:
See Also:
wc_Sha512Hash
wc_Sha512Final
wc_InitSha512
int wc_Sha512Final
Synopsis:
#include <wolfssl/wolfcrypt/sha512.h>
int wc_Sha512Final(Sha512* sha512, byte* hash)
Description:
Finalizes hashing of data. Result is placed into hash.
Return Values:
0: Returned upon successfully finalizing the hash.
Parameters:
sha512 - pointer to the sha512 structure to use for encryption
hash - Byte array to hold hash value.
Example:
Sha512 sha512[1];
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitSha512(sha512)) != 0) {
WOLFSSL_MSG("wc_InitSha512 failed");
}
else {
wc_Sha512Update(sha512, data, len);
wc_Sha512Final(sha512, hash);
}
See Also:
wc_Sha512Hash
wc_Sha512Final
wc_InitSha512
18.26 SHA-384
int wc_InitSha384
Synopsis:
#include <wolfssl/wolfcrypt/sha512.h>
int wc_InitSha384(Sha384* sha384);
Description:
This function initializes SHA384. This is automatically called by wc_Sha384Hash.
Return Values:
0: Returned upon successfully initializing
Parameters:
sha384 - pointer to the sha384 structure to use for encryption
Example:
Sha384 sha384[1];
if ((ret = wc_InitSha384(sha384)) != 0) {
WOLFSSL_MSG("wc_InitSha384 failed");
}
else {
wc_Sha384Update(sha384, data, len);
wc_Sha384Final(sha384, hash);
}
See Also:
wc_Sha384Hash
wc_Sha384Update
wc_Sha384Final
int wc_Sha384Update
Synopsis:
#include <wolfssl/wolfcrypt/sha512.h>
int wc_Sha384Update(Sha384* sha384, const byte* data, word32 len)
Description:
Can be called to continually hash the provided byte array of length len.
Return Values:
0: Returned upon successfully adding the data to the digest.
Parameters:
sha384 - pointer to the sha384 structure to use for encryption
data - the data to be hashed
len - length of data to be hashed
Example:
Sha384 sha384[1];
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitSha384(sha384)) != 0) {
WOLFSSL_MSG("wc_InitSha384 failed");
}
else {
wc_Sha384Update(sha384, data, len);
wc_Sha384Final(sha384, hash);
}
See Also:
wc_Sha384Hash
wc_Sha384Final
wc_InitSha384
int wc_Sha384Hash
Synopsis:
#include <wolfssl/wolfcrypt/hash.h>
int wc_Sha384Hash(const byte* data, word32 len, byte* hash)
Description:
Convenience function, handles all the hashing and places the result into hash.
Return Values:
0: Returned upon successfully hashing the data
Memory_E: memory error, unable to allocate memory. This is only possible with the small stack option enabled.
Parameters:
data - the data to hash
len - the length of data
hash - Byte array to hold hash value.
See Also:
wc_Sha384Hash
wc_Sha384Final
wc_InitSha384
int wc_Sha384Final
Synopsis:
#include <wolfssl/wolfcrypt/sha512.h>
int wc_Sha384Final(Sha384* sha384, byte* hash)
Description:
Finalizes hashing of data. Result is placed into hash.
Return Values:
0: Returned upon successfully finalizing.
Parameters:
sha384 - pointer to the sha384 structure to use for encryption
hash - Byte array to hold hash value.
Example:
Sha384 sha384[1];
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitSha384(sha384)) != 0) {
WOLFSSL_MSG("wc_InitSha384 failed");
}
else {
wc_Sha384Update(sha384, data, len);
wc_Sha384Final(sha384, hash);
}
See Also:
wc_Sha384Hash
wc_Sha384Final
wc_InitSha384
18.27 Logging
wolfSSL_SetLoggingCb
Synopsis:
#include <wolfssl/wolfcrypt/logging.h>
int wolfSSL_SetLoggingCb(wolfSSL_Logging_cb f);
Description:
This function allows a user to plugin a custom error-logging callback function to replace the standard wolfSSL callback function. The function should be of the type:
void (*wolfSSL_Logging_cb)(const int logLevel, const char *const logMessage)
In order to enable logging information, DEBUG_WOLFSSL should be enabled at compile time.
Return Values:
0: Returned upon successfully setting a custom error callback function
BAD_FUNC_ARG: Returned if the provided function, f, evaluates to null
NOT_COMPILED_IN: Returned if DEBUG_WOLFSSL is not enabled at compile time and this function is called.
Parameters:
f - pointer to the function of type wolfSSL_Logging_cb, of the type:
void (*wolfSSL_Logging_cb)(const int logLevel, const char *const logMessage)
Example:
void logger(const int logLevel, const char* const logMessage) {
printf("Custom Logging: ");
...
}
wolfSSL_Logging_cb customCB = &logger;
if (wolfSSL_SetLoggingCb(customCB) != 0) {
// error setting custom callback function
}
See Also:
18.28 MD2
int wc_InitMd2
Synopsis:
#include <wolfssl/wolfcrypt/md2.h>
int wc_InitMd2(md2* md2);
Description:
This function initializes md2. This is automatically called by wc_Md2Hash.
Return Values:
0: Returned upon successfully initializing
Parameters:
md2 - pointer to the md2 structure to use for encryption
Example:
md2 md2[1];
if ((ret = wc_InitMd2(md2)) != 0) {
WOLFSSL_MSG("wc_Initmd2 failed");
}
else {
wc_Md2Update(md2, data, len);
wc_Md2Final(md2, hash);
}
See Also:
wc_Md2Hash
wc_Md2Update
wc_Md2Final
int wc_Md2Update
Synopsis:
#include <wolfssl/wolfcrypt/md2.h>
int wc_Md2Update(md2* md2, const byte* data, word32 len)
Description:
Can be called to continually hash the provided byte array of length len.
Return Values:
0: Returned upon successfully adding the data to the digest.
Parameters:
md2 - pointer to the md2 structure to use for encryption
data - the data to be hashed
len - length of data to be hashed
Example:
md2 md2[1];
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitMd2(md2)) != 0) {
WOLFSSL_MSG("wc_Initmd2 failed");
}
else {
wc_Md2Update(md2, data, len);
wc_Md2Final(md2, hash);
}
See Also:
wc_Md2Hash
wc_Md2Final
wc_InitMd2
int wc_Md2Hash
Synopsis:
#include <wolfssl/wolfcrypt/md2.h>
int wc_Md2Hash(const byte* data, word32 len, byte* hash)
Description:
Convenience function, handles all the hashing and places the result into hash.
Return Values:
0: Returned upon successfully hashing the data.
Memory_E: memory error, unable to allocate memory. This is only possible with the small stack option enabled.
Parameters:
data - the data to hash
len - the length of data
hash - Byte array to hold hash value.
Example:
See Also:
wc_Md2Hash
wc_Md2Final
wc_InitMd2
int wc_Md2Final
Synopsis:
#include <wolfssl/wolfcrypt/md2.h>
int wc_Md2Final(md2* md2, byte* hash)
Description:
Finalizes hashing of data. Result is placed into hash.
Return Values:
0: Returned upon successfully finalizing.
Parameters:
md2 - pointer to the md2 structure to use for encryption
hash - Byte array to hold hash value.
Example:
md2 md2[1];
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitMd2(md2)) != 0) {
WOLFSSL_MSG("wc_Initmd2 failed");
}
else {
wc_Md2Update(md2, data, len);
wc_Md2Final(md2, hash);
}
See Also:
wc_Md2Hash
wc_Md2Final
wc_InitMd2
18.29 MD4
int wc_InitMd4
Synopsis:
#include <wolfssl/wolfcrypt/md4.h>
int wc_InitMd4(md4* md4);
Description:
This function initializes md4. This is automatically called by wc_Md4Hash.
Return Values:
0: Returned upon successfully initializing
Parameters:
md4 - pointer to the md4 structure to use for encryption
Example:
md4 md4[1];
if ((ret = wc_InitMd4(md4)) != 0) {
WOLFSSL_MSG("wc_Initmd4 failed");
}
else {
wc_Md4Update(md4, data, len);
wc_Md4Final(md4, hash);
}
See Also:
wc_Md4Hash
wc_Md4Update
wc_Md4Final
int wc_Md4Update
Synopsis:
#include <wolfssl/wolfcrypt/md4.h>
int wc_Md4Update(md4* md4, const byte* data, word32 len)
Description:
Can be called to continually hash the provided byte array of length len.
Return Values:
0: Returned upon successfully adding the data to the digest.
Parameters:
md4 - pointer to the md4 structure to use for encryption
data - the data to be hashed
len - length of data to be hashed
Example:
md4 md4[1];
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitMd4(md4)) != 0) {
WOLFSSL_MSG("wc_Initmd4 failed");
}
else {
wc_Md4Update(md4, data, len);
wc_Md4Final(md4, hash);
}
See Also:
wc_Md4Hash
wc_Md4Final
wc_InitMd4
int wc_Md4Final
Synopsis:
#include <wolfssl/wolfcrypt/md4.h>
int wc_Md4Final(md4* md4, byte* hash)
Description:
Finalizes hashing of data. Result is placed into hash.
Return Values:
0: Returned upon successfully finalizing.
Parameters:
md4 - pointer to the md4 structure to use for encryption
hash - Byte array to hold hash value.
Example:
md4 md4[1];
if ((ret = wc_InitMd4(md4)) != 0) {
WOLFSSL_MSG("wc_Initmd4 failed");
}
else {
wc_Md4Update(md4, data, len);
wc_Md4Final(md4, hash);
}
See Also:
wc_Md4Hash
wc_Md4Final
wc_InitMd4
18.30 MD5
int wc_InitMd5
Synopsis:
#include <wolfssl/wolfcrypt/md5.h>
int wc_InitMd5(md5* md5);
Description:
This function initializes md5. This is automatically called by wc_Md5Hash.
Return Values:
0: Returned upon successfully initializing.
BAD_FUNC_ARG: Returned if the Md5 structure is passed as a NULL value.
Parameters:
md5 - pointer to the md5 structure to use for encryption
Example:
Md5 md5;
byte* hash;
if ((ret = wc_InitMd5(&md5)) != 0) {
WOLFSSL_MSG("wc_Initmd5 failed");
}
else {
ret = wc_Md5Update(&md5, data, len);
if (ret != 0) {
/* Md5 Update Failure Case. */
}
ret = wc_Md5Final(&md5, hash);
if (ret != 0) {
/* Md5 Final Failure Case. */
}
}
See Also:
wc_Md5Hash
wc_Md5Update
wc_Md5Final
int wc_Md5Update
Synopsis:
#include <wolfssl/wolfcrypt/md5.h>
int wc_Md5Update(md5* md5, const byte* data, word32 len)
Description:
Can be called to continually hash the provided byte array of length len.
Return Values:
0: Returned upon successfully adding the data to the digest.
BAD_FUNC_ARG: Returned if the Md5 structure is NULL or if data is NULL and len is greater than zero. The function should not return an error if the data parameter is NULL and len is zero.
Parameters:
md5 - pointer to the md5 structure to use for encryption
data - the data to be hashed
len - length of data to be hashed
Example:
Md5 md5;
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitMd5(&md5)) != 0) {
WOLFSSL_MSG("wc_Initmd5 failed");
}
else {
ret = wc_Md5Update(&md5, data, len);
if (ret != 0) {
/* Md5 Update Error Case. */
}
ret = wc_Md5Final(&md5, hash);
if (ret != 0) {
/* Md5 Final Error Case. */
}
}
See Also:
wc_Md5Hash
wc_Md5Final
wc_InitMd5
int wc_Md5Hash
Synopsis:
#include <wolfssl/wolfcrypt/md5.h>
int wc_Md5Hash(const byte* data, word32 len, byte* hash)
Description:
Convenience function, handles all the hashing and places the result into hash.
Return Values:
0: Returned upon successfully hashing the data.
Memory_E: memory error, unable to allocate memory. This is only possible with the small stack option enabled.
Parameters:
data - the data to hash
len - the length of data
hash - Byte array to hold hash value.
Example:
const byte* data;
word32 data_len;
byte* hash;
int ret;
...
ret = wc_Md5Hash(data, data_len, hash);
if (ret != 0) {
/* Md5 Hash Failure Case. */
}
See Also:
wc_Md5Hash
wc_Md5Final
wc_InitMd5
int wc_Md5Final
Synopsis:
#include <wolfssl/wolfcrypt/md5.h>
int wc_Md5Final(md5* md5, byte* hash)
Description:
Finalizes hashing of data. Result is placed into hash. Md5 Struct is reset.
Return Values:
0: Returned upon successfully finalizing.
BAD_FUNC_ARG: Returned if the Md5 structure or hash pointer is passed in NULL.
Note: This function will also return the result of calling IntelQaSymMd5() in the case that HAVE_INTEL_QA is defined.
Parameters:
md5 - pointer to the md5 structure to use for encryption
hash - Byte array to hold hash value.
Example:
md5 md5[1];
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitMd5(md5)) != 0) {
WOLFSSL_MSG("wc_Initmd5 failed");
}
else {
ret = wc_Md5Update(md5, data, len);
if (ret != 0) {
/* Md5 Update Failure Case. */
}
ret = wc_Md5Final(md5, hash);
if (ret != 0) {
/* Md5 Final Failure Case. */
}
}
See Also:
wc_Md5Hash
wc_InitMd5
wc_Md5GetHash
void wc_Md5GetHash
Synopsis:
#include <wolfssl/wolfcrypt/hash.h>
void wc_Md5GetHash(Md5* md5, byte* hash);
Description:
Gets hash data. Result is placed into hash. Md5 struct is not reset.
Return Values:
Parameters:
md5 - pointer to the md5 structure to use for encryption.
hash - Byte array to hold hash value.
Example:
md5 md5[1];
if ((ret = wc_InitMd5(md5)) != 0) {
WOLFSSL_MSG("wc_Initmd5 failed");
}
else {
wc_Md5Update(md5, data, len);
wc_Md5GetHash(md5, hash);
}
See Also:
wc_Md5Hash
wc_Md5Final
wc_InitMd5
wc_Md5RestorePos
Synopsis:
#include <wolfssl/wolfcrypt/hash.h>
void wc_Md5RestorePos(Md5* m1, Md5* m2)
Description:
Sets the value of one Md5 struct equal to another.
Return Values:
No returns.
Parameters:
m1 -
m2 - Description
Example:
Sha m1;
Sha m2;
/* Initialize and use m2 */
wc_Md5RestorePos(&m1, &m2);
See Also:
wc_ShaRestorePos, wc_Sha256RestorPos
wc_Md5Free
Synopsis:
#include <wolfssl/wolfcrypt/hash.h>
void wc_Md5Free(Md5* md5)
Description:
Resets the Md5 structure. Note: this is only supported if you have WOLFSSL_TI_HASH defined.
Return Values:
No returns.
Parameters:
md5 - Pointer to the Md5 structure to be reset.
Example:
Md5 md5;
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitMd5(&md5)) != 0) {
WOLFSSL_MSG("wc_InitMd5 failed");
}
else {
wc_Md5Update(&md5, data, len);
wc_Md5Final(&md5, hash);
wc_Md5Free(&md5);
}
See Also:
wc_InitMd5, wc_Md5Update, wc_Md5Final
18.31 Memory
wolfSSL_SetAllocators
Synopsis:
#include <wolfssl/wolfcrypt/memory.h>
int wolfSSL_SetAllocators(wolfSSL_Malloc_cb mf, wolfSSL_Free_cb ff,
wolfSSL_Realloc_cb rf);
Description:
This function allows a user to plugin custom memory functions to replace malloc, free, and realloc. These functions will be utilized anywhere that memory is allocated by wolfSSL, as long as XMALLOC_USER and NO_WOLFSSL_MEMORY are not defined.
Return Values:
0: Returned upon successfully setting custom memory functions
BAD_FUNC_ARG: Returned if there is an error setting one of the memory functions
Parameters:
mf - pointer to a custom malloc function of the type:
void *(*wolfSSL_Malloc_cb)(size_t size);
ff - pointer to a custom free function of the type:
void (*wolfSSL_Free_cb)(void *ptr);
rf - pointer to a custom realloc function of the type:
void *(*wolfSSL_Realloc_cb)(void *ptr, size_t size);
Example:
void* custMalloc(size_t size) {
printf("Custom malloc: ");
...
}
void* custFree(void* ptr) {
printf("Custom free: ");
...
}
void* custRealloc(void* ptr, size_t size); {
printf("Custom realloc: ");
...
}
wolfSSL_Malloc_cb newMalloc= &custMalloc;
wolfSSL_Free_cb newFree = &custFree;
wolfSSL_Realloc_cb newRealloc = &custRealloc;
if (wolfSSL_SetAllocators(newMalloc, newFree, newRealloc) != 0) {
// error setting custom memory callback functions
}
See Also:
wolfSSL_Malloc, wolfSSL_Free, wolfSSL_Realloc
wolfSSL_Malloc
Synopsis:
#include <wolfssl/wolfcrypt/memory.h>
void* wolfSSL_Malloc(size_t size);
Description:
This function calls the custom malloc function, if one has been defined, or simply calls the default C malloc function if no custom function exists. It is not called directly by wolfSSL, but instead generally called by using XMALLOC, which may be replaced by wolfSSL_Malloc during preprocessing.
Return Values:
On successfully allocating the desired memory, returns a void* to that location
NULL: Returned when there is a failure to allocate memory
Parameters:
size - size, in bytes, of the memory to allocate
Example:
int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10);
See Also:
wolfSSL_Free, wolfSSL_Realloc, XMALLOC, XFREE, XREALLOC
wolfSSL_Free
Synopsis:
#include <wolfssl/wolfcrypt/memory.h>
void wolfSSL_Free(void *ptr);
Description:
This function calls a custom free function, if one has been defined, or simply calls the default C free function if no custom function exists. It is not called directly by wolfSSL, but instead generally called by using XFREE, which may be replaced by wolfSSL_Free during preprocessing.
Return Values:
No return values for this function.
Parameters:
ptr - pointer to the memory to free
Example:
int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10);
// process data as desired
...
if(tenInts) {
wolfSSL_Free(tenInts);
}
See Also:
wolfSSL_Malloc , wolfSSL_Realloc, XMALLOC, XFREE, XREALLOC
wolfSSL_Realloc
Synopsis:
#include <wolfssl/wolfcrypt/memory.h>
void* wolfSSL_Realloc(void *ptr, size_t size);
Description:
This function calls a custom realloc function, if one has been defined, or simply calls the default C realloc function if no custom function exists. It is not called directly by wolfSSL, but instead generally called by using XREALLOC, which may be replaced by wolfSSL_Realloc during preprocessing.
Return Values:
On successfully reallocating the desired memory, returns a void* to that location
NULL: Returned when there is a failure to reallocate memory
Parameters:
ptr - pointer to the memory to the memory to reallocate
size - desired size after reallocation
Example:
int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10);
int* twentyInts = (int*)realloc(tenInts, sizeof(tenInts)*2);
See Also:
wolfSSL_Malloc , wolfSSL_Free, XMALLOC, XFREE, XREALLOC
wolfSSL_StaticBufferSz
Synopsis:
#include <wolfssl/wolfcrypt/memory.h>
int wolfSSL_StaticBufferSz(byte* buffer, word32 size, int type);
Description:
This function is available when static memory feature is used (--enable-staticmemory). It gives the optimum buffer size for memory “buckets”. This allows for a way to compute buffer size so that no extra unused memory is left at the end after it has been partitioned. The returned value, if positive, is the computed buffer size to use.
Return Values:
On successfully completing buffer size calculations a positive value is returned. This returned value is for optimum buffer size. All negative values are considered to be error cases.
Parameters:
buffer - pointer to buffer
size - size of buffer
type - desired type of memory ie WOLFMEM_GENERAL or WOLFMEM_IO_POOL
Example:
byte buffer[1000];
word32 size = sizeof(buffer);
int optimum;
optimum = wolfSSL_StaticBufferSz(buffer, size, WOLFMEM_GENERAL);
if (optimum < 0) { //handle error case }
printf(“The optimum buffer size to make use of all memory is %d\n”, optimum);
...
See Also:
wolfSSL_Malloc , wolfSSL_Free
wolfSSL_MemoryPaddingSz
Synopsis:
#include <wolfssl/wolfcrypt/memory.h>
int wolfSSL_MemoryPaddingSz(void);
Description:
This function is available when static memory feature is used (--enable-staticmemory). It gives the size of padding needed for each partition of memory. This padding size will be the size needed to contain a memory management structure along with any extra for memory alignment.
Return Values:
On successfully memory padding calculation the return value will be a positive value. All negative values are considered error cases.
Parameters:
None
Example:
int padding;
padding = wolfSSL_MemoryPaddingSz();
if (padding < 0) { //handle error case }
printf(“The padding size needed for each \”bucket\” of memory is %d\n”, padding);
// calculation of buffer for IO POOL size is number of buckets times (padding + WOLFMEM_IO_SZ)
...
See Also:
wolfSSL_Malloc , wolfSSL_Free
18.32 PKCS7
wc_PKCS7_InitWithCert
Synopsis:
#include <wolfssl/wolfcrypt/pkcs7.h>
int wc_PKCS7_InitWithCert(PKCS7* pkcs7, byte* cert, word32 certSz);
Description:
This function initializes a PKCS7 structure with a DER-formatted certificate. To initialize an empty PKCS7 structure, one can pass in a NULL cert and 0 for certSz.
Return Values:
0: Returned on successfully initializing the PKCS7 structure
MEMORY_E: Returned if there is an error allocating memory with XMALLOC
ASN_PARSE_E: Returned if there is an error parsing the cert header
ASN_OBJECT_ID_E: Returned if there is an error parsing the encryption type from the cert
ASN_EXPECT_0_E: Returned if there is a formatting error in the encryption specification of the cert file
ASN_BEFORE_DATE_E: Returned if the date is before the certificate start date
ASN_AFTER_DATE_E: Returned if the date is after the certificate expiration date
ASN_BITSTR_E: Returned if there is an error parsing a bit string from the certificate
ASN_NTRU_KEY_E: Returned if there is an error parsing the NTRU key from the certificate
ECC_CURVE_OID_E: Returned if there is an error parsing the ECC key from the certificate
ASN_UNKNOWN_OID_E: Returned if the certificate is using an unknown key object id
ASN_VERSION_E: Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate
BAD_FUNC_ARG: Returned if there is an error processing the certificate extension
ASN_CRIT_EXT_E: Returned if an unfamiliar critical extension is encountered in processing the certificate
ASN_SIG_OID_E: Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file
ASN_SIG_CONFIRM_E: Returned if confirming the certification signature fails
ASN_NAME_INVALID_E: Returned if the certificate’s name is not permitted by the CA name constraints
ASN_NO_SIGNER_E: Returned if there is no CA signer to verify the certificate’s authenticity
Parameters:
pkcs7 - pointer to the PKCS7 structure in which to store the decoded cert
cert - pointer to a buffer containing a DER formatted ASN.1 certificate with which to initialize the PKCS7 structure
certSz - size of the certificate buffer
Example:
PKCS7 pkcs7;
byte derBuff[] = { /* initialize with DER-encoded certificate */ };
if ( wc_PKCS7_InitWithCert(&pkcs7, derBuff, sizeof(derBuff)) != 0 ) {
// error parsing certificate into pkcs7 format
}
See Also:
wc_PKCS7_Free
wc_PKCS7_Free
Synopsis:
#include <wolfssl/wolfcrypt/pkcs7.h>
void wc_PKCS7_Free(PKCS7* pkcs7);
Description:
This function releases any memory allocated by a PKCS7 initializer.
Return Values:
No return value for this function.
Parameters:
pkcs7 - pointer to the PKCS7 structure to free
Example:
PKCS7 pkcs7;
// initialize and use PKCS7 object
wc_PKCS7_Free(pkcs7);
See Also:
wc_PKCS7_InitWithCert
wc_PKCS7_EncodeData
Synopsis:
#include <wolfssl/wolfcrypt/pkcs7.h>
int wc_PKCS7_EncodeData(PKCS7* pkcs7, byte* output, word32 outputSz);
Description:
This function builds the PKCS7 data content type, encoding the PKCS7 structure into a buffer containing a parsable PKCS7 data packet.
Return Values:
On successfully encoding the PKCS7 data into the buffer, returns the index parsed up to in the PKCS7 structure. This index also corresponds to the bytes written to the output buffer.
BUFFER_E: Returned if the given buffer is not large enough to hold the encoded certificate
Parameters:
pkcs7 - pointer to the PKCS7 structure to encode
output - pointer to the buffer in which to store the encoded certificate
outputSz - size available in the output buffer
Example:
PKCS7 pkcs7;
int ret;
byte derBuff[] = { /* initialize with DER-encoded certificate */ };
byte pkcs7Buff[FOURK_BUF];
wc_PKCS7_InitWithCert(&pkcs7, derBuff, sizeof(derBuff));
// update message and data to encode
pkcs7.privateKey = key;
pkcs7.privateKeySz = keySz;
pkcs7.content = data;
pkcs7.contentSz = dataSz;
... etc.
ret = wc_PKCS7_EnocodeData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
if ( ret != 0 ) {
// error encoding into output buffer
}
See Also:
wc_PKCS7_InitWithCert
wc_PKCS7_EncodeSignedData
Synopsis:
#include <wolfssl/wolfcrypt/pkcs7.h>
int wc_PKCS7_EncodeSignedData(PKCS7* pkcs7, byte* output, word32 outputSz);
Description:
This function builds the PKCS7 signed data content type, encoding the PKCS7 structure into a buffer containing a parsable PKCS7 signed data packet.
Return Values:
On successfully encoding the PKCS7 data into the buffer, returns the index parsed up to in the PKCS7 structure. This index also corresponds to the bytes written to the output buffer.
BAD_FUNC_ARG: Returned if the PKCS7 structure is missing one or more required elements to generate a signed data packet
MEMORY_E: Returned if there is an error allocating memory
PUBLIC_KEY_E: Returned if there is an error parsing the public key
RSA_BUFFER_E: Returned if buffer error, output too small or input too large
BUFFER_E: Returned if the given buffer is not large enough to hold the encoded certificate
MP_INIT_E, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error generating the signature
Parameters:
pkcs7 - pointer to the PKCS7 structure to encode
output - pointer to the buffer in which to store the encoded certificate
outputSz - size available in the output buffer
Example:
PKCS7 pkcs7;
int ret;
byte derBuff[] = { /* initialize with DER-encoded certificate */ };
byte pkcs7Buff[FOURK_BUF];
wc_PKCS7_InitWithCert(&pkcs7, derBuff, sizeof(derBuff));
// update message and data to encode
pkcs7.privateKey = key;
pkcs7.privateKeySz = keySz;
pkcs7.content = data;
pkcs7.contentSz = dataSz;
... etc.
ret = wc_PKCS7_EnocodeSignedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
if ( ret != 0 ) {
// error encoding into output buffer
}
See Also:
wc_PKCS7_InitWithCert, wc_PKCS7_VerifySignedData
wc_PKCS7_VerifySignedData
Synopsis:
#include <wolfssl/wolfcrypt/pkcs7.h>
int wc_PKCS7_VerifySignedData(PKCS7* pkcs7, byte* pkiMsg, word32 pkiMsgSz);
Description:
This function takes in a transmitted PKCS7 signed data message, extracts the certificate list and certificate revocation list, and then verifies the signature. It stores the extracted content in the given PKCS7 structure.
Return Values:
0: Returned on successfully extracting the information from the message
BAD_FUNC_ARG: Returned if one of the input parameters is invalid
ASN_PARSE_E: Returned if there is an error parsing from the given pkiMsg
PKCS7_OID_E: Returned if the given pkiMsg is not a signed data type
ASN_VERSION_E: Returned if the PKCS7 signer info is not version 1
MEMORY_E: Returned if there is an error allocating memory
PUBLIC_KEY_E: Returned if there is an error parsing the public key
RSA_BUFFER_E: Returned if buffer error, output too small or input too large
MP_INIT_E, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error during signature verification
Parameters:
pkcs7 - pointer to the PKCS7 structure in which to store the parsed certificates
pkiMsg - pointer to the buffer containing the signed message to verify and decode
pkiMsgSz - size of the signed message
Example:
PKCS7 pkcs7;
int ret;
byte derBuff[] = { /* initialize with DER-encoded certificate */ };
byte pkcs7Buff[FOURK_BUF];
wc_PKCS7_InitWithCert(&pkcs7, derBuff, sizeof(derBuff));
// update message and data to encode
pkcs7.privateKey = key;
pkcs7.privateKeySz = keySz;
pkcs7.content = data;
pkcs7.contentSz = dataSz;
... etc.
ret = wc_PKCS7_EnocodeSignedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
if ( ret != 0 ) {
// error encoding into output buffer
}
See Also:
wc_PKCS7_InitWithCert, wc_PKCS7_EncodeSignedData
wc_PKCS7_EncodeEnvelopedData
Synopsis:
#include <wolfssl/wolfcrypt/pkcs7.h>
int wc_PKCS7_EncodeEnvelopedData(PKCS7* pkcs7, byte* output, word32 outputSz);
Description:
This function builds the PKCS7 enveloped data content type, encoding the PKCS7 structure into a buffer containing a parsable PKCS7 enveloped data packet.
Return Values:
Returned on successfully encoding the message in enveloped data format, returns the size written to the output buffer
BAD_FUNC_ARG: Returned if one of the input parameters is invalid, or if the PKCS7 structure is missing required elements
ALGO_ID_E: Returned if the PKCS7 structure is using an unsupported algorithm type. Currently, only DESb and DES3b are supported
BUFFER_E: Returned if the given output buffer is too small to store the output data
MEMORY_E: Returned if there is an error allocating memory
RNG_FAILURE_E: Returned if there is an error initializing the random number generator for encryption
DRBG_FAILED: Returned if there is an error generating numbers with the random number generator used for encryption
Parameters:
pkcs7 - pointer to the PKCS7 structure to encode
output - pointer to the buffer in which to store the encoded certificate
outputSz - size available in the output buffer
Example:
PKCS7 pkcs7;
int ret;
byte derBuff[] = { /* initialize with DER-encoded certificate */ };
byte pkcs7Buff[FOURK_BUF];
wc_PKCS7_InitWithCert(&pkcs7, derBuff, sizeof(derBuff));
// update message and data to encode
pkcs7.privateKey = key;
pkcs7.privateKeySz = keySz;
pkcs7.content = data;
pkcs7.contentSz = dataSz;
... etc.
ret = wc_PKCS7_EncodeEnvelopedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
if ( ret != 0 ) {
// error encoding into output buffer
}
See Also:
wc_PKCS7_InitWithCert, wc_PKCS7_DecodeEnvelopedData
wc_PKCS7_DecodeEnvelopedData
Synopsis:
#include <wolfssl/wolfcrypt/pkcs7.h>
int wc_PKCS7_DecodeEnvelopedData(PKCS7* pkcs7, byte* pkiMsg, word32 pkiMsgSz,
byte* output, word32 outputSz);
Description:
This function unwraps and decrypts a PKCS7 enveloped data content type, decoding the message into output. It uses the private key of the PKCS7 object passed in to decrypt the message.
Return Values:
On successfully extracting the information from the message, returns the bytes written to output
BAD_FUNC_ARG: Returned if one of the input parameters is invalid
ASN_PARSE_E: Returned if there is an error parsing from the given pkiMsg
PKCS7_OID_E: Returned if the given pkiMsg is not an enveloped data type
ASN_VERSION_E: Returned if the PKCS7 signer info is not version 0
MEMORY_E: Returned if there is an error allocating memory
ALGO_ID_E: Returned if the PKCS7 structure is using an unsupported algorithm type. Currently, only DESb and DES3b are supported for encryption, with RSAk for signature generation
PKCS7_RECIP_E: Returned if there is no recipient found in the enveloped data that matches the recipient provided
RSA_BUFFER_E: Returned if there is an error during RSA signature verification due to buffer error, output too small or input too large.
MP_INIT_E, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error during signature verification
Parameters:
pkcs7 - pointer to the PKCS7 structure containing the private key with which to decode the enveloped data package
pkiMsg - pointer to the buffer containing the enveloped data package
pkiMsgSz - size of the enveloped data package
output - pointer to the buffer in which to store the decoded message
outputSz - size available in the output buffer
Example:
PKCS7 pkcs7;
byte received[] = { /* initialize with received enveloped message */ };
byte decoded[FOURK_BUF];
int decodedSz;
// initialize pkcs7 with certificate
// update key
pkcs7.privateKey = key;
pkcs7.privateKeySz = keySz;
decodedSz = wc_PKCS7_DecodeEnvelopedData(&pkcs7, received, sizeof(received),decoded, sizeof(decoded));
if ( decodedSz != 0 ) {
// error decoding message
}
See Also:
wc_PKCS7_InitWithCert, wc_PKCS7_EncodeEnvelopedData
18.33 Poly1305
wc_Poly1305SetKey
Synopsis:
#include <wolfssl/wolfcrypt/poly1305.h>
int wc_Poly1305SetKey(Poly1305* ctx, const byte* key, word32 keySz) ;
Description:
This function sets the key for a Poly1305 context structure, initializing it for hashing. Note: A new key should be set after generating a message hash with wc_Poly1305Final to ensure security.
Return Values:
0: Returned on successfully setting the key and initializing the Poly1305 structure
BAD_FUNC_ARG: Returned if the given key is not 32 bytes long, or the Poly1305 context is NULL
Parameters:
ctx - pointer to a Poly1305 structure to initialize
key - pointer to the buffer containing the key to use for hashing
keySz - size of the key in the buffer. Should be 32 bytes
Example:
Poly1305 enc;
byte key[] = { /* initialize with 32 byte key to use for hashing */ };
wc_Poly1305SetKey(&enc, key, sizeof(key));
See Also:
wc_Poly1305Update, wc_Poly1305Final
wc_Poly1305Update
Synopsis:
#include <wolfssl/wolfcrypt/poly1305.h>
int wc_Poly1305Update(Poly1305* ctx, const byte* m, word32 bytes);
Description:
This function updates the message to hash with the Poly1305 structure.
Return Values:
0: Returned on successfully updating the message to hash
BAD_FUNC_ARG: Returned if the Poly1305 structure is NULL
Parameters:
ctx - pointer to a Poly1305 structure for which to update the message to hash
m - pointer to the buffer containing the message which should be added to the hash
bytes - size of the message to hash
Example:
Poly1305 enc;
byte key[] = { /* initialize with 32 byte key to use for encryption */ };
byte msg[] = { /* initialize with message to hash */ };
wc_Poly1305SetKey(&enc, key, sizeof(key));
if( wc_Poly1305Update(key, msg, sizeof(msg)) != 0 ) {
// error updating message to hash
}
See Also:
wc_Poly1305SetKey, wc_Poly1305Final
wc_Poly1305Final
Synopsis:
#include <wolfssl/wolfcrypt/poly1305.h>
int wc_Poly1305Final(Poly1305* ctx, byte* mac);
Description:
This function calculates the hash of the input messages and stores the result in mac. After this is called, the key should be reset.
Return Values:
0: Returned on successfully computing the final MAC
BAD_FUNC_ARG: Returned if the Poly1305 structure is NULL
Parameters:
ctx - pointer to a Poly1305 structure with which to generate the MAC
mac - pointer to the buffer in which to store the MAC. Should be POLY1305_DIGEST_SIZE (16 bytes) wide
Example:
Poly1305 enc;
byte mac[POLY1305_DIGEST_SIZE]; // space for a 16 byte mac
byte key[] = { /* initialize with 32 byte key to use for encryption */ };
byte msg[] = { /* initialize with message to hash */ };
wc_Poly1305SetKey(&enc, key, sizeof(key));
wc_Poly1305Update(key, msg, sizeof(msg));
if ( wc_Poly1305Final(&enc, mac) != 0 ) {
// error computing final MAC
}
See Also:
wc_Poly1305SetKey, wc_Poly1305Update
wc_Poly1305_MAC
Synopsis:
#include <wolfssl/wolfcrypt/poly1305.h>
int wc_Poly1305_MAC(Poly1305* ctx, byte* additional, word32 addSz,
byte* input, word32 sz, byte* tag, word32 tagSz)
Description:
Takes in an initialized Poly1305 struct that has a key loaded and creates a MAC (tag) using recent TLS AEAD padding scheme.
Return Values:
0: Success
BAD_FUNC_ARG: Returned if ctx, input, or tag is null or if additional is null and addSz is greater than 0 or if tagSz is less than WC_POLY1305_MAC_SZ.
Parameters:
ctx - Initialized Poly1305 struct to use
additional - Additional data to use
addSz - Size of additional buffer
input - Input buffer to create tag from
sz - Size of input buffer
tag - Buffer to hold created tag
tagSz - Size of input tag buffer (must be at least WC_POLY1305_MAC_SZ(16))
Example:
Poly1305 ctx;
byte key[] = { /* initialize with 32 byte key to use for hashing */ };
byte additional[] = { /* initialize with additional data */ }
byte msg[] = { /* initialize with message */ }
byte tag[16];
wc_Poly1305SetKey(&ctx, key, sizeof(key));
if(wc_Poly1305_MAC(&ctx, additional, sizeof(additional), (byte*)msg,
sizeof(msg), tag, sizeof(tag)) != 0)
{
/* Handle the error */
}
See Also:
wc_Poly1305SetKey, wc_Poly1305Update, wcPoly1305Final
18.34 PWDBASED
wc_PBKDF1
Synopsis:
#include <wolfssl/wolfcrypt/pwdbased.h>
int wc_PBKDF1(byte* output, const byte* passwd, int pLen, const byte* salt, int sLen,
int iterations, int kLen, int hashType);
Description:
This function implements the Password Based Key Derivation Function 1 (PBKDF1), converting an input password with a concatenated salt into a more secure key, which it stores in output. It allows the user to select between SHA and MD5 as hash functions.
Return Values:
0: Returned on successfully deriving a key from the input password
BAD_FUNC_ARG: Returned if there is an invalid hash type given (valid type are: MD5 and SHA), iterations is less than 1, or the key length (kLen) requested is greater than the hash length of the provided hash
MEMORY_E: Returned if there is an error allocating memory for a SHA or MD5 object
Parameters:
output - pointer to the buffer in which to store the generated key. Should be at least kLen long
passwd - pointer to the buffer containing the password to use for the key derivation
pLen - length of the password to use for key derivation
salt - pointer to the buffer containing the salt to use for key derivation
sLen - length of the salt
iterations - number of times to process the hash
kLen - desired length of the derived key. Should not be longer than the digest size of the hash chosen
hashType - the hashing algorithm to use. Valid choices are MD5 and SHA
Example:
int ret;
byte key[MD5_DIGEST_SIZE];
byte pass[] = { /* initialize with password */ };
byte salt[] = { /* initialize with salt */ };
ret = wc_PBKDF1(key, pass, sizeof(pass), salt, sizeof(salt), 1000, sizeof(key), MD5);
if ( ret != 0 ) {
// error deriving key from password
}
See Also:
wc_PBKDF2, wc_PKCS12_PBKDF
wc_PBKDF2
Synopsis:
#include <wolfssl/wolfcrypt/pwdbased.h>
int wc_PBKDF2(byte* output, const byte* passwd, int pLen, const byte* salt, int sLen,
int iterations, int kLen, int hashType);
Description:
This function implements the Password Based Key Derivation Function 2 (PBKDF2), converting an input password with a concatenated salt into a more secure key, which it stores in output. It allows the user to select any of the supported HMAC hash functions, including: MD5, SHA, SHA256, SHA384, SHA512, and BLAKE2B
Return Values:
0: Returned on successfully deriving a key from the input password
BAD_FUNC_ARG: Returned if there is an invalid hash type given or iterations is less than 1
MEMORY_E: Returned if there is an allocating memory for the HMAC object
Parameters:
output - pointer to the buffer in which to store the generated key. Should be kLen long
passwd - pointer to the buffer containing the password to use for the key derivation
pLen - length of the password to use for key derivation
salt - pointer to the buffer containing the salt to use for key derivation
sLen - length of the salt
iterations - number of times to process the hash
kLen - desired length of the derived key
hashType - the hashing algorithm to use. Valid choices are: MD5, SHA, SHA256, SHA384, SHA512, and BLAKE2B
Example:
int ret;
byte key[64];
byte pass[] = { /* initialize with password */ };
byte salt[] = { /* initialize with salt */ };
ret = wc_PBKDF2(key, pass, sizeof(pass), salt, sizeof(salt), 2048, sizeof(key),
SHA512);
if ( ret != 0 ) {
// error deriving key from password
}
See Also:
wc_PBKDF1, wc_PKCS12_PBKDF
wc_PKCS12_PBKDF
Synopsis:
#include <wolfssl/wolfcrypt/pwdbased.h>
int wc_PKCS12_PBKDF(byte* output, const byte* passwd, int passLen,const byte* salt,
int saltLen, int iterations, int kLen, int hashType, int id);
Description:
This function implements the Password Based Key Derivation Function (PBKDF) described in RFC 7292 Appendix B. This function converts an input password with a concatenated salt into a more secure key, which it stores in output. It allows the user to select any of the supported HMAC hash functions, including: MD5, SHA, SHA256, SHA384, SHA512, and BLAKE2B.
Return Values:
0: Returned on successfully deriving a key from the input password
BAD_FUNC_ARG: Returned if there is an invalid hash type given, iterations is less than 1, or the key length (kLen) requested is greater than the hash length of the provided hash
MEMORY_E: Returned if there is an allocating memory
MP_INIT_E, MP_READ_E, MP_CMP_E, MP_INVMOD_E, MP_EXPTMOD_E, MP_MOD_E, MP_MUL_E, MP_ADD_E, MP_MULMOD_E, MP_TO_E, and MP_MEM may be returned if there is an error during key generation
Parameters:
output - pointer to the buffer in which to store the generated key. Should be kLen long
passwd - pointer to the buffer containing the password to use for the key derivation
pLen - length of the password to use for key derivation
salt - pointer to the buffer containing the salt to use for key derivation
sLen - length of the salt
iterations - number of times to process the hash
kLen - desired length of the derived key
hashType - the hashing algorithm to use. Valid choices are: MD5, SHA, SHA256, SHA384, SHA512, and BLAKE2B
id - this is a byte indetifier indicating the purpose of key generation. It is used to diversify the key output, and should be assigned as follows:
ID=1: pseudorandom bits are to be used as key material for performing encryption or decryption.
ID=2: pseudorandom bits are to be used an IV (Initial Value) for encryption or decryption.
ID=3: pseudorandom bits are to be used as an integrity key for MACing.
Example:
int ret;
byte key[64];
byte pass[] = { /* initialize with password */ };
byte salt[] = { /* initialize with salt */ };
ret = wc_PKCS512_PBKDF(key, pass, sizeof(pass), salt, sizeof(salt), 2048,
sizeof(key), SHA512, 1);
if ( ret != 0 ) {
// error deriving key from password
}
See Also:
wc_PBKDF1, wc_PBKDF2
18.35 RABBIT
wc_RabbitSetKey
Synopsis:
#include <wolfssl/wolfcrypt/rabbit.h>
int wc_RabbitSetKey(Rabbit* ctx, const byte* key, const byte* iv);
Description:
This function initializes a Rabbit context for use with encryption or decryption by setting its iv and key.
Return Values:
0: Returned on successfully setting the key and iv
Parameters:
ctx - pointer to the Rabbit structure to initialize
key - pointer to the buffer containing the 16 byte key to use for encryption/decryption
iv - pointer to the buffer containing the 8 byte iv with which to initialize the Rabbit structure
Example:
int ret;
Rabbit enc;
byte key[] = { /* initialize with 16 byte key */ };
byte iv[] = { /* initialize with 8 byte iv */ };
wc_RabbitSetKey(&enc, key, iv);
See Also:
wc_RabbitProcess
wc_RabbitProcess
Synopsis:
#include <wolfssl/wolfcrypt/rabbit.h>
int wc_RabbitProcess(Rabbit* ctx, byte* output, const byte* input, word32 msglen);
Description:
This function encrypts or decrypts a message of any size, storing the result in output. It requires that the Rabbit ctx structure be initialized with a key and an iv before encryption.
Return Values:
0: Returned on successfully encrypting/decrypting input
BAD_ALIGN_E: Returned if the input message is not 4-byte aligned but is required to be by XSTREAM_ALIGN, but NO_WOLFSSL_ALLOC_ALIGN is defined
MEMORY_E: Returned if there is an error allocating memory to align the message, if NO_WOLFSSL_ALLOC_ALIGN is not defined
Parameters:
ctx - pointer to the Rabbit structure to use for encryption/decryption
output - pointer to the buffer in which to store the processed message. Should be at least msglen long
input - pointer to the buffer containing the message to process
msglen - the length of the message to process
Example:
int ret;
Rabbit enc;
byte key[] = { /* initialize with 16 byte key */ };
byte iv[] = { /* initialize with 8 byte iv */ };
wc_RabbitSetKey(&enc, key, iv);
byte message[] = { /* initialize with plaintext message */ };
byte ciphertext[sizeof(message)];
wc_RabbitProcess(enc, ciphertext, message, sizeof(message));
See Also:
wc_RabbitSetKey
18.36 SRP
wc_SrpInit
Synopsis:
#include <wolfssl/wolfcrypt/srp.h>
int wc_SrpInit(Srp* srp, SrpType type, SrpSide side);
Description:
Initializes the Srp struct for usage.
Return Values:
BAD_FUNC_ARG: Returns when there's an issue with the arguments such as srp being null or SrpSide not being SRP_CLIENT_SIDE or SRP_SERVER_SIDE.
NOT_COMPILED_IN: Returns when a type is passed as an argument but hasn't been configured in the wolfCrypt build.
0: on success.
< 0: on error.
Parameters:
srp - the Srp structure to be initialized.
type - the hash type to be used.
side - the side of the communication.
Example:
Srp srp;
if (wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE) != 0)
{
/* Initialization error */
}
else
{
wc_SrpTerm(&srp);
}
See Also:
wc_SrpTerm
wc_SrpSetUsername
wc_SrpSetUsername
Synopsis:
#include <wolfssl/wolfcrypt/srp.h>
int wc_SrpSetUsername(Srp* srp, const byte* username, word32 size);
Description:
Sets the username. This function MUST be called after wc_SrpInit.
Return Values:
0: Username set successfully.
BAD_FUNC_ARG: Return if srp or username is null.
MEMORY_E: Returns if there is an issue allocating memory for srp->user
< 0: Error.
Parameters:
srp - the Srp structure.
username - the buffer containing the username.
size - the username size in bytes
Example:
Srp srp;
byte username[] = "user";
word32 usernameSize = 4;
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE);
if(wc_SrpSetUsername(&srp, username, usernameSize) != 0)
{
/* Error occurred setting username. */
}
wc_SrpTerm(&srp);
See Also:
wc_SrpInit
wc_SrpSetParams
wc_SrpTerm
wc_SrpSetParams
Synopsis:
#include <wolfssl/wolfcrypt/srp.h>
int wc_SrpSetParams(Srp* srp, const byte* N, word32 nSz,
const byte* g, word32 gSz,
const byte* salt, word32 saltSz);
Description:
Sets the srp parameters based on the username.. Must be called after wc_SrpSetUsername.
Return Values:
0: Success
BAD_FUNC_ARG: Returns if srp, N, g, or salt is null or if nSz < gSz.
SRP_CALL_ORDER_E: Returns if wc_SrpSetParams is called before
wc_SrpSetUsername.
< 0: Error
Parameters:
srp - the Srp structure.
N - the Modulus. N = 2q+1, [q, N] are primes.
nSz - the N size in bytes.
g - the Generator modulo N.
gSz - the g size in bytes
salt - a small random salt. Specific for each username.
saltSz - the salt size in bytes
Example:
Srp srp;
byte username[] = "user";
word32 usernameSize = 4;
byte N[] = { /* Contents of byte array N */ };
byte g[] = { /* Contents of byte array g */ };
byte salt[] = { /* Contents of byte array salt */ };
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE);
wc_SrpSetUsername(&srp, username, usernameSize);
if(wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt)) != 0)
{
/* Error setting params */
}
wc_SrpTerm(&srp);
See Also:
wc_SrpInit
wc_SrpSetUsername
wc_SrpTerm
wc_SrpSetPassword
Synopsis:
#include <wolfssl/wolfcrypt/srp.h>
int wc_SrpSetPassword(Srp* srp, const byte* password, word32 size);
Description:
Sets the password. Setting the password does not persists the clear password data in the srp structure. The client calculates x = H(salt + H(user:pswd)) and stores it in the auth field.
This function MUST be called after wc_SrpSetParams and is CLIENT SIDE ONLY.
Return Values:
0: Success
BAD_FUNC_ARG: Returns if srp or password is null or if srp->side is not set to
SRP_CLIENT_SIDE.
SRP_CALL_ORDER_E: Returns when wc_SrpSetPassword is called out of order.
< 0: Error
Parameters:
srp - The Srp structure.
password - The buffer containing the password.
size - The size of the password in bytes.
Example:
Srp srp;
byte username[] = "user";
word32 usernameSize = 4;
byte password[] = "password";
word32 passwordSize = 8;
byte N[] = { /* Contents of byte array N */ };
byte g[] = { /* Contents of byte array g */ };
byte salt[] = { /* Contents of byte array salt */ };
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE);
wc_SrpSetUsername(&srp, username, usernameSize);
wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt));
if(wc_SrpSetPassword(&srp, password, passwordSize) != 0)
{
/* Error setting password */
}
wc_SrpTerm(&srp);
See Also:
wc_SrpInit
wc_SrpSetUsername
wc_SrpSetParams
wc_SrpSetVerifier
Synopsis:
#include <wolfssl/wolfcrypt/srp.h>
int wc_SrpSetVerifier(Srp* srp, const byte* verifier, word32 size);
Description:
Sets the verifier. This function MUST be called after wc_SrpSetParams and is SERVER SIDE ONLY.
Return Values:
0: Success
BAD_FUNC_ARG: Returned if srp or verifier is null or srp->side is not
SRP_SERVER_SIDE.
< 0: Error
Parameters:
srp - The Srp structure.
verifier - The structure containing the verifier.
size - The verifier size in bytes.
Example:
Srp srp;
byte username[] = "user";
word32 usernameSize = 4;
byte N[] = { /* Contents of byte array N */ };
byte g[] = { /* Contents of byte array g */ };
byte salt[] = { /* Contents of byte array salt */ };
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_SERVER_SIDE);
wc_SrpSetUsername(&srp, username, usernameSize);
wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt))
byte verifier[] = { /* Contents of some verifier */ };
if(wc_SrpSetVerifier(&srp, verifier, sizeof(verifier)) != 0)
{
/* Error setting verifier */
}
wc_SrpTerm(&srp);
See Also:
wc_SrpInit
wc_SrpSetParams
wc_SrpGetVerifier
wc_SrpGetVerifier
Synopsis:
#include <wolfssl/wolfcrypt/srp.h>
int wc_SrpGetVerifier(Srp* srp, byte* verifier, word32* size);
Description:
Gets the verifier. The client calculates the verifier with v = g ^ x % N. This function MAY be called after wc_SrpSetPassword and is CLIENT SIDE ONLY.
Return Values:
0: Success
BAD_FUNC_ARG: Returned if srp, verifier or size is null or if srp->side is not
SRP_CLIENT_SIDE.
SRP_CALL_ORDER_E: Returned if wc_SrpGetVerifier is called out of order.
< 0: Error
Parameters:
srp - The Srp structure.
verifier - The buffer to write the verifier.
size - Buffer size in bytes. Updated with the verifier size.
Example:
Srp srp;
byte username[] = "user";
word32 usernameSize = 4;
byte password[] = "password";
word32 passwordSize = 8;
byte N[] = { /* Contents of byte array N */ };
byte g[] = { /* Contents of byte array g */ };
byte salt[] = { /* Contents of byte array salt */ };
byte v[64];
word32 vSz = 0;
vSz = sizeof(v);
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE);
wc_SrpSetUsername(&srp, username, usernameSize);
wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt))
wc_SrpSetPassword(&srp, password, passwordSize)
if( wc_SrpGetVerifier(&srp, v, &vSz ) != 0)
{
/* Error getting verifier */
}
wc_SrpTerm(&srp);
See Also:
wc_SrpSetVerifier
wc_SrpSetPassword
wc_SrpSetPrivate
Synopsis:
#include <wolfssl/wolfcrypt/srp.h>
int wc_SrpSetPrivate(Srp* srp, const byte* priv, word32 size);
Description:
Sets the private ephemeral value. The private ephemeral value is known as:
- a at the client side. a = random()
- b at the server side. b = random()
This function is handy for unit test cases or if the developer wants to use an external random source to set the ephemeral value. This function MAY be called before wc_SrpGetPublic.
Return Values:
0: Success
BAD_FUNC_ARG: Returned if srp, private, or size is null.
SRP_CALL_ORDER_E: Returned if wc_SrpSetPrivate is called out of order.
< 0: Error
Parameters:
srp - the Srp structure.
priv - the ephemeral value.
size - the private size in bytes.
Example:
Srp srp;
byte username[] = "user";
word32 usernameSize = 4;
byte N[] = { /* Contents of byte array N */ };
byte g[] = { /* Contents of byte array g */ };
byte salt[] = { /* Contents of byte array salt */ };
byte verifier = { /* Contents of some verifier */ };
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_SERVER_SIDE);
wc_SrpSetUsername(&srp, username, usernameSize);
wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt))
wc_SrpSetVerifier(&srp, verifier, sizeof(verifier))
byte b[] = { /* Some ephemeral value */ }
if( wc_SrpSetPrivate(&srp, b, sizeof(b)) != 0)
{
/* Error setting private ephemeral */
}
wc_SrpTerm(&srp);
See Also:
wc_SrpGetPublic
wc_SrpGetPublic
Synopsis:
#include <wolfssl/wolfcrypt/srp.h>
int wc_SrpGetPublic(Srp* srp, byte* pub, word32* size);
Description:
Gets the public ephemeral value. The public ephemeral value is known as:
- A at the client side. A = g ^ a % N
- B at the server side. B = (k * v + (g ˆ b % N)) % N
This function MUST be called after wc_SrpSetPassword or wc_SrpSetVerifier. The function wc_SrpSetPrivate may be called before wc_SrpGetPublic.
Return Values:
0: Success
BAD_FUNC_ARG: Returned if srp, pub, or size is null.
SRP_CALL_ORDER_E: Returned if wc_SrpGetPublic is called out of order.
BUFFER_E: Returned if size < srp.N.
< 0: Error
Parameters:
srp - the Srp structure.
pub - the buffer to write the public ephemeral value.
size - the the buffer size in bytes. Will be updated with the ephemeral value size.
Example:
Srp srp;
byte username[] = "user";
word32 usernameSize = 4;
byte password[] = "password";
word32 passwordSize = 8;
byte N[] = { /* Contents of byte array N */ };
byte g[] = { /* Contents of byte array g */ };
byte salt[] = { /* Contents of byte array salt */ };
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE);
wc_SrpSetUsername(&srp, username, usernameSize);
wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt));
wc_SrpSetPassword(&srp, password, passwordSize)
byte public[64];
word32 publicSz = 0;
if( wc_SrpGetPublic(&srp, public, &publicSz) != 0)
{
/* Error getting public ephemeral */
}
wc_SrpTerm(&srp);
See Also:
wc_SrpSetPrivate
wc_SrpSetPassword
wc_SrpSetVerifier
wc_SrpComputeKey
Synopsis:
#include <wolfssl/wolfcrypt/srp.h>
int wc_SrpComputeKey(Srp* srp,
byte* clientPubKey, word32 clientPubKeySz,
byte* serverPubKey, word32 serverPubKeySz);
Description:
Computes the session key. The key can be accessed at srp->key after success.
Return Values:
0: Success
BAD_FUNC_ARG: Returned if srp, clientPubKey, or serverPubKey or if
clientPubKeySz or serverPubKeySz is 0.
SRP_CALL_ORDER_E: Returned if wc_SrpComputeKey is called out of order.
< 0: Error
Parameters:
srp - the Srp structure.
clientPubKey - the client's public ephemeral value.
clientPubKeySz - the client's public ephemeral value size.
serverPubKey - the server's public ephemeral value.
serverPubKeySz - the server's public ephemeral value size.
Example:
Srp server;
byte username[] = "user";
word32 usernameSize = 4;
byte password[] = "password";
word32 passwordSize = 8;
byte N[] = { /* Contents of byte array N */ };
byte g[] = { /* Contents of byte array g */ };
byte salt[] = { /* Contents of byte array salt */ };
byte verifier[] = { /* Contents of some verifier */ };
byte serverPubKey[] = { /* Contents of server pub key */ };
word32 serverPubKeySize = sizeof(serverPubKey);
byte clientPubKey[64]; /* Buffer */
word32 clientPubKeySize = 64;
wc_SrpInit(&server, SRP_TYPE_SHA, SRP_SERVER_SIDE);
wc_SrpSetUsername(&server, username, usernameSize);
wc_SrpSetParams(&server, N, sizeof(N), g, sizeof(g), salt, sizeof(salt));
wc_SrpSetVerifier(&server, verifier, sizeof(verifier));
wc_SrpGetPublic(&server, serverPubKey, &serverPubKeySize);
wc_SrpComputeKey(&server, clientPubKey, clientPubKeySz,
serverPubKey, serverPubKeySize)
wc_SrpTerm(&server);
See Also:
wc_SrpGetPublic
wc_SrpGetProof
Synopsis:
#include <wolfssl/wolfcrypt/srp.h>
int wc_SrpGetProof(Srp* srp, byte* proof, word32* size);
Description:
Gets the proof. This function MUST be called after wc_SrpComputeKey.
Return Values:
0: Success
BAD_FUNC_ARG: Returns if srp, proof, or size is null.
BUFFER_E: Returns if size is less than the hash size of srp->type.
< 0: Error
Parameters:
srp - the Srp structure.
proof - the peers proof.
size - the proof size in bytes.
Example:
Srp cli;
byte clientProof[SRP_MAX_DIGEST_SIZE];
word32 clientProofSz = SRP_MAX_DIGEST_SIZE;
/* Initialize Srp following steps from previous examples */
if (wc_SrpGetProof(&cli, clientProof, &clientProofSz) != 0)
{
/* Error getting proof */
}
See Also:
wc_SrpComputeKey
wc_SrpVerifyPeersProof
Synopsis:
#include <wolfssl/wolfcrypt/srp.h>
int wc_SrpVerifyPeersProof(Srp* srp, byte* proof, word32 size);
Description:
Verifies the peers proof. This function MUST be called before wc_SrpGetSessionKey.
Return Values:
0: Success
< 0: Error
Parameters:
srp - the Srp structure.
proof - the peers proof.
size - the proof size in bytes.
Example:
Srp cli;
Srp srv;
byte clientProof[SRP_MAX_DIGEST_SIZE];
word32 clientProofSz = SRP_MAX_DIGEST_SIZE;
/* Initialize Srp following steps from previous examples */
/* First get the proof */
wc_SrpGetProof(&cli, clientProof, &clientProofSz)
if (wc_SrpVerifyPeersProof(&srv, clientProof, clientProofSz) != 0)
{
/* Error verifying proof */
}
See Also:
wc_SrpGetSessionKey
wc_SrpGetProof
wc_SrpTerm
wc_SrpTerm
Synopsis:
#include <wolfssl/wolfcrypt/srp.h>
void wc_SrpTerm(Srp* srp);
Description:
Releases the Srp struct resources after usage.
Return Values:
Parameters:
srp - Pointer to the Srp structure to be terminated.
Example:
Srp srp;
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE);
/* Use srp */
wc_SrpTerm(&srp)
See Also:
wc_SrpInit
18.37 Types
CheckRunTimeFastMath
Synopsis:
#include <wolfssl/wolfcrypt/tfm.h>
word32 CheckRunTimeFastMath(void);
Description:
This function checks the runtime fastmath settings for the maximum size of an integer. It is important when a user is using a wolfCrypt library independently, as the FP_SIZE must match for each library in order for math to work correctly. This check is defined as CheckFastMathSettings(), which simply compares CheckRunTimeFastMath and FP_SIZE, returning 0 if there is a mismatch, or 1 if they match.
Return Values:
Returns FP_SIZE, corresponding to the max size available for the math library.
Parameters:
No parameters for this function.
Example:
if (CheckFastMathSettings() != 1) {
return err_sys("Build vs. runtime fastmath FP_MAX_BITS mismatch\n");
}
/* This is converted by the preprocessor to:
* if ( (CheckRunTimeFastMath() == FP_SIZE) != 1) {
* and confirms that the fast math settings match
* the compile time settings
*/
See Also:
CheckRunTimeSettings
CheckRunTimeSettings
Synopsis:
#include <wolfssl/wolfcrypt/types.h>
word32 CheckRunTimeSettings(void);
Description:
This function checks the compile time class settings. It is important when a user is using a wolfCrypt library independently, as the settings must match between libraries for math to work correctly. This check is defined as CheckCtcSettings(), which simply compares CheckRunTimeSettings and CTC_SETTINGS, returning 0 if there is a mismatch, or 1 if they match.
Return Values:
Returns the runtime CTC_SETTINGS (Compile Time Settings)
Parameters:
No parameters for this function.
Example:
if (CheckCtcSettings() != 1) {
return err_sys("Build vs. runtime math mismatch\n");
}
/* This is converted by the preprocessor to:
* if ( (CheckCtcSettings() == CTC_SETTINGS) != 1) {
* and will compare whether the compile time class settings
* match the current settings
*/
See Also:
CheckRunTimeFastMath
XMALLOC, XREALLOC, XFREE
Synopsis:
#include <wolfssl/wolfcrypt/types.h>
void* XMALLOC(size_t n, void* heap, int type);
void *XREALLOC(void *p, size_t n, void* heap, int type);
void XFREE(void *p, void* heap, int type);
Description:
This is not actually a function, but rather a preprocessor macro, which allows the user to substitute in their own malloc, realloc, and free functions in place of the standard C memory functions.
To use external memory functions, define XMALLOC_USER. This will cause the memory functions to be replaced by external functions of the form:
extern void *XMALLOC(size_t n, void* heap, int type);
extern void *XREALLOC(void *p, size_t n, void* heap, int type);
extern void XFREE(void *p, void* heap, int type);
To use the basic C memory functions in place of wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This will replace the memory functions with:
#define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s)))
#define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));}
#define XREALLOC(p, n, h, t) realloc((p), (n))
If none of these options are selected, the system will default to use the wolfSSL memory functions. A user can set custom memory functions through callback hooks, (see wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free). This option will replace the memory functions with:
#define XMALLOC(s, h, t) ((void)h, (void)t, wolfSSL_Malloc((s)))
#define XFREE(p, h, t) {void* xp = (p); if((xp)) wolfSSL_Free((xp));}
#define XREALLOC(p, n, h, t) wolfSSL_Realloc((p), (n))
Return Values:
XMALLOC -
Return a pointer to allocated memory on success
NULL on failure
XREALLOC -
Return a pointer to allocated memory on success
NULL on failure
XFREE -
No return values for this function
Parameters:
XMALLOC -
s - size of memory to allocate
h - (used by custom XMALLOC function) pointer to the heap to use
t - memory allocation types for user hints. See enum in types.h
XREALLOC -
p - pointer to the address to reallocate
n - size of memory to allocate
h - (used by custom XREALLOC function) pointer to the heap to use
t - memory allocation types for user hints. See enum in types.h
XFREE -
p - pointer to the address to free
h - (used by custom XFREE function) pointer to the heap to use
t - memory allocation types for user hints. See enum in types.h
Example:
int* 10 ints = XMALLOC(10 * sizeof(int), NULL, DYNAMIC_TYPE_TMP_BUFFER);
if ( ints == NULL) {
// error allocating space
return MEMORY_E;
}
See Also:
wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free, wolfSSL_SetAllocators
18.38 Wrappers
See https://github.com/wolfSSL/wolfssl-examples/tree/master/signature for complete example of these wrappers.
wc_HashGetDigestSize
Synopsis:
#include <wolfssl/wolfcrypt/hash.h>
int wc_HashGetDigestSize(enum wc_HashType hash_type);
Description:
This function returns the size of the digest (output) for a hash_type. The returns size is used to make sure the output buffer provided to wc_Hash is large enough.
Return Values:
Returns HASH_TYPE_E if hash_type is not supported. Returns BAD_FUNC_ARG if an invalid hash_type was used. A positive return value indicates the digest size for the hash.
Parameters:
hash_type - A hash type from the “enum wc_HashType” such as “WC_HASH_TYPE_SHA256”.
Example:
int hash_len = wc_HashGetDigestSize(hash_type);
if (hash_len <= 0) {
WOLFSSL_MSG("Invalid hash type/len");
return BAD_FUNC_ARG;
}
See Also:
wc_Hash
wc_Hash
Synopsis:
#include <wolfssl/wolfcrypt/hash.h>
int wc_Hash(
enum wc_HashType hash_type,
const byte* data, word32 data_len,
byte* hash, word32 hash_len);
Description:
This function performs a hash on the provided data buffer and returns it in the hash buffer provided.
Return Values:
0 = Success, else error (such as BAD_FUNC_ARG or BUFFER_E).
Parameters:
hash_type - A hash type from the “enum wc_HashType” such as “WC_HASH_TYPE_SHA256”.
data - Pointer to buffer containing the data to hash.
data_len - Length of the data buffer.
hash - Pointer to buffer used to output the final hash to.
hash_len - Length of the hash buffer.
Example:
enum wc_HashType hash_type = WC_HASH_TYPE_SHA256;
int hash_len = wc_HashGetDigestSize(hash_type);
if (hash_len > 0) {
int ret = wc_Hash(hash_type, data, data_len, hash_data, hash_len);
if(ret == 0) {
/* Success */
}
}
See Also:
wc_HashGetDigestSize
wc_HashGetOID
Synopsis:
#include <wolfssl/wolfcrypt/hash.h>
int wc_HashGetOID(enum wc_HashType hash_type);
Description:
This function will return the OID for the wc_HashType provided.
Return Values:
OID > 0, else error (such as HASH_TYPE_E or BAD_FUNC_ARG).
Parameters:
hash_type - A hash type from the “enum wc_HashType” such as “WC_HASH_TYPE_SHA256”.
Example:
enum wc_HashType hash_type = WC_HASH_TYPE_SHA256;
int oid = wc_HashGetOID(hash_type);
if (oid > 0) {
/* Success */
}
See Also:
wc_HashGetDigestSize
wc_Hash
wc_SignatureGetSize
Synopsis:
#include <wolfssl/wolfcrypt/signature.h>
int wc_SignatureGetSize(
enum wc_SignatureType sig_type,
const void* key, word32 key_len);
Description:
This function returns the maximum size of the resulting signature.
Return Values:
Returns SIG_TYPE_E if sig_type is not supported. Returns BAD_FUNC_ARG if sig_type was invalid. A positive return value indicates the maximum size of a signature.
Parameters:
sig_type - A signature type enum value such as WC_SIGNATURE_TYPE_ECC or WC_SIGNATURE_TYPE_RSA.
key - Pointer to a key structure such as ecc_key or RsaKey.
key_len - Size of the key structure.
Example:
/* Get signature length */
enum wc_SignatureType sig_type = WC_SIGNATURE_TYPE_ECC;
ecc_key eccKey;
word32 sigLen;
wc_ecc_init(&eccKey);
sigLen = wc_SignatureGetSize(sig_type, &eccKey, sizeof(eccKey));
if (sigLen > 0) {
/* Success */
}
See Also:
wc_HashGetDigestSize
wc_SignatureGenerate
wc_SignatureVerify
wc_SignatureVerify
Synopsis:
#include <wolfssl/wolfcrypt/signature.h>
int wc_SignatureVerify(
enum wc_HashType hash_type, enum wc_SignatureType sig_type,
const byte* data, word32 data_len,
const byte* sig, word32 sig_len,
const void* key, word32 key_len)
Description:
This function validates a signature by hashing the data and using the resulting hash and key to verify the signature.
Return Values:
0 = Success, else error (such as SIG_TYPE_E, BAD_FUNC_ARG or BUFFER_E).
Parameters:
hash_type - A hash type from the “enum wc_HashType” such as “WC_HASH_TYPE_SHA256”.
sig_type - A signature type enum value such as WC_SIGNATURE_TYPE_ECC or WC_SIGNATURE_TYPE_RSA.
data - Pointer to buffer containing the data to hash.
data_len - Length of the data buffer.
sig - Pointer to buffer to output signature.
sig_len - Length of the signature output buffer.
key - Pointer to a key structure such as ecc_key or RsaKey.
key_len - Size of the key structure.
Example:
int ret;
ecc_key eccKey;
/* Import the public key */
wc_ecc_init(&eccKey);
ret = wc_ecc_import_x963(eccPubKeyBuf, eccPubKeyLen, &eccKey);
/* Perform signature verification using public key */
ret = wc_SignatureVerify(
WC_HASH_TYPE_SHA256, WC_SIGNATURE_TYPE_ECC,
fileBuf, fileLen,
sigBuf, sigLen,
&eccKey, sizeof(eccKey));
printf("Signature Verification: %s (%d)\n", (ret == 0) ? "Pass" : "Fail", ret);
wc_ecc_free(&eccKey);
See Also:
wc_SignatureGetSize
wc_SignatureGenerate
wc_SignatureGenerate
Synopsis:
#include <wolfssl/wolfcrypt/signature.h>
int wc_SignatureGenerate(
enum wc_HashType hash_type, enum wc_SignatureType sig_type,
const byte* data, word32 data_len,
byte* sig, word32 *sig_len,
const void* key, word32 key_len, RNG* rng);
Description:
This function generates a signature from the data using a key. It first creates a hash of the data then signs the hash using the key.
Return Values:
0 = Success, else error (such as SIG_TYPE_E, BAD_FUNC_ARG or BUFFER_E).
Parameters:
hash_type - A hash type from the “enum wc_HashType” such as “WC_HASH_TYPE_SHA256”.
sig_type - A signature type enum value such as WC_SIGNATURE_TYPE_ECC or WC_SIGNATURE_TYPE_RSA.
data - Pointer to buffer containing the data to hash.
data_len - Length of the data buffer.
sig - Pointer to buffer to output signature.
sig_len - Length of the signature output buffer.
key - Pointer to a key structure such as ecc_key or RsaKey.
key_len - Size of the key structure.
rng - Pointer to an initialized RNG structure.
Example:
int ret;
RNG rng;
ecc_key eccKey;
/* Init */
wc_InitRng(&rng);
wc_ecc_init(&eccKey);
/* Generate key */
ret = wc_ecc_make_key(&rng, 32, &eccKey);
/* Get signature length and allocate buffer */
sigLen = wc_SignatureGetSize(sig_type, &eccKey, sizeof(eccKey));
sigBuf = malloc(sigLen);
/* Perform signature verification using public key */
ret = wc_SignatureGenerate(
WC_HASH_TYPE_SHA256, WC_SIGNATURE_TYPE_ECC,
fileBuf, fileLen,
sigBuf, &sigLen,
&eccKey, sizeof(eccKey),
&rng);
printf("Signature Generation: %s (%d)\n", (ret == 0) ? "Pass" : "Fail", ret);
free(sigBuf);
wc_ecc_free(&eccKey);
wc_FreeRng(&rng);
See Also:
wc_SignatureGetSize
wc_SignatureVerify
18.39 IDEA
wc_IdeaSetKey
Synopsis:
#include <wolfssl/wolfcrypt/idea.h>
int wc_IdeaSetKey(Idea *idea, const byte* key, word16 keySz,
const byte *iv, int dir)
Description:
Generate the 52, 16-bit key sub-blocks from the 128 key.
Return Values:
0: Success
BAD_FUNC_ARG: Returns if idea or key is null, keySz is not equal to IDEA_KEY_SIZE, or dir is not IDEA_ENCRYPTION or IDEA_DECRYPTION.
Parameters:
idea - Pointer to Idea structure.
key - Pointer to key in memory.
keySz - Size of key.
iv - Value for IV in Idea structure. Can be null.
dir - Direction, either IDEA_ENCRYPTION or IDEA_DECRYPTION
Example:
byte v_key[IDEA_KEY_SIZE] = { /* Some Key */ }
Idea idea;
int ret = wc_IdeaSetKey(&idea v_key, IDEA_KEY_SIZE, NULL, IDEA_ENCRYPTION);
if (ret != 0)
{
/* There was an error */
}
See Also:
wc_IdeaSetIV
wc_IdeaSetIV
Synopsis:
#include <wolfssl/wolfcrypt/idea.h>
int wc_IdeaSetIV(Idea *idea, const byte* iv);
Description:
Sets the IV in an Idea key structure.
Return Values:
0: Success
BAD_FUNC_ARG: Returns if idea is null.
Parameters:
idea - Pointer to idea key structure.
iv - The IV value to set, can be null.
Example:
Idea idea;
/* Initialize idea */
byte iv[] = { /* Some IV */ }
int ret = wc_IdeaSetIV(&idea, iv);
if(ret != 0)
{
/* Some error occured */
}
See Also:
wc_IdeaSetKey
wc_IdeaCipher
Synopsis:
#include <wolfssl/wolfcrypt/idea.h>
void wc_IdeaCipher(Idea *idea, byte* out, const byte* in)
Description:
Encryption or decryption for a block (64 bits).
Return Values:
Parameters:
idea - Pointer to idea key structure.
out - Pointer to destination.
in - Pointer to input data to encrypt or decrypt.
Example:
byte v_key[IDEA_KEY_SIZE] = { /* Some Key */ }
byte data[IDEA_BLOCK_SIZE] = { /* Some encrypted data */ }
Idea idea;
wc_IdeaSetKey(&idea, v_key, IDEA_KEY_SIZE, NULL, IDEA_DECRYPTION);
int ret = wc_IdeaCipher(&idea, data, data);
if (ret != 0)
{
/* There was an error */
}
See Also:
wc_IdeaSetKey, wc_IdeaSetIV, wc_IdeaCbcEncrypt, wc_IdeaCbcDecrypt
wc_IdeaCbcEncrypt
Synopsis:
#include <wolfssl/wolfcrypt/idea.h>
int wc_IdeaCbcEncrypt(Idea *idea, byte* out, const byte* in, word32 len);
Description:
Encrypt data using IDEA CBC mode.
Return Values:
0: Success
BAD_FUNC_ARG: Returns if any arguments are null.
Parameters:
idea - Pointer to Idea key structure.
out - Pointer to destination for encryption.
in - Pointer to input for encryption.
len - length of input.
Example:
Idea idea;
/* Initialize idea structure for encryption*/
const char *message = "International Data Encryption Algorithm";
byte msg_enc[40], msg_dec[40];
memset(msg_enc, 0, sizeof(msg_enc));
ret = wc_IdeaCbcEncrypt(&idea, msg_enc, (byte *)message,
(word32)strlen(message)+1);
if(ret != 0)
{
/* Some error occured */
}
See Also:
wc_IdeaCbcDecrypt, wc_IdeaCipher, wc_IdeaSetKey
wc_IdeaCbcDecrypt
Synopsis:
#include <wolfssl/wolfcrypt/idea.h>
int wc_IdeaCbcDecrypt(Idea *idea, byte* out, const byte* in, word32 len);
Description:
Decrypt data using IDEA CBC mode.
Return Values:
0: Success
BAD_FUNC_ARG: Returns if any arguments are null.
Parameters:
idea - Pointer to Idea key structure.
out - Pointer to destination for encryption.
in - Pointer to input for encryption.
len - length of input.
Example:
Idea idea;
/* Initialize idea structure for decryption*/
const char *message = "International Data Encryption Algorithm";
byte msg_enc[40], msg_dec[40];
memset(msg_dec, 0, sizeof(msg_dec));
ret = wc_IdeaCbcDecrypt(&idea, msg_dec, msg_enc,
(word32)strlen(message)+1);
if(ret != 0)
{
/* Some error occured */
}
See Also:
wc_IdeaCbcEncrypt, wc_IdeaCipher, wc_IdeaSetKey
18.40 TI-Hash
wc_InitSha224
Synopsis:
#include <wolfssl/wolfcrypt/port/ti/ti-hash.h>
int wc_InitSha224(Sha224* sha224)
Description:
Used to initialize a Sha224 struct.
Return Values:
0: Success
1: Error returned because sha224 is null.
Parameters:
sha224 - Pointer to a Sha224 struct to initialize.
Example:
Sha224 sha224;
if(wc_InitSha224(&sha224) != 0)
{
/* Handle error */
}
See Also:
wc_Sha224Hash, wc_Sha224Update, wc_Sha224Final
wc_Sha224Hash
Synopsis:
#include <wolfssl/wolfcrypt/port/ti/ti-hash.h>
int wc_Sha224Hash(const byte* data, word32 len, byte* hash)
Description:
Description
Return Values:
0: Success
< 0: Error
Parameters:
data - the data to hash
len - the length of data
hash - Byte array to hold hash value.
Example:
Example Code
See Also:
wc_InitSha224, wc_Sha224Update, wc_Sha224Final
wc_Sha224Update
Synopsis:
#include <wolfssl/wolfcrypt/port/ti/ti-hash.h>
int wc_Sha224Update(Sha224* sha224, const byte* data, word32 len)
Description:
Can be called to continually hash the provided byte array of length len.
Return Values:
0: Success
1: Error returned if function fails.
BAD_FUNC_ARG: Error returned if sha224 or data is null.
Parameters:
sha224 - Pointer to the Sha224 structure to use for encryption.
data - Data to be hashed.
len - Length of data to be hashed.
Example:
Sha224 sha224;
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitSha224(&sha224)) != 0) {
WOLFSSL_MSG("wc_InitSha224 failed");
}
else {
wc_Sha224Update(&sha224, data, len);
wc_Sha224Final(&sha224, hash);
}
See Also:
wc_InitSha224, wc_Sha224Final, wc_Sha224Hash
wc_Sha224Final
Synopsis:
#include <wolfssl/wolfcrypt/port/ti/ti-hash.h>
int wc_Sha224Final(Sha224* sha224, byte* hash)
Description:
Finalizes hashing of data. Result is placed into hash. Resets state of sha224 struct.
Return Values:
0: Success
< 0: Error
Parameters:
sha224 - pointer to the sha224 structure to use for encryption
hash - Byte array to hold hash value.
Example:
Sha224 sha224;
byte data[] = { /* Data to be hashed */ };
word32 len = sizeof(data);
if ((ret = wc_InitSha224(&sha224)) != 0) {
WOLFSSL_MSG("wc_InitSha224 failed");
}
else {
wc_Sha256Update(&sha224, data, len);
wc_Sha256Final(&sha224, hash);
}
See Also:
wc_InitSha224, wc_Sha224Hash, wc_Sha224Update
18.41 Keys
wolfSSL_PubKeyPemToDer
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wolfSSL_PubKeyPemToDer(const unsigned char* pem, int pemSz,
unsigned char* buff, int buffSz)
Description:
Convert a PEM encoded public key to DER. Returns the number of bytes written to the buffer or a negative value for an error.
Return Values:
>0: Success, number of bytes written.
BAD_FUNC_ARG: Returns if pem, buff, or buffSz are null
< 0: An error occurred in the function.
Parameters:
pem - PEM encoded key
pemSz - Size of pem
buff - Pointer to buffer for output.
buffSz - Size of buffer.
Example:
byte some_pem[] = { /* Initialize with PEM key */ }
unsigned char out_buffer[1024]; /* Ensure buffer is large enough to fit DER */
if(wolfSSL_PubKeyPemToDer(some_pem, sizeof(some_pem), out_buffer,
sizeof(out_buffer)) < 0)
{
/* Handle error */
}
See Also:
wolfSSL_PemPubKeyToDer
wolfSSL_PemPubKeyToDer
Synopsis:
#include <wolfssl/wolfcrypt/asn_public.h>
int wolfSSL_PemPubKeyToDer(const char* fileName,
unsigned char* derBuf, int derSz)
Description:
Loads a PEM key from a file and converts to a DER encoded buffer.
Return Values:
0: Success
< 0: Error
SSL_BAD_FILE: There is a problem with opening the file.
MEMORY_E: There is an error allocating memory for the file buffer.
BUFFER_E: derBuf is not large enough to hold the converted key.
Parameters:
fileName - Name of the file to load.
derBuf - Buffer for DER encoded key.
derSz - Size of DER buffer.
Example:
char* some_file = "filename";
unsigned char der[];
if(wolfSSL_PemPubKeyToDer(some_file, der, sizeof(der)) != 0)
{
/* Handle Error */
}
See Also:
wolfSSL_PubKeyPemToDer
Copyright 2015 wolfSSL Inc. All rights reserved.