Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) User Space Interface
^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 concepts of the kernel crypto API visible to kernel space is fully
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) applicable to the user space interface as well. Therefore, the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) crypto API high level discussion for the in-kernel use cases applies
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) here as well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) The major difference, however, is that user space can only act as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) consumer and never as a provider of a transformation or cipher
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) algorithm.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) The following covers the user space interface exported by the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) crypto API. A working example of this description is libkcapi that can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) be obtained from [1]. That library can be used by user space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) applications that require cryptographic services from the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) Some details of the in-kernel kernel crypto API aspects do not apply to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) user space, however. This includes the difference between synchronous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) and asynchronous invocations. The user space API call is fully
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) synchronous.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) [1] https://www.chronox.de/libkcapi.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) User Space API General Remarks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) The kernel crypto API is accessible from user space. Currently, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) following ciphers are accessible:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) -  Message digest including keyed message digest (HMAC, CMAC)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) -  Symmetric ciphers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) -  AEAD ciphers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) -  Random Number Generators
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) The interface is provided via socket type using the type AF_ALG. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) addition, the setsockopt option type is SOL_ALG. In case the user space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) header files do not export these flags yet, use the following macros:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48)     #ifndef AF_ALG
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49)     #define AF_ALG 38
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50)     #endif
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51)     #ifndef SOL_ALG
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52)     #define SOL_ALG 279
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53)     #endif
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) A cipher is accessed with the same name as done for the in-kernel API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) calls. This includes the generic vs. unique naming schema for ciphers as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) well as the enforcement of priorities for generic names.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) To interact with the kernel crypto API, a socket must be created by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) user space application. User space invokes the cipher operation with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) send()/write() system call family. The result of the cipher operation is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) obtained with the read()/recv() system call family.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) The following API calls assume that the socket descriptor is already
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) opened by the user space application and discusses only the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) crypto API specific invocations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) To initialize the socket interface, the following sequence has to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) performed by the consumer:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) 1. Create a socket of type AF_ALG with the struct sockaddr_alg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73)    parameter specified below for the different cipher types.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) 2. Invoke bind with the socket descriptor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) 3. Invoke accept with the socket descriptor. The accept system call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78)    returns a new file descriptor that is to be used to interact with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79)    particular cipher instance. When invoking send/write or recv/read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80)    system calls to send data to the kernel or obtain data from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81)    kernel, the file descriptor returned by accept must be used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) In-place Cipher operation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) Just like the in-kernel operation of the kernel crypto API, the user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) space interface allows the cipher operation in-place. That means that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) the input buffer used for the send/write system call and the output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) buffer used by the read/recv system call may be one and the same. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) is of particular interest for symmetric cipher operations where a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) copying of the output data to its final destination can be avoided.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) If a consumer on the other hand wants to maintain the plaintext and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) ciphertext in different memory locations, all a consumer needs to do is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) to provide different memory pointers for the encryption and decryption
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) Message Digest API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) The message digest type to be used for the cipher operation is selected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) when invoking the bind syscall. bind requires the caller to provide a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) filled struct sockaddr data structure. This data structure must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) filled as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)     struct sockaddr_alg sa = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)         .salg_family = AF_ALG,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)         .salg_type = "hash", /* this selects the hash logic in the kernel */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)         .salg_name = "sha1" /* this is the cipher name */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)     };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) The salg_type value "hash" applies to message digests and keyed message
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) digests. Though, a keyed message digest is referenced by the appropriate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) salg_name. Please see below for the setsockopt interface that explains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) how the key can be set for a keyed message digest.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) Using the send() system call, the application provides the data that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) should be processed with the message digest. The send system call allows
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) the following flags to be specified:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) -  MSG_MORE: If this flag is set, the send system call acts like a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)    message digest update function where the final hash is not yet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)    calculated. If the flag is not set, the send system call calculates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)    the final message digest immediately.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) With the recv() system call, the application can read the message digest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) from the kernel crypto API. If the buffer is too small for the message
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) digest, the flag MSG_TRUNC is set by the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) In order to set a message digest key, the calling application must use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) the setsockopt() option of ALG_SET_KEY. If the key is not set the HMAC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) operation is performed without the initial HMAC state change caused by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) the key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) Symmetric Cipher API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) The operation is very similar to the message digest discussion. During
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) initialization, the struct sockaddr data structure must be filled as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)     struct sockaddr_alg sa = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)         .salg_family = AF_ALG,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)         .salg_type = "skcipher", /* this selects the symmetric cipher */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)         .salg_name = "cbc(aes)" /* this is the cipher name */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)     };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) Before data can be sent to the kernel using the write/send system call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) family, the consumer must set the key. The key setting is described with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) the setsockopt invocation below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) Using the sendmsg() system call, the application provides the data that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) should be processed for encryption or decryption. In addition, the IV is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) specified with the data structure provided by the sendmsg() system call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) The sendmsg system call parameter of struct msghdr is embedded into the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) struct cmsghdr data structure. See recv(2) and cmsg(3) for more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) information on how the cmsghdr data structure is used together with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) send/recv system call family. That cmsghdr data structure holds the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) following information specified with a separate header instances:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) -  specification of the cipher operation type with one of these flags:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170)    -  ALG_OP_ENCRYPT - encryption of data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)    -  ALG_OP_DECRYPT - decryption of data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) -  specification of the IV information marked with the flag ALG_SET_IV
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) The send system call family allows the following flag to be specified:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) -  MSG_MORE: If this flag is set, the send system call acts like a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)    cipher update function where more input data is expected with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)    subsequent invocation of the send system call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) Note: The kernel reports -EINVAL for any unexpected data. The caller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) must make sure that all data matches the constraints given in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) /proc/crypto for the selected cipher.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) With the recv() system call, the application can read the result of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) cipher operation from the kernel crypto API. The output buffer must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) at least as large as to hold all blocks of the encrypted or decrypted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) data. If the output data size is smaller, only as many blocks are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) returned that fit into that output buffer size.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) AEAD Cipher API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) The operation is very similar to the symmetric cipher discussion. During
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) initialization, the struct sockaddr data structure must be filled as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)     struct sockaddr_alg sa = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)         .salg_family = AF_ALG,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)         .salg_type = "aead", /* this selects the symmetric cipher */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)         .salg_name = "gcm(aes)" /* this is the cipher name */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)     };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) Before data can be sent to the kernel using the write/send system call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) family, the consumer must set the key. The key setting is described with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) the setsockopt invocation below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) In addition, before data can be sent to the kernel using the write/send
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) system call family, the consumer must set the authentication tag size.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) To set the authentication tag size, the caller must use the setsockopt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) invocation described below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) Using the sendmsg() system call, the application provides the data that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) should be processed for encryption or decryption. In addition, the IV is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) specified with the data structure provided by the sendmsg() system call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) The sendmsg system call parameter of struct msghdr is embedded into the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) struct cmsghdr data structure. See recv(2) and cmsg(3) for more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) information on how the cmsghdr data structure is used together with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) send/recv system call family. That cmsghdr data structure holds the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) following information specified with a separate header instances:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) -  specification of the cipher operation type with one of these flags:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)    -  ALG_OP_ENCRYPT - encryption of data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)    -  ALG_OP_DECRYPT - decryption of data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) -  specification of the IV information marked with the flag ALG_SET_IV
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) -  specification of the associated authentication data (AAD) with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)    flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)    with the plaintext / ciphertext. See below for the memory structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) The send system call family allows the following flag to be specified:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) -  MSG_MORE: If this flag is set, the send system call acts like a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)    cipher update function where more input data is expected with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243)    subsequent invocation of the send system call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) Note: The kernel reports -EINVAL for any unexpected data. The caller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) must make sure that all data matches the constraints given in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) /proc/crypto for the selected cipher.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) With the recv() system call, the application can read the result of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) cipher operation from the kernel crypto API. The output buffer must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) at least as large as defined with the memory structure below. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) output data size is smaller, the cipher operation is not performed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) The authenticated decryption operation may indicate an integrity error.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) Such breach in integrity is marked with the -EBADMSG error code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) AEAD Memory Structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) ~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) The AEAD cipher operates with the following information that is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) communicated between user and kernel space as one data stream:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) -  plaintext or ciphertext
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) -  associated authentication data (AAD)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) -  authentication tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) The sizes of the AAD and the authentication tag are provided with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) sendmsg and setsockopt calls (see there). As the kernel knows the size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) of the entire data stream, the kernel is now able to calculate the right
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) offsets of the data components in the data stream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) The user space caller must arrange the aforementioned information in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) following order:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) -  AEAD encryption input: AAD \|\| plaintext
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) -  AEAD decryption input: AAD \|\| ciphertext \|\| authentication tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) The output buffer the user space caller provides must be at least as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) large to hold the following data:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) -  AEAD encryption output: ciphertext \|\| authentication tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) -  AEAD decryption output: plaintext
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) Random Number Generator API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) ---------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) Again, the operation is very similar to the other APIs. During
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) initialization, the struct sockaddr data structure must be filled as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)     struct sockaddr_alg sa = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298)         .salg_family = AF_ALG,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299)         .salg_type = "rng", /* this selects the random number generator */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300)         .salg_name = "drbg_nopr_sha256" /* this is the RNG name */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)     };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) Depending on the RNG type, the RNG must be seeded. The seed is provided
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) using the setsockopt interface to set the key. For example, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) ansi_cprng requires a seed. The DRBGs do not require a seed, but may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) seeded. The seed is also known as a *Personalization String* in NIST SP 800-90A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) standard.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) Using the read()/recvmsg() system calls, random numbers can be obtained.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) The kernel generates at most 128 bytes in one call. If user space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) requires more data, multiple calls to read()/recvmsg() must be made.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) WARNING: The user space caller may invoke the initially mentioned accept
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) system call multiple times. In this case, the returned file descriptors
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) have the same state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) Following CAVP testing interfaces are enabled when kernel is built with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) CRYPTO_USER_API_RNG_CAVP option:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) -  the concatenation of *Entropy* and *Nonce* can be provided to the RNG via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322)    ALG_SET_DRBG_ENTROPY setsockopt interface. Setting the entropy requires
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323)    CAP_SYS_ADMIN permission.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) -  *Additional Data* can be provided using the send()/sendmsg() system calls,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)    but only after the entropy has been set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) Zero-Copy Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) In addition to the send/write/read/recv system call family, the AF_ALG
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) interface can be accessed with the zero-copy interface of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) splice/vmsplice. As the name indicates, the kernel tries to avoid a copy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) operation into kernel space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) The zero-copy operation requires data to be aligned at the page
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) boundary. Non-aligned data can be used as well, but may require more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) operations of the kernel which would defeat the speed gains obtained
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) from the zero-copy interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) The system-inherent limit for the size of one zero-copy operation is 16
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) pages. If more data is to be sent to AF_ALG, user space must slice the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) input into segments with a maximum size of 16 pages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) Zero-copy can be used with the following code example (a complete
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) working example is provided with libkcapi):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350)     int pipes[2];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)     pipe(pipes);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)     /* input data in iov */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354)     vmsplice(pipes[1], iov, iovlen, SPLICE_F_GIFT);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355)     /* opfd is the file descriptor returned from accept() system call */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356)     splice(pipes[0], NULL, opfd, NULL, ret, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357)     read(opfd, out, outlen);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) Setsockopt Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) In addition to the read/recv and send/write system call handling to send
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) and retrieve data subject to the cipher operation, a consumer also needs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) to set the additional information for the cipher operation. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) additional information is set using the setsockopt system call that must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) be invoked with the file descriptor of the open cipher (i.e. the file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) descriptor returned by the accept system call).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) Each setsockopt invocation must use the level SOL_ALG.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) The setsockopt interface allows setting the following data using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) mentioned optname:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) -  ALG_SET_KEY -- Setting the key. Key setting is applicable to:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377)    -  the skcipher cipher type (symmetric ciphers)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379)    -  the hash cipher type (keyed message digests)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381)    -  the AEAD cipher type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383)    -  the RNG cipher type to provide the seed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) -  ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386)    AEAD ciphers. For a encryption operation, the authentication tag of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387)    the given size will be generated. For a decryption operation, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388)    provided ciphertext is assumed to contain an authentication tag of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389)    the given size (see section about AEAD memory layout below).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) -  ALG_SET_DRBG_ENTROPY -- Setting the entropy of the random number generator.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392)    This option is applicable to RNG cipher type only.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) User space API example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) Please see [1] for libkcapi which provides an easy-to-use wrapper around
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) the aforementioned Netlink kernel interface. [1] also contains a test
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) application that invokes all libkcapi API calls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) [1] https://www.chronox.de/libkcapi.html