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