Documentation/crypto/userspace-if.rst

1 User Space Interface
5 ------------
8 applicable to the user space interface as well. Therefore, the kernel
9 crypto API high level discussion for the in-kernel use cases applies
12 The major difference, however, is that user space can only act as a
16 The following covers the user space interface exported by the kernel
18 be obtained from [1]. That library can be used by user space
21 Some details of the in-kernel kernel crypto API aspects do not apply to
22 user space, however. This includes the difference between synchronous
23 and asynchronous invocations. The user space API call is fully
28 User Space API General Remarks
29 ------------------------------
31 The kernel crypto API is accessible from user space. Currently, the
34 -  Message digest including keyed message digest (HMAC, CMAC)
36 -  Symmetric ciphers
38 -  AEAD ciphers
40 -  Random Number Generators
43 addition, the setsockopt option type is SOL_ALG. In case the user space
56 A cipher is accessed with the same name as done for the in-kernel API
61 user space application. User space invokes the cipher operation with the
66 opened by the user space application and discusses only the kernel
83 In-place Cipher operation
84 -------------------------
86 Just like the in-kernel operation of the kernel crypto API, the user
87 space interface allows the cipher operation in-place. That means that
99 ------------------
101 The message digest type to be used for the cipher operation is selected
124 -  MSG_MORE: If this flag is set, the send system call acts like a
139 --------------------
168 -  specification of the cipher operation type with one of these flags:
170    -  ALG_OP_ENCRYPT - encryption of data
172    -  ALG_OP_DECRYPT - decryption of data
174 -  specification of the IV information marked with the flag ALG_SET_IV
178 -  MSG_MORE: If this flag is set, the send system call acts like a
182 Note: The kernel reports -EINVAL for any unexpected data. The caller
184 /proc/crypto for the selected cipher.
193 ---------------
227 -  specification of the cipher operation type with one of these flags:
229    -  ALG_OP_ENCRYPT - encryption of data
231    -  ALG_OP_DECRYPT - decryption of data
233 -  specification of the IV information marked with the flag ALG_SET_IV
235 -  specification of the associated authentication data (AAD) with the
241 -  MSG_MORE: If this flag is set, the send system call acts like a
245 Note: The kernel reports -EINVAL for any unexpected data. The caller
247 /proc/crypto for the selected cipher.
255 Such breach in integrity is marked with the -EBADMSG error code.
261 communicated between user and kernel space as one data stream:
263 -  plaintext or ciphertext
265 -  associated authentication data (AAD)
267 -  authentication tag
274 The user space caller must arrange the aforementioned information in the
277 -  AEAD encryption input: AAD \|\| plaintext
279 -  AEAD decryption input: AAD \|\| ciphertext \|\| authentication tag
281 The output buffer the user space caller provides must be at least as
284 -  AEAD encryption output: ciphertext \|\| authentication tag
286 -  AEAD decryption output: plaintext
289 ---------------------------
307 seeded. The seed is also known as a *Personalization String* in NIST SP 800-90A
311 The kernel generates at most 128 bytes in one call. If user space
314 WARNING: The user space caller may invoke the initially mentioned accept
321 -  the concatenation of *Entropy* and *Nonce* can be provided to the RNG via
325 -  *Additional Data* can be provided using the send()/sendmsg() system calls,
328 Zero-Copy Interface
329 -------------------
332 interface can be accessed with the zero-copy interface of
336 The zero-copy operation requires data to be aligned at the page
337 boundary. Non-aligned data can be used as well, but may require more
339 from the zero-copy interface.
341 The system-inherent limit for the size of one zero-copy operation is 16
342 pages. If more data is to be sent to AF_ALG, user space must slice the
345 Zero-copy can be used with the following code example (a complete
361 --------------------
375 -  ALG_SET_KEY -- Setting the key. Key setting is applicable to:
377    -  the skcipher cipher type (symmetric ciphers)
379    -  the hash cipher type (keyed message digests)
381    -  the AEAD cipher type
383    -  the RNG cipher type to provide the seed
385 - ALG_SET_KEY_BY_KEY_SERIAL -- Setting the key via keyring key_serial_t.
391    permission set, otherwise -EPERM is returned. Supports key types: user,
394 -  ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size for
400 -  ALG_SET_DRBG_ENTROPY -- Setting the entropy of the random number generator.
403 User space API example
404 ----------------------
406 Please see [1] for libkcapi which provides an easy-to-use wrapper around