1 User Space Interface
2 ====================
3
4 Introduction
5 ------------
6
7 The concepts of the kernel crypto API visible
8 applicable to the user space interface as well
9 crypto API high level discussion for the in-ke
10 here as well.
11
12 The major difference, however, is that user sp
13 consumer and never as a provider of a transfor
14 algorithm.
15
16 The following covers the user space interface
17 crypto API. A working example of this descript
18 be obtained from [1]. That library can be used
19 applications that require cryptographic servic
20
21 Some details of the in-kernel kernel crypto AP
22 user space, however. This includes the differe
23 and asynchronous invocations. The user space A
24 synchronous.
25
26 [1] https://www.chronox.de/libkcapi.html
27
28 User Space API General Remarks
29 ------------------------------
30
31 The kernel crypto API is accessible from user
32 following ciphers are accessible:
33
34 - Message digest including keyed message dige
35
36 - Symmetric ciphers
37
38 - AEAD ciphers
39
40 - Random Number Generators
41
42 The interface is provided via socket type usin
43 addition, the setsockopt option type is SOL_AL
44 header files do not export these flags yet, us
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
56 A cipher is accessed with the same name as don
57 calls. This includes the generic vs. unique na
58 well as the enforcement of priorities for gene
59
60 To interact with the kernel crypto API, a sock
61 user space application. User space invokes the
62 send()/write() system call family. The result
63 obtained with the read()/recv() system call fa
64
65 The following API calls assume that the socket
66 opened by the user space application and discu
67 crypto API specific invocations.
68
69 To initialize the socket interface, the follow
70 performed by the consumer:
71
72 1. Create a socket of type AF_ALG with the str
73 parameter specified below for the different
74
75 2. Invoke bind with the socket descriptor
76
77 3. Invoke accept with the socket descriptor. T
78 returns a new file descriptor that is to be
79 particular cipher instance. When invoking s
80 system calls to send data to the kernel or
81 kernel, the file descriptor returned by acc
82
83 In-place Cipher operation
84 -------------------------
85
86 Just like the in-kernel operation of the kerne
87 space interface allows the cipher operation in
88 the input buffer used for the send/write syste
89 buffer used by the read/recv system call may b
90 is of particular interest for symmetric cipher
91 copying of the output data to its final destin
92
93 If a consumer on the other hand wants to maint
94 ciphertext in different memory locations, all
95 to provide different memory pointers for the e
96 operation.
97
98 Message Digest API
99 ------------------
100
101 The message digest type to be used for the cip
102 when invoking the bind syscall. bind requires
103 filled struct sockaddr data structure. This da
104 filled as follows:
105
106 ::
107
108 struct sockaddr_alg sa = {
109 .salg_family = AF_ALG,
110 .salg_type = "hash", /* this selects t
111 .salg_name = "sha1" /* this is the cip
112 };
113
114
115 The salg_type value "hash" applies to message
116 digests. Though, a keyed message digest is ref
117 salg_name. Please see below for the setsockopt
118 how the key can be set for a keyed message dig
119
120 Using the send() system call, the application
121 should be processed with the message digest. T
122 the following flags to be specified:
123
124 - MSG_MORE: If this flag is set, the send sys
125 message digest update function where the fi
126 calculated. If the flag is not set, the sen
127 the final message digest immediately.
128
129 With the recv() system call, the application c
130 from the kernel crypto API. If the buffer is t
131 digest, the flag MSG_TRUNC is set by the kerne
132
133 In order to set a message digest key, the call
134 the setsockopt() option of ALG_SET_KEY or ALG_
135 key is not set the HMAC operation is performed
136 change caused by the key.
137
138 Symmetric Cipher API
139 --------------------
140
141 The operation is very similar to the message d
142 initialization, the struct sockaddr data struc
143 follows:
144
145 ::
146
147 struct sockaddr_alg sa = {
148 .salg_family = AF_ALG,
149 .salg_type = "skcipher", /* this selec
150 .salg_name = "cbc(aes)" /* this is the
151 };
152
153
154 Before data can be sent to the kernel using th
155 family, the consumer must set the key. The key
156 the setsockopt invocation below.
157
158 Using the sendmsg() system call, the applicati
159 should be processed for encryption or decrypti
160 specified with the data structure provided by
161
162 The sendmsg system call parameter of struct ms
163 struct cmsghdr data structure. See recv(2) and
164 information on how the cmsghdr data structure
165 send/recv system call family. That cmsghdr dat
166 following information specified with a separat
167
168 - specification of the cipher operation type
169
170 - ALG_OP_ENCRYPT - encryption of data
171
172 - ALG_OP_DECRYPT - decryption of data
173
174 - specification of the IV information marked
175
176 The send system call family allows the followi
177
178 - MSG_MORE: If this flag is set, the send sys
179 cipher update function where more input dat
180 subsequent invocation of the send system ca
181
182 Note: The kernel reports -EINVAL for any unexp
183 must make sure that all data matches the const
184 /proc/crypto for the selected cipher.
185
186 With the recv() system call, the application c
187 cipher operation from the kernel crypto API. T
188 at least as large as to hold all blocks of the
189 data. If the output data size is smaller, only
190 returned that fit into that output buffer size
191
192 AEAD Cipher API
193 ---------------
194
195 The operation is very similar to the symmetric
196 initialization, the struct sockaddr data struc
197 follows:
198
199 ::
200
201 struct sockaddr_alg sa = {
202 .salg_family = AF_ALG,
203 .salg_type = "aead", /* this selects t
204 .salg_name = "gcm(aes)" /* this is the
205 };
206
207
208 Before data can be sent to the kernel using th
209 family, the consumer must set the key. The key
210 the setsockopt invocation below.
211
212 In addition, before data can be sent to the ke
213 system call family, the consumer must set the
214 To set the authentication tag size, the caller
215 invocation described below.
216
217 Using the sendmsg() system call, the applicati
218 should be processed for encryption or decrypti
219 specified with the data structure provided by
220
221 The sendmsg system call parameter of struct ms
222 struct cmsghdr data structure. See recv(2) and
223 information on how the cmsghdr data structure
224 send/recv system call family. That cmsghdr dat
225 following information specified with a separat
226
227 - specification of the cipher operation type
228
229 - ALG_OP_ENCRYPT - encryption of data
230
231 - ALG_OP_DECRYPT - decryption of data
232
233 - specification of the IV information marked
234
235 - specification of the associated authenticat
236 flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent
237 with the plaintext / ciphertext. See below
238
239 The send system call family allows the followi
240
241 - MSG_MORE: If this flag is set, the send sys
242 cipher update function where more input dat
243 subsequent invocation of the send system ca
244
245 Note: The kernel reports -EINVAL for any unexp
246 must make sure that all data matches the const
247 /proc/crypto for the selected cipher.
248
249 With the recv() system call, the application c
250 cipher operation from the kernel crypto API. T
251 at least as large as defined with the memory s
252 output data size is smaller, the cipher operat
253
254 The authenticated decryption operation may ind
255 Such breach in integrity is marked with the -E
256
257 AEAD Memory Structure
258 ~~~~~~~~~~~~~~~~~~~~~
259
260 The AEAD cipher operates with the following in
261 communicated between user and kernel space as
262
263 - plaintext or ciphertext
264
265 - associated authentication data (AAD)
266
267 - authentication tag
268
269 The sizes of the AAD and the authentication ta
270 sendmsg and setsockopt calls (see there). As t
271 of the entire data stream, the kernel is now a
272 offsets of the data components in the data str
273
274 The user space caller must arrange the aforeme
275 following order:
276
277 - AEAD encryption input: AAD \|\| plaintext
278
279 - AEAD decryption input: AAD \|\| ciphertext
280
281 The output buffer the user space caller provid
282 large to hold the following data:
283
284 - AEAD encryption output: ciphertext \|\| aut
285
286 - AEAD decryption output: plaintext
287
288 Random Number Generator API
289 ---------------------------
290
291 Again, the operation is very similar to the ot
292 initialization, the struct sockaddr data struc
293 follows:
294
295 ::
296
297 struct sockaddr_alg sa = {
298 .salg_family = AF_ALG,
299 .salg_type = "rng", /* this selects th
300 .salg_name = "drbg_nopr_sha256" /* thi
301 };
302
303
304 Depending on the RNG type, the RNG must be see
305 using the setsockopt interface to set the key.
306 ansi_cprng requires a seed. The DRBGs do not r
307 seeded. The seed is also known as a *Personali
308 standard.
309
310 Using the read()/recvmsg() system calls, rando
311 The kernel generates at most 128 bytes in one
312 requires more data, multiple calls to read()/r
313
314 WARNING: The user space caller may invoke the
315 system call multiple times. In this case, the
316 have the same state.
317
318 Following CAVP testing interfaces are enabled
319 CRYPTO_USER_API_RNG_CAVP option:
320
321 - the concatenation of *Entropy* and *Nonce*
322 ALG_SET_DRBG_ENTROPY setsockopt interface.
323 CAP_SYS_ADMIN permission.
324
325 - *Additional Data* can be provided using the
326 but only after the entropy has been set.
327
328 Zero-Copy Interface
329 -------------------
330
331 In addition to the send/write/read/recv system
332 interface can be accessed with the zero-copy i
333 splice/vmsplice. As the name indicates, the ke
334 operation into kernel space.
335
336 The zero-copy operation requires data to be al
337 boundary. Non-aligned data can be used as well
338 operations of the kernel which would defeat th
339 from the zero-copy interface.
340
341 The system-inherent limit for the size of one
342 pages. If more data is to be sent to AF_ALG, u
343 input into segments with a maximum size of 16
344
345 Zero-copy can be used with the following code
346 working 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_G
355 /* opfd is the file descriptor returned fr
356 splice(pipes[0], NULL, opfd, NULL, ret, 0)
357 read(opfd, out, outlen);
358
359
360 Setsockopt Interface
361 --------------------
362
363 In addition to the read/recv and send/write sy
364 and retrieve data subject to the cipher operat
365 to set the additional information for the ciph
366 additional information is set using the setsoc
367 be invoked with the file descriptor of the ope
368 descriptor returned by the accept system call)
369
370 Each setsockopt invocation must use the level
371
372 The setsockopt interface allows setting the fo
373 mentioned optname:
374
375 - ALG_SET_KEY -- Setting the key. Key setting
376
377 - the skcipher cipher type (symmetric ciph
378
379 - the hash cipher type (keyed message dige
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
386 This operation behaves the same as ALG_SET_
387 data is copied from a keyring key, and uses
388 key for symmetric encryption.
389
390 The passed in key_serial_t must have the KE
391 permission set, otherwise -EPERM is returne
392 logon, encrypted, and trusted.
393
394 - ALG_SET_AEAD_AUTHSIZE -- Setting the authen
395 AEAD ciphers. For a encryption operation, t
396 the given size will be generated. For a dec
397 provided ciphertext is assumed to contain a
398 the given size (see section about AEAD memo
399
400 - ALG_SET_DRBG_ENTROPY -- Setting the entropy
401 This option is applicable to RNG cipher typ
402
403 User space API example
404 ----------------------
405
406 Please see [1] for libkcapi which provides an
407 the aforementioned Netlink kernel interface. [
408 application that invokes all libkcapi API call
409
410 [1] https://www.chronox.de/libkcapi.html
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.