Documentation/crypto/intro.rst

   1 Kernel Crypto API Interface Specification
   2 =========================================
   3
   4 Introduction
   5 ------------
   6
   7 The kernel crypto API offers a rich set of cryptographic ciphers as well
   8 as other data transformation mechanisms and methods to invoke these.
   9 This document contains a description of the API and provides example
  10 code.
  11
  12 To understand and properly use the kernel crypto API a brief explanation
  13 of its structure is given. Based on the architecture, the API can be
  14 separated into different components. Following the architecture
  15 specification, hints to developers of ciphers are provided. Pointers to
  16 the API function call documentation are given at the end.
  17
  18 The kernel crypto API refers to all algorithms as "transformations".
  19 Therefore, a cipher handle variable usually has the name "tfm". Besides
  20 cryptographic operations, the kernel crypto API also knows compression
  21 transformations and handles them the same way as ciphers.
  22
  23 The 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
  30 This specification is intended for consumers of the kernel crypto API as
  31 well as for developers implementing ciphers. This API specification,
  32 however, does not discuss all API calls available to data transformation
  33 implementations (i.e. implementations of ciphers and other
  34 transformations (such as CRC or even compression algorithms) that can
  35 register with the kernel crypto API).
  36
  37 Note: The terms "transformation" and cipher algorithm are used
  38 interchangeably.
  39
  40 Terminology
  41 -----------
  42
  43 The transformation implementation is an actual code or interface to
  44 hardware which implements a certain transformation with precisely
  45 defined behavior.
  46
  47 The transformation object (TFM) is an instance of a transformation
  48 implementation. There can be multiple transformation objects associated
  49 with a single transformation implementation. Each of those
  50 transformation objects is held by a crypto API consumer or another
  51 transformation. Transformation object is allocated when a crypto API
  52 consumer requests a transformation implementation. The consumer is then
  53 provided with a structure, which contains a transformation object (TFM).
  54
  55 The structure that contains transformation objects may also be referred
  56 to as a "cipher handle". Such a cipher handle is always subject to the
  57 following phases that are reflected in the API calls applicable to such
  58 a cipher handle:
  59
  60 1. Initialization of a cipher handle.
  61
  62 2. Execution of all intended cipher operations applicable for the handle
  63    where the cipher handle must be furnished to every API call.
  64
  65 3. Destruction of a cipher handle.
  66
  67 When using the initialization API calls, a cipher handle is created and
  68 returned to the consumer. Therefore, please refer to all initialization
  69 API calls that refer to the data structure type a consumer is expected
  70 to receive and subsequently to use. The initialization API calls have
  71 all the same naming conventions of crypto_alloc\*.
  72
  73 The transformation context is private data associated with the
  74 transformation object.