Chapter 2. Programming Guidelines

Table of Contents

Convenience Functions
Synchronous Symmetric Cipher API
Asynchronous Symmetric Cipher API
AEAD Cipher API
Aynchronous AEAD Cipher API
AEAD Memory Structure
Message Digest API
Asymmetric Cipher API
Zero Copy
Memory Allocation
Asynchronous I/O Use Cases and Libkcapi
Multiple Staged Cipher Operations
Multiple Separate Cipher Operations
Kernel Interfaces
Kernel Configuration
Example Code

A consumer has to use the kcapi.h header file to link with libkcapi. The linking has to be performed using -lkcapi.

In case a consumer does not want a shared library, the libkcapi C file and header file can also just copied to the consumer code and compiled along with it.

A general requirement must be observed: setting of keys must be performed before any operation. Re-setting of keys is only permissible once all data in flight (sent to the kernel but the kernel's result is not yet obtained) is processed, i.e. no data is in flight any more.

Convenience Functions

To support various use cases, the API provided with libkcapi is extensive. Though, some developers want to simply use a given cipher without any specific details. To accommodate such users, libkcapi provides convenience functions or convenience wrappers.

The convenience functions provide exactly one function call to perform one complete cipher operation, such as an AES CBC encryption operation or a SHA-256 hashing. The caller only needs to provide the input and output buffers of his data. The entire intrinsic operation of libkcapi is hidden from the user.

Convenience functions are provided for the different cipher types. They are clearly marked in the API specification below.