Asynchronous Symmetric Cipher API
Prev | Chapter 2. Programming Guidelines | Next

## Asynchronous Symmetric Cipher API

In addition to the symmetric cipher API, an asynchronous API is offered with the kcapi_cipher_*_aio and kcapi_aead_*_aio API calls. The concept of that API is to perform parallel operations of multiple encryption or decryption data streams.

To use the AIO API, the caller must use the KCAPI_INIT_AIO with the kcapi_cipher_init function call to set up all additional logistics for handing AIO. That means, users which are not interested in AIO will not suffer from the additional memory overhead including the time required to allocate that memory required for AIO.

This implies that the asynchronous API handles the scatter-gather lists referenced by the IOVECs differently compared to the synchronous APIs. Whereas the synchronous API references different parts of plaintext or ciphertext that are processed with one cipher operation, the IOVECs of the asynchronous API references plaintext or ciphertext where each IOVEC is processed with an independent cipher operation. I.e. when using AES-CBC with the synchronous API and the scatter-gather lists, all input data is sent to one invocation of the AES-CBC cipher. Conversely, the asynchronous API invokes one individual AES-CBC operation for each individual IOVEC.

The asynchronous API is designed to perform an in-place operation where the buffers for the input data are used to store the output data.

The asynchronous API in libkcapi as well as the kernel has a higher overhead for setting the cipher operation up. That means that if the caller only uses a one IOVEC with one associated cipher operation, the asynchronous API is expected to be slower compared to the synchronous API. But already with two or three combined cipher operations, the AIO API should be faster than the synchronous API. You may test the difference in performance with the test/kcapi test application by using the options -f for measuring the time of cipher operations in nanoseconds, -d for the number of parallel invocations and -x 1 for a symmetric one-shot cipher invocation and -x 9 for an asymmetric cipher operation with the given input data.

The kernel offers the AIO interface since kernel version 4.1 (symmetric ciphers) and 4.7 (AEAD ciphers). The libkcapi implements a transparent fallback to use the synchronous cipher API in case the AIO support is not present for the current kernel. This allows the calling users to be agnostic of the kernel support. Nonetheless, libkcapi with report the lack of AIO support if AIO is requested as the fallback implementation has a slight performance overhead.

Prev | Up | Next
Synchronous Symmetric Cipher API | Home | AEAD Cipher API