Introduction¶

The kernel crypto API offers a rich set of cryptographic ciphers as wellas other data transformation mechanisms and methods to invoke these.This document contains a description of the API and provides examplecode.

To understand and properly use the kernel crypto API a brief explanationof its structure is given. Based on the architecture, the API can beseparated into different components. Following the architecturespecification, hints to developers of ciphers are provided. Pointers tothe API function call documentation are given at the end.

The kernel crypto API refers to all algorithms as “transformations”.Therefore, a cipher handle variable usually has the name “tfm”. Besidescryptographic operations, the kernel crypto API also knows compressiontransformations and handles them the same way as ciphers.

The kernel crypto API serves the following entity types:

• consumers requesting cryptographic services

• data transformation implementations (typically ciphers) that can becalled by consumers using the kernel crypto API

This specification is intended for consumers of the kernel crypto API aswell as for developers implementing ciphers. This API specification,however, does not discuss all API calls available to data transformationimplementations (i.e. implementations of ciphers and othertransformations (such as CRC or even compression algorithms) that canregister with the kernel crypto API).

Note: The terms “transformation” and cipher algorithm are usedinterchangeably.

Terminology¶

The transformation implementation is an actual code or interface tohardware which implements a certain transformation with preciselydefined behavior.

The transformation object (TFM) is an instance of a transformationimplementation. There can be multiple transformation objects associatedwith a single transformation implementation. Each of thosetransformation objects is held by a crypto API consumer or anothertransformation. Transformation object is allocated when a crypto APIconsumer requests a transformation implementation. The consumer is thenprovided with a structure, which contains a transformation object (TFM).

The structure that contains transformation objects may also be referredto as a “cipher handle”. Such a cipher handle is always subject to thefollowing phases that are reflected in the API calls applicable to sucha cipher handle:

1. Initialization of a cipher handle.

2. Execution of all intended cipher operations applicable for the handlewhere the cipher handle must be furnished to every API call.

3. Destruction of a cipher handle.

When using the initialization API calls, a cipher handle is created andreturned to the consumer. Therefore, please refer to all initializationAPI calls that refer to the data structure type a consumer is expectedto receive and subsequently to use. The initialization API calls haveall the same naming conventions of crypto_alloc*.

The transformation context is private data associated with thetransformation object.