userspace-if.rst 15 KB

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