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