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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.