1Kernel Crypto API Interface Specification
2=========================================
3
4Introduction
5------------
6
7The kernel crypto API offers a rich set of cryptographic ciphers as well
8as other data transformation mechanisms and methods to invoke these.
9This document contains a description of the API and provides example
10code.
11
12To understand and properly use the kernel crypto API a brief explanation
13of its structure is given. Based on the architecture, the API can be
14separated into different components. Following the architecture
15specification, hints to developers of ciphers are provided. Pointers to
16the API function call documentation are given at the end.
17
18The kernel crypto API refers to all algorithms as "transformations".
19Therefore, a cipher handle variable usually has the name "tfm". Besides
20cryptographic operations, the kernel crypto API also knows compression
21transformations and handles them the same way as ciphers.
22
23The kernel crypto API serves the following entity types:
24
25-  consumers requesting cryptographic services
26
27-  data transformation implementations (typically ciphers) that can be
28   called by consumers using the kernel crypto API
29
30This specification is intended for consumers of the kernel crypto API as
31well as for developers implementing ciphers. This API specification,
32however, does not discuss all API calls available to data transformation
33implementations (i.e. implementations of ciphers and other
34transformations (such as CRC or even compression algorithms) that can
35register with the kernel crypto API).
36
37Note: The terms "transformation" and cipher algorithm are used
38interchangeably.
39
40Terminology
41-----------
42
43The transformation implementation is an actual code or interface to
44hardware which implements a certain transformation with precisely
45defined behavior.
46
47The transformation object (TFM) is an instance of a transformation
48implementation. There can be multiple transformation objects associated
49with a single transformation implementation. Each of those
50transformation objects is held by a crypto API consumer or another
51transformation. Transformation object is allocated when a crypto API
52consumer requests a transformation implementation. The consumer is then
53provided with a structure, which contains a transformation object (TFM).
54
55The structure that contains transformation objects may also be referred
56to as a "cipher handle". Such a cipher handle is always subject to the
57following phases that are reflected in the API calls applicable to such
58a cipher handle:
59
601. Initialization of a cipher handle.
61
622. Execution of all intended cipher operations applicable for the handle
63   where the cipher handle must be furnished to every API call.
64
653. Destruction of a cipher handle.
66
67When using the initialization API calls, a cipher handle is created and
68returned to the consumer. Therefore, please refer to all initialization
69API calls that refer to the data structure type a consumer is expected
70to receive and subsequently to use. The initialization API calls have
71all the same naming conventions of crypto_alloc\*.
72
73The transformation context is private data associated with the
74transformation object.
75