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