Orange Pi5 kernel

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