1*3b72c814SStephan MuellerKernel Crypto API Interface Specification 2*3b72c814SStephan Mueller========================================= 3*3b72c814SStephan Mueller 4*3b72c814SStephan MuellerIntroduction 5*3b72c814SStephan Mueller------------ 6*3b72c814SStephan Mueller 7*3b72c814SStephan MuellerThe kernel crypto API offers a rich set of cryptographic ciphers as well 8*3b72c814SStephan Muelleras other data transformation mechanisms and methods to invoke these. 9*3b72c814SStephan MuellerThis document contains a description of the API and provides example 10*3b72c814SStephan Muellercode. 11*3b72c814SStephan Mueller 12*3b72c814SStephan MuellerTo understand and properly use the kernel crypto API a brief explanation 13*3b72c814SStephan Muellerof its structure is given. Based on the architecture, the API can be 14*3b72c814SStephan Muellerseparated into different components. Following the architecture 15*3b72c814SStephan Muellerspecification, hints to developers of ciphers are provided. Pointers to 16*3b72c814SStephan Muellerthe API function call documentation are given at the end. 17*3b72c814SStephan Mueller 18*3b72c814SStephan MuellerThe kernel crypto API refers to all algorithms as "transformations". 19*3b72c814SStephan MuellerTherefore, a cipher handle variable usually has the name "tfm". Besides 20*3b72c814SStephan Muellercryptographic operations, the kernel crypto API also knows compression 21*3b72c814SStephan Muellertransformations and handles them the same way as ciphers. 22*3b72c814SStephan Mueller 23*3b72c814SStephan MuellerThe kernel crypto API serves the following entity types: 24*3b72c814SStephan Mueller 25*3b72c814SStephan Mueller- consumers requesting cryptographic services 26*3b72c814SStephan Mueller 27*3b72c814SStephan Mueller- data transformation implementations (typically ciphers) that can be 28*3b72c814SStephan Mueller called by consumers using the kernel crypto API 29*3b72c814SStephan Mueller 30*3b72c814SStephan MuellerThis specification is intended for consumers of the kernel crypto API as 31*3b72c814SStephan Muellerwell as for developers implementing ciphers. This API specification, 32*3b72c814SStephan Muellerhowever, does not discuss all API calls available to data transformation 33*3b72c814SStephan Muellerimplementations (i.e. implementations of ciphers and other 34*3b72c814SStephan Muellertransformations (such as CRC or even compression algorithms) that can 35*3b72c814SStephan Muellerregister with the kernel crypto API). 36*3b72c814SStephan Mueller 37*3b72c814SStephan MuellerNote: The terms "transformation" and cipher algorithm are used 38*3b72c814SStephan Muellerinterchangeably. 39*3b72c814SStephan Mueller 40*3b72c814SStephan MuellerTerminology 41*3b72c814SStephan Mueller----------- 42*3b72c814SStephan Mueller 43*3b72c814SStephan MuellerThe transformation implementation is an actual code or interface to 44*3b72c814SStephan Muellerhardware which implements a certain transformation with precisely 45*3b72c814SStephan Muellerdefined behavior. 46*3b72c814SStephan Mueller 47*3b72c814SStephan MuellerThe transformation object (TFM) is an instance of a transformation 48*3b72c814SStephan Muellerimplementation. There can be multiple transformation objects associated 49*3b72c814SStephan Muellerwith a single transformation implementation. Each of those 50*3b72c814SStephan Muellertransformation objects is held by a crypto API consumer or another 51*3b72c814SStephan Muellertransformation. Transformation object is allocated when a crypto API 52*3b72c814SStephan Muellerconsumer requests a transformation implementation. The consumer is then 53*3b72c814SStephan Muellerprovided with a structure, which contains a transformation object (TFM). 54*3b72c814SStephan Mueller 55*3b72c814SStephan MuellerThe structure that contains transformation objects may also be referred 56*3b72c814SStephan Muellerto as a "cipher handle". Such a cipher handle is always subject to the 57*3b72c814SStephan Muellerfollowing phases that are reflected in the API calls applicable to such 58*3b72c814SStephan Muellera cipher handle: 59*3b72c814SStephan Mueller 60*3b72c814SStephan Mueller1. Initialization of a cipher handle. 61*3b72c814SStephan Mueller 62*3b72c814SStephan Mueller2. Execution of all intended cipher operations applicable for the handle 63*3b72c814SStephan Mueller where the cipher handle must be furnished to every API call. 64*3b72c814SStephan Mueller 65*3b72c814SStephan Mueller3. Destruction of a cipher handle. 66*3b72c814SStephan Mueller 67*3b72c814SStephan MuellerWhen using the initialization API calls, a cipher handle is created and 68*3b72c814SStephan Muellerreturned to the consumer. Therefore, please refer to all initialization 69*3b72c814SStephan MuellerAPI calls that refer to the data structure type a consumer is expected 70*3b72c814SStephan Muellerto receive and subsequently to use. The initialization API calls have 71*3b72c814SStephan Muellerall the same naming conventions of crypto_alloc\*. 72*3b72c814SStephan Mueller 73*3b72c814SStephan MuellerThe transformation context is private data associated with the 74*3b72c814SStephan Muellertransformation object. 75