Functions
Algorithms - AES

Functions

WOLFSSL_API int wc_AesSetKey (Aes *aes, const byte *key, word32 len, const byte *iv, int dir)
 This function initializes an AES structure by setting the key and then setting the initialization vector. More...
 
WOLFSSL_API int wc_AesSetIV (Aes *aes, const byte *iv)
 This function sets the initialization vector for a particular AES object. The AES object should be initialized before calling this function. More...
 
WOLFSSL_API int wc_AesCbcEncrypt (Aes *aes, byte *out, const byte *in, word32 sz)
 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. More...
 
WOLFSSL_API int wc_AesCbcDecrypt (Aes *aes, byte *out, const byte *in, word32 sz)
 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. More...
 
WOLFSSL_API int wc_AesCtrEncrypt (Aes *aes, byte *out, const byte *in, word32 sz)
 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. NOTE: Regarding using same API for encryption and decryption. User should differentiate between Aes structures for encrypt/decrypt. More...
 
WOLFSSL_API void wc_AesEncryptDirect (Aes *aes, byte *out, const byte *in)
 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. Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible. More...
 
WOLFSSL_API void wc_AesDecryptDirect (Aes *aes, byte *out, const byte *in)
 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. Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible. More...
 
WOLFSSL_API int wc_AesSetKeyDirect (Aes *aes, const byte *key, word32 len, const byte *iv, int dir)
 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. Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible. More...
 
WOLFSSL_API int wc_AesGcmSetKey (Aes *aes, const byte *key, word32 len)
 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. More...
 
WOLFSSL_API 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)
 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. More...
 
WOLFSSL_API 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)
 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. More...
 
WOLFSSL_API int wc_GmacSetKey (Gmac *gmac, const byte *key, word32 len)
 This function initializes and sets the key for a GMAC object to be used for Galois Message Authentication. More...
 
WOLFSSL_API int wc_GmacUpdate (Gmac *gmac, const byte *iv, word32 ivSz, const byte *authIn, word32 authInSz, byte *authTag, word32 authTagSz)
 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. More...
 
WOLFSSL_API int wc_AesCcmSetKey (Aes *aes, const byte *key, word32 keySz)
 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. More...
 
WOLFSSL_API int wc_AesCcmEncrypt (Aes *aes, byte *out, const byte *in, word32 inSz, const byte *nonce, word32 nonceSz, byte *authTag, word32 authTagSz, const byte *authIn, word32 authInSz)
 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. More...
 
WOLFSSL_API 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)
 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. More...
 
WOLFSSL_API int wc_AesXtsSetKey (XtsAes *aes, const byte *key, word32 len, int dir, void *heap, int devId)
 This is to help with setting keys to correct encrypt or decrypt type. It is up to user to call wc_AesXtsFree on aes key when done. More...
 
WOLFSSL_API int wc_AesXtsEncryptSector (XtsAes *aes, byte *out, const byte *in, word32 sz, word64 sector)
 Same process as wc_AesXtsEncrypt but uses a word64 type as the tweak value instead of a byte array. This just converts the word64 to a byte array and calls wc_AesXtsEncrypt. More...
 
WOLFSSL_API int wc_AesXtsDecryptSector (XtsAes *aes, byte *out, const byte *in, word32 sz, word64 sector)
 Same process as wc_AesXtsDecrypt but uses a word64 type as the tweak value instead of a byte array. This just converts the word64 to a byte array. More...
 
WOLFSSL_API int wc_AesXtsEncrypt (XtsAes *aes, byte *out, const byte *in, word32 sz, const byte *i, word32 iSz)
 AES with XTS mode. (XTS) XEX encryption with Tweak and cipher text Stealing. More...
 
WOLFSSL_API int wc_AesXtsDecrypt (XtsAes *aes, byte *out, const byte *in, word32 sz, const byte *i, word32 iSz)
 Same process as encryption but Aes key is AES_DECRYPTION type. More...
 
WOLFSSL_API int wc_AesXtsFree (XtsAes *aes)
 This is to free up any resources used by the XtsAes structure. More...
 
WOLFSSL_API int wc_AesInit (Aes *, void *, int)
 Initialize Aes structure. Sets heap hint to be used and ID for use with async hardware. More...
 
WOLFSSL_API int wc_AesCbcDecryptWithKey (byte *out, const byte *in, word32 inSz, const byte *key, word32 keySz, const byte *iv)
 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. More...
 

Detailed Description

Function Documentation

◆ wc_AesCbcDecrypt()

int wc_AesCbcDecrypt ( Aes aes,
byte *  out,
const byte *  in,
word32  sz 
)

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.

