0001 Kernel Crypto API Interface Specification
0002 =========================================
0003
0004 Introduction
0005 ------------
0006
0007 The kernel crypto API offers a rich set of cryptographic ciphers as well
0008 as other data transformation mechanisms and methods to invoke these.
0009 This document contains a description of the API and provides example
0010 code.
0011
0012 To understand and properly use the kernel crypto API a brief explanation
0013 of its structure is given. Based on the architecture, the API can be
0014 separated into different components. Following the architecture
0015 specification, hints to developers of ciphers are provided. Pointers to
0016 the API function call documentation are given at the end.
0017
0018 The kernel crypto API refers to all algorithms as "transformations".
0019 Therefore, a cipher handle variable usually has the name "tfm". Besides
0020 cryptographic operations, the kernel crypto API also knows compression
0021 transformations and handles them the same way as ciphers.
0022
0023 The kernel crypto API serves the following entity types:
0024
0025 - consumers requesting cryptographic services
0026
0027 - data transformation implementations (typically ciphers) that can be
0028 called by consumers using the kernel crypto API
0029
0030 This specification is intended for consumers of the kernel crypto API as
0031 well as for developers implementing ciphers. This API specification,
0032 however, does not discuss all API calls available to data transformation
0033 implementations (i.e. implementations of ciphers and other
0034 transformations (such as CRC or even compression algorithms) that can
0035 register with the kernel crypto API).
0036
0037 Note: The terms "transformation" and cipher algorithm are used
0038 interchangeably.
0039
0040 Terminology
0041 -----------
0042
0043 The transformation implementation is an actual code or interface to
0044 hardware which implements a certain transformation with precisely
0045 defined behavior.
0046
0047 The transformation object (TFM) is an instance of a transformation
0048 implementation. There can be multiple transformation objects associated
0049 with a single transformation implementation. Each of those
0050 transformation objects is held by a crypto API consumer or another
0051 transformation. Transformation object is allocated when a crypto API
0052 consumer requests a transformation implementation. The consumer is then
0053 provided with a structure, which contains a transformation object (TFM).
0054
0055 The structure that contains transformation objects may also be referred
0056 to as a "cipher handle". Such a cipher handle is always subject to the
0057 following phases that are reflected in the API calls applicable to such
0058 a cipher handle:
0059
0060 1. Initialization of a cipher handle.
0061
0062 2. Execution of all intended cipher operations applicable for the handle
0063 where the cipher handle must be furnished to every API call.
0064
0065 3. Destruction of a cipher handle.
0066
0067 When using the initialization API calls, a cipher handle is created and
0068 returned to the consumer. Therefore, please refer to all initialization
0069 API calls that refer to the data structure type a consumer is expected
0070 to receive and subsequently to use. The initialization API calls have
0071 all the same naming conventions of crypto_alloc\*.
0072
0073 The transformation context is private data associated with the
0074 transformation object.
