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