wc_encrypt.h

Functions

	Name
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.
int	wc_Des_CbcDecryptWithKey(byte * out, const byte * in, word32 sz, const byte * key, const byte * iv) 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.
int	wc_Des_CbcEncryptWithKey(byte * out, const byte * in, word32 sz, const byte * key, const byte * iv) 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.
int	wc_Des3_CbcEncryptWithKey(byte * out, const byte * in, word32 sz, const byte * key, const byte * iv) 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.
int	wc_Des3_CbcDecryptWithKey(byte * out, const byte * in, word32 sz, const byte * key, const byte * iv) 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.
int	wc_AesCbcEncryptWithKey(byte * out, const byte * in, word32 inSz, const byte * key, word32 keySz, const byte * iv) This function encrypts a plaintext message and stores the result in the output buffer. It uses AES encryption with cipher block chaining (CBC) mode. This function does not require an AES structure to be initialized. Instead, it takes in a key and an iv and uses these to encrypt the message.
int	wc_BufferKeyDecrypt(struct EncryptedInfo * info, byte * der, word32 derSz, const byte * password, int passwordSz, int hashType) This function decrypts an encrypted key buffer using the provided password. It supports various encryption algorithms including DES, 3DES, and AES. The encryption information is provided in the EncryptedInfo structure.
int	wc_BufferKeyEncrypt(struct EncryptedInfo * info, byte * der, word32 derSz, const byte * password, int passwordSz, int hashType) This function encrypts a key buffer using the provided password. It supports various encryption algorithms including DES, 3DES, and AES. The encryption information is provided in the EncryptedInfo structure.

Functions Documentation

function wc_AesCbcDecryptWithKey

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.

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

See:

• wc_AesSetKey
• wc_AesSetIV
• wc_AesCbcEncrypt
• wc_AesCbcDecrypt

Return:

• 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.

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
}

function wc_Des_CbcDecryptWithKey

int wc_Des_CbcDecryptWithKey(
    byte * out,
    const byte * in,
    word32 sz,
    const byte * key,
    const byte * iv
)

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.

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

See: wc_Des_CbcDecrypt

Return:

• 0 Returned upon successfully decrypting the given ciphertext
• MEMORY_E Returned if there is an error allocating space for a Des structure

3

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
}

function wc_Des_CbcEncryptWithKey

int wc_Des_CbcEncryptWithKey(
    byte * out,
    const byte * in,
    word32 sz,
    const byte * key,
    const byte * iv
)

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.

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

See:

• wc_Des_CbcDecryptWithKey
• wc_Des_CbcEncrypt

Return:

• 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.

3

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
}

function wc_Des3_CbcEncryptWithKey

int wc_Des3_CbcEncryptWithKey(
    byte * out,
    const byte * in,
    word32 sz,
    const byte * key,
    const byte * iv
)

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.

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

See:

• wc_Des3_CbcDecryptWithKey
• wc_Des_CbcEncryptWithKey
• wc_Des_CbcDecryptWithKey

Return:

• 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.

3

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
}

function wc_Des3_CbcDecryptWithKey

int wc_Des3_CbcDecryptWithKey(
    byte * out,
    const byte * in,
    word32 sz,
    const byte * key,
    const byte * iv
)

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.

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

See: wc_Des3_CbcDecrypt

Return:

• 0 Returned upon successfully decrypting the given ciphertext
• MEMORY_E Returned if there is an error allocating space for a Des structure

3

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
}

function wc_AesCbcEncryptWithKey

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

This function encrypts a plaintext message and stores the result in the output buffer. It uses AES encryption with cipher block chaining (CBC) mode. This function does not require an AES structure to be initialized. Instead, it takes in a key and an iv and uses these to encrypt the message.

Parameters:

• out pointer to the output buffer in which to store the ciphertext of the encrypted message
• in pointer to the input buffer containing plaintext to encrypt
• inSz size of input message
• key 16, 24, or 32 byte secret key for encryption
• keySz size of key used for encryption
• iv pointer to the 16 byte initialization vector to use

See:

