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