Returns
0 On successfully decrypting message.
BAD_ALIGN_E Returned on block align error.
Parameters
aespointer to the AES object used to decrypt data.
outpointer to the output buffer in which to store the plain text of the decrypted message.
inpointer to the input buffer containing cipher text to be decrypted.
szsize 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()

WOLFSSL_API int wc_AesCbcDecryptWithKey ( byte *  out,
const byte *  in,
word32  inSz,
const byte *  key,
word32  keySz,
const byte *  iv 
)

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.

Returns
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
outpointer to the output buffer in which to store the plain text of the decrypted message
inpointer to the input buffer containing cipher text to be decrypted
inSzsize of input message
key16, 24, or 32 byte secret key for decryption
keySzsize 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_AesCbcEncrypt()

int wc_AesCbcEncrypt ( Aes aes,
byte *  out,
const byte *  in,
word32  sz 
)

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.

Returns
0 On successfully encrypting message.
BAD_ALIGN_E: Returned on block align error
Parameters
aespointer to the AES object used to encrypt data
outpointer to the output buffer in which to store the ciphertext of the encrypted message
inpointer to the input buffer containing message to be encrypted
szsize 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_AesCcmDecrypt()

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 
)

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.

Returns
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
aespointer to the AES object used to encrypt data
outpointer to the output buffer in which to store the cipher text
inpointer to the input buffer holding the message to encrypt
szlength of the input cipher text to decrypt
noncepointer to the buffer containing the nonce (number only used once)
nonceSzlength of the nonce
authTagpointer to the buffer in which to store the authentication tag
authTagSzlength of the desired authentication tag
authInpointer to the buffer containing the input authentication vector
authInSzlength 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_AesCcmEncrypt()

int wc_AesCcmEncrypt ( Aes aes,
byte *  out,
const byte *  in,
word32  inSz,
const byte *  nonce,
word32  nonceSz,
byte *  authTag,
word32  authTagSz,
const byte *  authIn,
word32  authInSz 
)

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.

Returns
none
Parameters
aespointer to the AES object used to encrypt data
outpointer to the output buffer in which to store the cipher text
inpointer to the input buffer holding the message to encrypt
szlength of the input message to encrypt
noncepointer to the buffer containing the nonce (number only used once)
nonceSzlength of the nonce
authTagpointer to the buffer in which to store the authentication tag
authTagSzlength of the desired authentication tag
authInpointer to the buffer containing the input authentication vector
authInSzlength 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_AesCcmSetKey()

int wc_AesCcmSetKey ( Aes aes,
const byte *  key,
word32  keySz 
)

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.

Returns
none
Parameters
aesaes structure in which to store the supplied key
key16, 24, or 32 byte secret key for encryption and decryption
keySzsize 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_AesCtrEncrypt()

int wc_AesCtrEncrypt ( Aes aes,
byte *  out,
const byte *  in,
word32  sz 
)

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. NOTE: Regarding using same API for encryption and decryption. User should differentiate between Aes structures for encrypt/decrypt.

Returns
int integer values corresponding to wolfSSL error or success status
Parameters
aespointer to the AES object used to decrypt data
outpointer to the output buffer in which to store the cipher text of the encrypted message
inpointer to the input buffer containing plain text to be encrypted
szsize of the input plain text

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_AesDecryptDirect()

void wc_AesDecryptDirect ( Aes aes,
byte *  out,
const byte *  in 
)

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. Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible.

Returns
none
Parameters
aespointer to the AES object used to encrypt data
outpointer to the output buffer in which to store the plain text of the decrypted cipher text
inpointer 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_AesEncryptDirect()

void wc_AesEncryptDirect ( Aes aes,
byte *  out,
const byte *  in 
)

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. Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible.

Parameters
aespointer to the AES object used to encrypt data
outpointer to the output buffer in which to store the cipher text of the encrypted message
inpointer 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_AesGcmDecrypt()

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 
)

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.

Returns
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
aespointer to the AES object used to encrypt data
outpointer to the output buffer in which to store the message text
inpointer to the input buffer holding the cipher text to decrypt
szlength of the cipher text to decrypt
ivpointer to the buffer containing the initialization vector
ivSzlength of the initialization vector
authTagpointer to the buffer containing the authentication tag
authTagSzlength of the desired authentication tag
authInpointer to the buffer containing the input authentication vector
authInSzlength 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_AesGcmEncrypt()

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 
)

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.

Returns
0 On successfully encrypting the input message
Parameters
aes- pointer to the AES object used to encrypt data
outpointer to the output buffer in which to store the cipher text
inpointer to the input buffer holding the message to encrypt
szlength of the input message to encrypt
ivpointer to the buffer containing the initialization vector
ivSzlength of the initialization vector
authTagpointer to the buffer in which to store the authentication tag
authTagSzlength of the desired authentication tag
authInpointer to the buffer containing the input authentication vector
authInSzlength 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_AesGcmSetKey()