• wc_AesCbcDecryptWithKey
• wc_AesSetKey
• wc_AesCbcEncrypt

Return:

• 0 On successfully encrypting the message
• BAD_ALIGN_E Returned on block align error
• BAD_FUNC_ARG Returned if key length is invalid
• MEMORY_E Returned if WOLFSSL_SMALL_STACK is enabled and XMALLOC fails to instantiate an AES object

Example

byte key[]; // 16, 24, or 32 byte key
byte iv[]; // 16 byte iv
byte plain[]; // plaintext to encrypt
byte cipher[sizeof(plain)];

int ret = wc_AesCbcEncryptWithKey(cipher, plain, sizeof(plain),
                                  key, sizeof(key), iv);
if (ret != 0) {
    // encryption error
}

function wc_BufferKeyDecrypt

int wc_BufferKeyDecrypt(
    struct EncryptedInfo * info,
    byte * der,
    word32 derSz,
    const byte * password,
    int passwordSz,
    int hashType
)

This function decrypts an encrypted key buffer using the provided password. It supports various encryption algorithms including DES, 3DES, and AES. The encryption information is provided in the EncryptedInfo structure.

Parameters:

• info pointer to EncryptedInfo structure containing encryption algorithm and parameters
• der pointer to the encrypted key buffer
• derSz size of the encrypted key buffer
• password pointer to the password buffer
• passwordSz size of the password
• hashType hash algorithm to use for key derivation

See: wc_BufferKeyEncrypt

Return:

• Length of decrypted key on success
• Negative value on error

Example

EncryptedInfo info;
byte encryptedKey[]; // encrypted key data
byte password[] = "mypassword";

int ret = wc_BufferKeyDecrypt(&info, encryptedKey,
                              sizeof(encryptedKey), password,
                              sizeof(password)-1, WC_SHA256);
if (ret < 0) {
    // decryption error
}

function wc_BufferKeyEncrypt

int wc_BufferKeyEncrypt(
    struct EncryptedInfo * info,
    byte * der,
    word32 derSz,
    const byte * password,
    int passwordSz,
    int hashType
)

This function encrypts a key buffer using the provided password. It supports various encryption algorithms including DES, 3DES, and AES. The encryption information is provided in the EncryptedInfo structure.

Parameters:

• info pointer to EncryptedInfo structure containing encryption algorithm and parameters
• der pointer to the key buffer to encrypt
• derSz size of the key buffer
• password pointer to the password buffer
• passwordSz size of the password
• hashType hash algorithm to use for key derivation

See: wc_BufferKeyDecrypt

Return:

• Length of encrypted key on success
• Negative value on error

Example

EncryptedInfo info;
byte key[]; // key data to encrypt
byte password[] = "mypassword";

info.algo = AES256CBCb;
int ret = wc_BufferKeyEncrypt(&info, key, sizeof(key), password,
                              sizeof(password)-1, WC_SHA256);
if (ret < 0) {
    // encryption error
}

Source code

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

int  wc_Des_CbcDecryptWithKey(byte* out,
                                          const byte* in, word32 sz,
                                          const byte* key, const byte* iv);

int  wc_Des_CbcEncryptWithKey(byte* out,
                                          const byte* in, word32 sz,
                                          const byte* key, const byte* iv);

int  wc_Des3_CbcEncryptWithKey(byte* out,
                                           const byte* in, word32 sz,
                                           const byte* key, const byte* iv);

int  wc_Des3_CbcDecryptWithKey(byte* out,
                                           const byte* in, word32 sz,
                                           const byte* key, const byte* iv);

int wc_AesCbcEncryptWithKey(byte* out, const byte* in, word32 inSz,
                            const byte* key, word32 keySz,
                            const byte* iv);

int wc_BufferKeyDecrypt(struct EncryptedInfo* info, byte* der,
                        word32 derSz, const byte* password,
                        int passwordSz, int hashType);

int wc_BufferKeyEncrypt(struct EncryptedInfo* info, byte* der,
                        word32 derSz, const byte* password,
                        int passwordSz, int hashType);

---

Updated on 2025-12-31 at 01:16:04 +0000