diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2016-12-18 03:00:34 +0300 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2016-12-18 03:00:34 +0300 |
commit | 0aaf2146ecf00f7932f472ec5aa30d999c89530c (patch) | |
tree | 690dd244437f1974b8132fcb1e360213f827bf94 /Documentation/crypto/intro.rst | |
parent | 59331c215daf600a650e281b6e8ef3e1ed1174c2 (diff) | |
parent | 3fa71d0f58a9b9df84e8e79196f961bcfbf01b2e (diff) | |
download | linux-0aaf2146ecf00f7932f472ec5aa30d999c89530c.tar.xz |
Merge tag 'docs-4.10-2' of git://git.lwn.net/linux
Pull more documentation updates from Jonathan Corbet:
"This converts the crypto DocBook to Sphinx"
* tag 'docs-4.10-2' of git://git.lwn.net/linux:
crypto: doc - optimize compilation
crypto: doc - clarify AEAD memory structure
crypto: doc - remove crypto_alloc_ablkcipher
crypto: doc - add KPP documentation
crypto: doc - fix separation of cipher / req API
crypto: doc - fix source comments for Sphinx
crypto: doc - remove crypto API DocBook
crypto: doc - convert crypto API documentation to Sphinx
Diffstat (limited to 'Documentation/crypto/intro.rst')
-rw-r--r-- | Documentation/crypto/intro.rst | 74 |
1 files changed, 74 insertions, 0 deletions
diff --git a/Documentation/crypto/intro.rst b/Documentation/crypto/intro.rst new file mode 100644 index 000000000000..9aa89ebbfba9 --- /dev/null +++ b/Documentation/crypto/intro.rst @@ -0,0 +1,74 @@ +Kernel Crypto API Interface Specification +========================================= + +Introduction +------------ + +The kernel crypto API offers a rich set of cryptographic ciphers as well +as other data transformation mechanisms and methods to invoke these. +This document contains a description of the API and provides example +code. + +To understand and properly use the kernel crypto API a brief explanation +of its structure is given. Based on the architecture, the API can be +separated into different components. Following the architecture +specification, hints to developers of ciphers are provided. Pointers to +the API function call documentation are given at the end. + +The kernel crypto API refers to all algorithms as "transformations". +Therefore, a cipher handle variable usually has the name "tfm". Besides +cryptographic operations, the kernel crypto API also knows compression +transformations and handles them the same way as ciphers. + +The kernel crypto API serves the following entity types: + +- consumers requesting cryptographic services + +- data transformation implementations (typically ciphers) that can be + called by consumers using the kernel crypto API + +This specification is intended for consumers of the kernel crypto API as +well as for developers implementing ciphers. This API specification, +however, does not discuss all API calls available to data transformation +implementations (i.e. implementations of ciphers and other +transformations (such as CRC or even compression algorithms) that can +register with the kernel crypto API). + +Note: The terms "transformation" and cipher algorithm are used +interchangeably. + +Terminology +----------- + +The transformation implementation is an actual code or interface to +hardware which implements a certain transformation with precisely +defined behavior. + +The transformation object (TFM) is an instance of a transformation +implementation. There can be multiple transformation objects associated +with a single transformation implementation. Each of those +transformation objects is held by a crypto API consumer or another +transformation. Transformation object is allocated when a crypto API +consumer requests a transformation implementation. The consumer is then +provided with a structure, which contains a transformation object (TFM). + +The structure that contains transformation objects may also be referred +to as a "cipher handle". Such a cipher handle is always subject to the +following phases that are reflected in the API calls applicable to such +a cipher handle: + +1. Initialization of a cipher handle. + +2. Execution of all intended cipher operations applicable for the handle + where the cipher handle must be furnished to every API call. + +3. Destruction of a cipher handle. + +When using the initialization API calls, a cipher handle is created and +returned to the consumer. Therefore, please refer to all initialization +API calls that refer to the data structure type a consumer is expected +to receive and subsequently to use. The initialization API calls have +all the same naming conventions of crypto_alloc\*. + +The transformation context is private data associated with the +transformation object. |