AES functions
These functions perform encryption and decryption or computation or verification of message authentication codes using an AES key. Supported key lengths are 16, 24 or 32 bytes for AES-128, AES-192 and AES-256 respectively. The cipher block size for AES is 16 bytes.
These functions are declared in: include/ica_api.h.
To securely apply AES encryption to messages that are longer than the cipher block size, modes of operation can be used to chain multiple encryption, decryption, or authentication operations. Most modes of operation require an initialization vector as additional input.
As long as the messages are encrypted or decrypted using such a mode of operation, have a size that is a multiple of a particular block size (mostly the cipher block size), the functions encrypting or decryption according to a mode of operation also compute an output vector. The output vector can be used as the initialization vector of a chained encryption or decryption operation in the same mode with the same block size and the same key.
When decrypting a cipher text, the mode of operation, the key, the initialization vector (if applicable), and for ica_aes_cfb, the lcfb value used for the decryption function must match the corresponding settings of the encryption function that transformed the plain text into cipher text.
AES API functions exploiting the KMA instruction
libica offers an enhanced API for the AES cipher in GCM block cipher mode. It consists of six API functions that exploit the cipher message with authentication (KMA) instruction. This KMA instruction is part of the message-security-assist extension 8 (MSA 8) and runs on the CPACF starting with z14 processors.
GCM API functions provided by libica earlier than version 3.2 also use the new KMA instruction on z14 processors. However, the enhanced GCM APIs offer advantages concerning usability and performance. Therefore, consider to use these APIs instead of the existing ones in all of your applicable applications.
You find the descriptions of the enhanced GCM APIs in the following topics: