ica_aes_cbc_cs

Purpose

Encrypt or decrypt data with an AES key using Cipher Block Chaining with Ciphertext Stealing (CBC-CS) mode, as described in NIST Special Publication 800-38A Chapter 6.2, and the Addendum to NIST Special Publication 800-38A on Recommendation for Block Cipher Modes of Operation: Three Variants of Ciphertext Stealing for CBC Mode.

ica_aes_cbc_cs can be used to encrypt or decrypt the last chunk of a message consisting of multiple chunks, where all chunks except the last one are encrypted or decrypted by chained calls to ica_aes_cbc. To do this, the resulting iv of the last call to ica_aes_cbc is fed into the iv of the ica_aes_cbc_cs call, provided that the chunk is greater than the cipher block size (greater than 16 bytes for AES).

Required hardware support

KMC-AES-128, KMC-AES-192 or KMC-AES-256

Parameters

const unsigned char *in_data

Pointer to a readable buffer that contains the message to be encrypted or decrypted. The size of the message in bytes is data_length. The size of this buffer must be at least as large as data_length.

unsigned char *out_data

Pointer to a writable buffer to contain the resulting encrypted or decrypted message. The size of this buffer in bytes must be at least as large as data_length.

unsigned long data_length

Length in bytes of the message to be encrypted or decrypted, which resides at the beginning of in_data. data_length must be greater than or equal to the cipher block size (16 bytes for AES).

const unsigned char *key

Pointer to a valid AES key.

unsigned int key_length

Length in bytes of the AES key. Supported sizes are 16, 24, and 32, for AES-128, AES-192, and AES-256 respectively. . Therefore, you can use the definitions: AES_KEY_LEN128, AES_KEY_LEN192, and AES_KEY_LEN256.

unsigned char *iv

Pointer to a valid initialization vector of cipher block size number of bytes. This vector is overwritten during the function. For variant equal to 1 or variant equal to 2, the result value in iv can be used as the initialization vector for a chained ica_aes_cbc or ica_aes_cbc_cs call with the same key, if data_length is a multiple of the cipher block size.

unsigned int direction

0

Use the decrypt function.

1

Use the encrypt function.

unsigned int variant

1

Use variant CBC-CS1 of the Addendum to NIST Special Publication 800-38A to encrypt or decrypt the message: always keep last two blocks in order.

2

Use variant CBC-CS2 of the Addendum to NIST Special Publication 800-38A to encrypt or decrypt the message: switch order of the last two blocks if data_length is not a multiple of the cipher block size (a multiple of 16 bytes for AES).

3

Use variant CBC-CS3 of the Addendum to NIST Special Publication 800-38A to encrypt or decrypt the message: always switch order of the last two blocks.

Return codes

0

Success

For return codes indicating exceptions, see Return codes.