ica_aes_xts_ex

Purpose

Encrypt or decrypt data with an AES key using the XEX Tweakable Block Cipher with Ciphertext Stealing (XTS) mode, as described in NIST Special Publication 800-38E and IEEE standard 1619-2007. In contrast to ica_aes_xts(), the ica_aes_xts() API allows to encrypt multiple data parts of an input message by repeatedly calling the function for intermediate data parts and the final data part.

Format


unsigned int ica_aes_xts_ex(const unsigned char *in_data,
  unsigned char *out_data,
  unsigned long data_length,
  const unsigned char *key1,
  const unsigned char *key2,
  unsigned int key_length,
  unsigned char *tweak,
  unsigned char *iv,
  unsigned int direction);

Required hardware support

KM-XTS-AES-128, or KM-XTS-AES-256
PCC-Compute-XTS-Parameter-Using-AES-128, or PCC-Compute-XTS-Parameter-Using-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 part to be encrypted or decrypted, which resides at the beginning of in_data. For multi-part operations, data_length for the first and intermediate message parts must be a multiple of the AES cipher block size of 16 bytes, (16, 32, 48, … and so on). Any message part, whose data_length is longer than 16 bytes, but not a multiple of 16, is recognized as the final message part. Further calls of this function after a final message part has been processed, leads to unexpected results. If the data_length of the last message part is a multiple of 16 bytes, no special final block handling is required.

const unsigned char *key1

Pointer to a buffer containing a valid AES key. key1 is used for the actual encryption of the message buffer, combined with some vector computed from the tweak value (Key1 in IEEE Std 1619-2007).

const unsigned char *key2

Pointer to a buffer containing a valid AES key. key2 is used to encrypt the tweak (Key2 in IEEE Std 1619-2007).

unsigned int key_length

The length in bytes of the AES key. XTS-supported AES key sizes are 16 and 32, for AES-128 and AES-256 respectively.

unsigned char *tweak

Pointer to a valid 16-byte tweak value (as in IEEE standard 1619-2007). For multi-part operations the tweak must only be specified for the initial part. For subsequent parts, the tweak parameter must be NULL.

unsigned char *iv

Pointer to the initialization vector to be used for multi-part operations. If the tweak parameter is NULL, then the operation uses the initialization vector specified with this parameter. On return, the initialization vector is updated with the output vector that can be used as initialization vector for the next part. For single part operations, this parameter can be NULL.

unsigned int direction

Can be 0 or 1:

0: Use the decrypt function.
1: Use the encrypt function.

Return codes

0: Success
EINVAL: If at least one invalid parameter is given.
EIO: If the operation fails.
EPERM: If required hardware support is not available.

For return codes indicating exceptions, see Return codes.