75 lines · plain
1Kernel Crypto API Interface Specification2=========================================3 4Introduction5------------6 7The kernel crypto API offers a rich set of cryptographic ciphers as well8as other data transformation mechanisms and methods to invoke these.9This document contains a description of the API and provides example10code.11 12To understand and properly use the kernel crypto API a brief explanation13of its structure is given. Based on the architecture, the API can be14separated into different components. Following the architecture15specification, hints to developers of ciphers are provided. Pointers to16the 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". Besides20cryptographic operations, the kernel crypto API also knows compression21transformations and handles them the same way as ciphers.22 23The kernel crypto API serves the following entity types:24 25- consumers requesting cryptographic services26 27- data transformation implementations (typically ciphers) that can be28 called by consumers using the kernel crypto API29 30This specification is intended for consumers of the kernel crypto API as31well as for developers implementing ciphers. This API specification,32however, does not discuss all API calls available to data transformation33implementations (i.e. implementations of ciphers and other34transformations (such as CRC or even compression algorithms) that can35register with the kernel crypto API).36 37Note: The terms "transformation" and cipher algorithm are used38interchangeably.39 40Terminology41-----------42 43The transformation implementation is an actual code or interface to44hardware which implements a certain transformation with precisely45defined behavior.46 47The transformation object (TFM) is an instance of a transformation48implementation. There can be multiple transformation objects associated49with a single transformation implementation. Each of those50transformation objects is held by a crypto API consumer or another51transformation. Transformation object is allocated when a crypto API52consumer requests a transformation implementation. The consumer is then53provided with a structure, which contains a transformation object (TFM).54 55The structure that contains transformation objects may also be referred56to as a "cipher handle". Such a cipher handle is always subject to the57following phases that are reflected in the API calls applicable to such58a cipher handle:59 601. Initialization of a cipher handle.61 622. Execution of all intended cipher operations applicable for the handle63 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 and68returned to the consumer. Therefore, please refer to all initialization69API calls that refer to the data structure type a consumer is expected70to receive and subsequently to use. The initialization API calls have71all the same naming conventions of crypto_alloc\*.72 73The transformation context is private data associated with the74transformation object.75