int wc_AesGcmSetKey ( Aes aes,
const byte *  key,
word32  len 
)

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.

Returns
0 On successfully setting the key.
BAD_FUNC_ARG Returned if the given key is an invalid length.
Parameters
aespointer to the AES object used to encrypt data
key16, 24, or 32 byte secret key for encryption and decryption
lenlength 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_AesInit()

int wc_AesInit ( Aes aes,
void *  heap,
int  devId 
)

Initialize Aes structure. Sets heap hint to be used and ID for use with async hardware.

Returns
0 Success
Parameters
aesaes structure in to initialize
heapheap hint to use for malloc / free if needed
devIdID to use with async hardware

Example

Aes enc;
void* hint = NULL;
int devId = INVALID_DEVID; //if not using async INVALID_DEVID is default
//heap hint could be set here if used
wc_AesInit(&aes, hint, devId);
See also
wc_AesSetKey
wc_AesSetIV

◆ wc_AesSetIV()

int wc_AesSetIV ( Aes aes,
const byte *  iv 
)

This function sets the initialization vector for a particular AES object. The AES object should be initialized before calling this function.

Returns
0 On successfully setting initialization vector.
BAD_FUNC_ARG Returned if AES pointer is NULL.
Parameters
aespointer to the AES structure on which to set the initialization vector
ivinitialization 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_AesSetKey()

int wc_AesSetKey ( Aes aes,
const byte *  key,
word32  len,
const byte *  iv,
int  dir 
)

This function initializes an AES structure by setting the key and then setting the initialization vector.

Returns
0 On successfully setting key and initialization vector.
BAD_FUNC_ARG Returned if key length is invalid.
Parameters
aespointer to the AES structure to modify
key16, 24, or 32 byte secret key for encryption and decryption
lenlength of the key passed in
ivpointer to the initialization vector used to initialize the key
dirCipher direction. Set AES_ENCRYPTION to encrypt, or AES_DECRYPTION to decrypt.

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_AesSetKeyDirect()

int wc_AesSetKeyDirect ( Aes aes,
const byte *  key,
word32  len,
const byte *  iv,
int  dir 
)

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. Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible.

Returns
0 On successfully setting the key.
BAD_FUNC_ARG Returned if the given key is an invalid length.
Parameters
aespointer to the AES object used to encrypt data
key16, 24, or 32 byte secret key for encryption and decryption
lenlength of the key passed in
ivinitialization vector used to initialize the key
dirCipher 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_AesXtsDecrypt()

WOLFSSL_API int wc_AesXtsDecrypt ( XtsAes aes,
byte *  out,
const byte *  in,
word32  sz,
const byte *  i,
word32  iSz 
)

Same process as encryption but Aes key is AES_DECRYPTION type.

Returns
0 Success
Parameters
aesAES keys to use for block encrypt/decrypt
outoutput buffer to hold plain text
ininput cipher text buffer to decrypt
szsize of both out and in buffers
ivalue to use for tweak
iSzsize of i buffer, should always be AES_BLOCK_SIZE but having this input adds a sanity check on how the user calls the function.

Example

XtsAes aes;
unsigned char plain[SIZE];
unsigned char cipher[SIZE];
unsigned char i[AES_BLOCK_SIZE];
//set up key with AES_DECRYPTION as dir and tweak with AES_ENCRYPTION
if(wc_AesXtsDecrypt(&aes, plain, cipher, SIZE, i, sizeof(i)) != 0)
{
// Handle error
}
See also
wc_AesXtsEncrypt
wc_AesXtsSetKey
wc_AesXtsFree

◆ wc_AesXtsDecryptSector()

WOLFSSL_API int wc_AesXtsDecryptSector ( XtsAes aes,
byte *  out,
const byte *  in,
word32  sz,
word64  sector 
)

Same process as wc_AesXtsDecrypt but uses a word64 type as the tweak value instead of a byte array. This just converts the word64 to a byte array.

Returns
0 Success
Parameters
aesAES keys to use for block encrypt/decrypt
outoutput buffer to hold plain text
ininput cipher text buffer to decrypt
szsize of both out and in buffers
sectorvalue to use for tweak

Example

XtsAes aes;
unsigned char plain[SIZE];
unsigned char cipher[SIZE];
word64 s = VALUE;
//set up aes key with AES_DECRYPTION as dir and tweak with AES_ENCRYPTION
if(wc_AesXtsDecryptSector(&aes, plain, cipher, SIZE, s) != 0)
{
// Handle error
}
See also
wc_AesXtsEncrypt
wc_AesXtsDecrypt
wc_AesXtsSetKey
wc_AesXtsFree

