intro.rst (3158B)
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.