◆ wc_AesXtsEncrypt()

WOLFSSL_API int wc_AesXtsEncrypt ( XtsAes aes,
byte *  out,
const byte *  in,
word32  sz,
const byte *  i,
word32  iSz 
)

AES with XTS mode. (XTS) XEX encryption with Tweak and cipher text Stealing.

Returns
0 Success
Parameters
aesAES keys to use for block encrypt/decrypt
outoutput buffer to hold cipher text
ininput plain text buffer to encrypt
szsize of both out and in buffers
ivalue to use for tweak
iSzsize of i buffer, should always be AES_BLOCK_SIZE but having this input adds a sanity check on how the user calls the function.

Example

XtsAes aes;
unsigned char plain[SIZE];
unsigned char cipher[SIZE];
unsigned char i[AES_BLOCK_SIZE];
//set up key with AES_ENCRYPTION as dir
if(wc_AesXtsEncrypt(&aes, cipher, plain, SIZE, i, sizeof(i)) != 0)
{
// Handle error
}
See also
wc_AesXtsDecrypt
wc_AesXtsSetKey
wc_AesXtsFree

◆ wc_AesXtsEncryptSector()

WOLFSSL_API int wc_AesXtsEncryptSector ( XtsAes aes,
byte *  out,
const byte *  in,
word32  sz,
word64  sector 
)

Same process as wc_AesXtsEncrypt but uses a word64 type as the tweak value instead of a byte array. This just converts the word64 to a byte array and calls wc_AesXtsEncrypt.

Returns
0 Success
Parameters
aesAES keys to use for block encrypt/decrypt
outoutput buffer to hold cipher text
ininput plain text buffer to encrypt
szsize of both out and in buffers
sectorvalue to use for tweak

Example

XtsAes aes;
unsigned char plain[SIZE];
unsigned char cipher[SIZE];
word64 s = VALUE;
//set up keys with AES_ENCRYPTION as dir
if(wc_AesXtsEncryptSector(&aes, cipher, plain, SIZE, s) != 0)
{
// Handle error
}
See also
wc_AesXtsEncrypt
wc_AesXtsDecrypt
wc_AesXtsSetKey
wc_AesXtsFree

◆ wc_AesXtsFree()

WOLFSSL_API int wc_AesXtsFree ( XtsAes aes)

This is to free up any resources used by the XtsAes structure.

Returns
0 Success
Parameters
aesAES keys to free

Example

XtsAes aes;
if(wc_AesXtsSetKey(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, 0) != 0)
{
// Handle error
}
See also
wc_AesXtsEncrypt
wc_AesXtsDecrypt
wc_AesXtsSetKey

◆ wc_AesXtsSetKey()

WOLFSSL_API int wc_AesXtsSetKey ( XtsAes aes,
const byte *  key,
word32  len,
int  dir,
void *  heap,
int  devId 
)

This is to help with setting keys to correct encrypt or decrypt type. It is up to user to call wc_AesXtsFree on aes key when done.

Returns
0 Success
Parameters
aesAES keys for encrypt/decrypt process
keybuffer holding aes key | tweak key
lenlength of key buffer in bytes. Should be twice that of key size. i.e. 32 for a 16 byte key.
dirdirection, either AES_ENCRYPTION or AES_DECRYPTION
heapheap hint to use for memory. Can be NULL
devIdid to use with async crypto. Can be 0

Example

XtsAes aes;
if(wc_AesXtsSetKey(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, 0) != 0)
{
// Handle error
}
See also
wc_AesXtsEncrypt
wc_AesXtsDecrypt
wc_AesXtsFree

◆ wc_GmacSetKey()

WOLFSSL_API int wc_GmacSetKey ( Gmac gmac,
const byte *  key,
word32  len 
)

This function initializes and sets the key for a GMAC object to be used for Galois Message Authentication.

Returns
0 On successfully setting the key
BAD_FUNC_ARG Returned if key length is invalid.
Parameters
gmacpointer to the gmac object used for authentication
key16, 24, or 32 byte secret key for authentication
lenlength 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()

WOLFSSL_API int wc_GmacUpdate ( Gmac gmac,
const byte *  iv,
word32  ivSz,
const byte *  authIn,
word32  authInSz,
byte *  authTag,
word32  authTagSz 
)

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.

Returns
0 On successfully computing the Gmac hash.
Parameters
gmacpointer to the gmac object used for authentication
ivinitialization vector used for the hash
ivSzsize of the initialization vector used
authInpointer to the buffer containing the authentication vector to verify
authInSzsize of the authentication vector
authTagpointer to the output buffer in which to store the Gmac hash
authTagSzthe 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