1User Space Interface 2==================== 3 4Introduction 5------------ 6 7AF_ALG provides unprivileged userspace programs access to arbitrary hash, 8symmetric cipher, AEAD, and RNG algorithms that are implemented in kernel-mode 9code. 10 11AF_ALG is insecure and is deprecated. Originally added to the kernel in 2010, 12most kernel developers now consider it to be a mistake. 13 14AF_ALG continues to be supported only for backwards compatibility. On systems 15where no programs using AF_ALG remain, the support for it should be disabled by 16disabling ``CONFIG_CRYPTO_USER_API_*``. 17 18Deprecation 19----------- 20 21AF_ALG was originally intended to provide userspace programs access to crypto 22accelerators that they wouldn't otherwise have access to. 23 24However, that capability turned out to not be useful on very many systems. More 25significantly, the actual implementation exposes a vastly greater amount of 26functionality than that. It actually provides access to all software algorithms. 27 28This includes arbitrary compositions of different algorithms created via a 29complex template system, as well as algorithms that only make sense as internal 30implementation details of other algorithms. It also includes full zero-copy 31support, which is difficult for the kernel to implement securely. 32 33Ultimately, these algorithms are just math computations. They use the same 34instructions that userspace programs already have access to, just accessed in a 35much more convoluted and less efficient way. 36 37Indeed, userspace code is nearly always what is being used anyway. These same 38algorithms are widely implemented in userspace crypto libraries. 39 40Meanwhile, AF_ALG hasn't been withstanding modern vulnerability discovery tools 41such as syzbot and large language models. It receives a steady stream of CVEs. 42Some of the examples include: 43 44- CVE-2026-31677 45- CVE-2026-31431 (https://copy.fail) 46- CVE-2025-38079 47- CVE-2025-37808 48- CVE-2024-26824 49- CVE-2022-48781 50- CVE-2019-8912 51- CVE-2018-14619 52- CVE-2017-18075 53- CVE-2017-17806 54- CVE-2017-17805 55- CVE-2016-10147 56- CVE-2015-8970 57- CVE-2015-3331 58- CVE-2014-9644 59- CVE-2013-7421 60- CVE-2011-4081 61 62It is recommended that, whenever possible, userspace programs be migrated to 63userspace crypto code (which again, is what is normally used anyway) and 64``CONFIG_CRYPTO_USER_API_*`` be disabled. On systems that use SELinux, SELinux 65can also be used to restrict the use of AF_ALG to trusted programs. 66 67The remainder of this documentation provides the historical documentation for 68the deprecated AF_ALG interface. 69 70User Space API General Remarks 71------------------------------ 72 73The kernel crypto API is accessible from user space. Currently, the 74following ciphers are accessible: 75 76- Message digest including keyed message digest (HMAC, CMAC) 77 78- Symmetric ciphers 79 80- AEAD ciphers 81 82- Random Number Generators 83 84The interface is provided via socket type using the type AF_ALG. In 85addition, the setsockopt option type is SOL_ALG. In case the user space 86header files do not export these flags yet, use the following macros: 87 88:: 89 90 #ifndef AF_ALG 91 #define AF_ALG 38 92 #endif 93 #ifndef SOL_ALG 94 #define SOL_ALG 279 95 #endif 96 97 98A cipher is accessed with the same name as done for the in-kernel API 99calls. This includes the generic vs. unique naming schema for ciphers as 100well as the enforcement of priorities for generic names. 101 102To interact with the kernel crypto API, a socket must be created by the 103user space application. User space invokes the cipher operation with the 104send()/write() system call family. The result of the cipher operation is 105obtained with the read()/recv() system call family. 106 107The following API calls assume that the socket descriptor is already 108opened by the user space application and discusses only the kernel 109crypto API specific invocations. 110 111To initialize the socket interface, the following sequence has to be 112performed by the consumer: 113 1141. Create a socket of type AF_ALG with the struct sockaddr_alg 115 parameter specified below for the different cipher types. 116 1172. Invoke bind with the socket descriptor 118 1193. Invoke accept with the socket descriptor. The accept system call 120 returns a new file descriptor that is to be used to interact with the 121 particular cipher instance. When invoking send/write or recv/read 122 system calls to send data to the kernel or obtain data from the 123 kernel, the file descriptor returned by accept must be used. 124 125In-place Cipher operation 126------------------------- 127 128Just like the in-kernel operation of the kernel crypto API, the user 129space interface allows the cipher operation in-place. That means that 130the input buffer used for the send/write system call and the output 131buffer used by the read/recv system call may be one and the same. This 132is of particular interest for symmetric cipher operations where a 133copying of the output data to its final destination can be avoided. 134 135If a consumer on the other hand wants to maintain the plaintext and the 136ciphertext in different memory locations, all a consumer needs to do is 137to provide different memory pointers for the encryption and decryption 138operation. 139 140Message Digest API 141------------------ 142 143The message digest type to be used for the cipher operation is selected 144when invoking the bind syscall. bind requires the caller to provide a 145filled struct sockaddr data structure. This data structure must be 146filled as follows: 147 148:: 149 150 struct sockaddr_alg sa = { 151 .salg_family = AF_ALG, 152 .salg_type = "hash", /* this selects the hash logic in the kernel */ 153 .salg_name = "sha1" /* this is the cipher name */ 154 }; 155 156 157The salg_type value "hash" applies to message digests and keyed message 158digests. Though, a keyed message digest is referenced by the appropriate 159salg_name. Please see below for the setsockopt interface that explains 160how the key can be set for a keyed message digest. 161 162Using the send() system call, the application provides the data that 163should be processed with the message digest. The send system call allows 164the following flags to be specified: 165 166- MSG_MORE: If this flag is set, the send system call acts like a 167 message digest update function where the final hash is not yet 168 calculated. If the flag is not set, the send system call calculates 169 the final message digest immediately. 170 171With the recv() system call, the application can read the message digest 172from the kernel crypto API. If the buffer is too small for the message 173digest, the flag MSG_TRUNC is set by the kernel. 174 175In order to set a message digest key, the calling application must use 176the setsockopt() option of ALG_SET_KEY or ALG_SET_KEY_BY_KEY_SERIAL. If the 177key is not set the HMAC operation is performed without the initial HMAC state 178change caused by the key. 179 180Symmetric Cipher API 181-------------------- 182 183The operation is very similar to the message digest discussion. During 184initialization, the struct sockaddr data structure must be filled as 185follows: 186 187:: 188 189 struct sockaddr_alg sa = { 190 .salg_family = AF_ALG, 191 .salg_type = "skcipher", /* this selects the symmetric cipher */ 192 .salg_name = "cbc(aes)" /* this is the cipher name */ 193 }; 194 195 196Before data can be sent to the kernel using the write/send system call 197family, the consumer must set the key. The key setting is described with 198the setsockopt invocation below. 199 200Using the sendmsg() system call, the application provides the data that 201should be processed for encryption or decryption. In addition, the IV is 202specified with the data structure provided by the sendmsg() system call. 203 204The sendmsg system call parameter of struct msghdr is embedded into the 205struct cmsghdr data structure. See recv(2) and cmsg(3) for more 206information on how the cmsghdr data structure is used together with the 207send/recv system call family. That cmsghdr data structure holds the 208following information specified with a separate header instances: 209 210- specification of the cipher operation type with one of these flags: 211 212 - ALG_OP_ENCRYPT - encryption of data 213 214 - ALG_OP_DECRYPT - decryption of data 215 216- specification of the IV information marked with the flag ALG_SET_IV 217 218The send system call family allows the following flag to be specified: 219 220- MSG_MORE: If this flag is set, the send system call acts like a 221 cipher update function where more input data is expected with a 222 subsequent invocation of the send system call. 223 224Note: The kernel reports -EINVAL for any unexpected data. The caller 225must make sure that all data matches the constraints given in 226/proc/crypto for the selected cipher. 227 228With the recv() system call, the application can read the result of the 229cipher operation from the kernel crypto API. The output buffer must be 230at least as large as to hold all blocks of the encrypted or decrypted 231data. If the output data size is smaller, only as many blocks are 232returned that fit into that output buffer size. 233 234AEAD Cipher API 235--------------- 236 237The operation is very similar to the symmetric cipher discussion. During 238initialization, the struct sockaddr data structure must be filled as 239follows: 240 241:: 242 243 struct sockaddr_alg sa = { 244 .salg_family = AF_ALG, 245 .salg_type = "aead", /* this selects the symmetric cipher */ 246 .salg_name = "gcm(aes)" /* this is the cipher name */ 247 }; 248 249 250Before data can be sent to the kernel using the write/send system call 251family, the consumer must set the key. The key setting is described with 252the setsockopt invocation below. 253 254In addition, before data can be sent to the kernel using the write/send 255system call family, the consumer must set the authentication tag size. 256To set the authentication tag size, the caller must use the setsockopt 257invocation described below. 258 259Using the sendmsg() system call, the application provides the data that 260should be processed for encryption or decryption. In addition, the IV is 261specified with the data structure provided by the sendmsg() system call. 262 263The sendmsg system call parameter of struct msghdr is embedded into the 264struct cmsghdr data structure. See recv(2) and cmsg(3) for more 265information on how the cmsghdr data structure is used together with the 266send/recv system call family. That cmsghdr data structure holds the 267following information specified with a separate header instances: 268 269- specification of the cipher operation type with one of these flags: 270 271 - ALG_OP_ENCRYPT - encryption of data 272 273 - ALG_OP_DECRYPT - decryption of data 274 275- specification of the IV information marked with the flag ALG_SET_IV 276 277- specification of the associated authentication data (AAD) with the 278 flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together 279 with the plaintext / ciphertext. See below for the memory structure. 280 281The send system call family allows the following flag to be specified: 282 283- MSG_MORE: If this flag is set, the send system call acts like a 284 cipher update function where more input data is expected with a 285 subsequent invocation of the send system call. 286 287Note: The kernel reports -EINVAL for any unexpected data. The caller 288must make sure that all data matches the constraints given in 289/proc/crypto for the selected cipher. 290 291With the recv() system call, the application can read the result of the 292cipher operation from the kernel crypto API. The output buffer must be 293at least as large as defined with the memory structure below. If the 294output data size is smaller, the cipher operation is not performed. 295 296The authenticated decryption operation may indicate an integrity error. 297Such breach in integrity is marked with the -EBADMSG error code. 298 299AEAD Memory Structure 300~~~~~~~~~~~~~~~~~~~~~ 301 302The AEAD cipher operates with the following information that is 303communicated between user and kernel space as one data stream: 304 305- plaintext or ciphertext 306 307- associated authentication data (AAD) 308 309- authentication tag 310 311The sizes of the AAD and the authentication tag are provided with the 312sendmsg and setsockopt calls (see there). As the kernel knows the size 313of the entire data stream, the kernel is now able to calculate the right 314offsets of the data components in the data stream. 315 316The user space caller must arrange the aforementioned information in the 317following order: 318 319- AEAD encryption input: AAD \|\| plaintext 320 321- AEAD decryption input: AAD \|\| ciphertext \|\| authentication tag 322 323The output buffer the user space caller provides must be at least as 324large to hold the following data: 325 326- AEAD encryption output: ciphertext \|\| authentication tag 327 328- AEAD decryption output: plaintext 329 330Random Number Generator API 331--------------------------- 332 333Again, the operation is very similar to the other APIs. During 334initialization, the struct sockaddr data structure must be filled as 335follows: 336 337:: 338 339 struct sockaddr_alg sa = { 340 .salg_family = AF_ALG, 341 .salg_type = "rng", /* this selects the random number generator */ 342 .salg_name = "stdrng" /* this is the RNG name */ 343 }; 344 345 346Depending on the RNG type, the RNG must be seeded. The seed is provided 347using the setsockopt interface to set the key. The SP800-90A DRBGs do 348not require a seed, but may be seeded. The seed is also known as a 349*Personalization String* in NIST SP 800-90A standard. 350 351Using the read()/recvmsg() system calls, random numbers can be obtained. 352The kernel generates at most 128 bytes in one call. If user space 353requires more data, multiple calls to read()/recvmsg() must be made. 354 355WARNING: The user space caller may invoke the initially mentioned accept 356system call multiple times. In this case, the returned file descriptors 357have the same state. 358 359Following CAVP testing interfaces are enabled when kernel is built with 360CRYPTO_USER_API_RNG_CAVP option: 361 362- the concatenation of *Entropy* and *Nonce* can be provided to the RNG via 363 ALG_SET_DRBG_ENTROPY setsockopt interface. Setting the entropy requires 364 CAP_SYS_ADMIN permission. 365 366- *Additional Data* can be provided using the send()/sendmsg() system calls, 367 but only after the entropy has been set. 368 369Zero-Copy Interface 370------------------- 371 372AF_ALG used to have zero-copy support, but it was removed due to it being a 373frequent source of vulnerabilities. For backwards compatibility the splice() 374and sendfile() system calls are still supported, but the kernel will make an 375internal copy of the data before passing it to the crypto code. 376 377 378Setsockopt Interface 379-------------------- 380 381In addition to the read/recv and send/write system call handling to send 382and retrieve data subject to the cipher operation, a consumer also needs 383to set the additional information for the cipher operation. This 384additional information is set using the setsockopt system call that must 385be invoked with the file descriptor of the open cipher (i.e. the file 386descriptor returned by the accept system call). 387 388Each setsockopt invocation must use the level SOL_ALG. 389 390The setsockopt interface allows setting the following data using the 391mentioned optname: 392 393- ALG_SET_KEY -- Setting the key. Key setting is applicable to: 394 395 - the skcipher cipher type (symmetric ciphers) 396 397 - the hash cipher type (keyed message digests) 398 399 - the AEAD cipher type 400 401 - the RNG cipher type to provide the seed 402 403- ALG_SET_KEY_BY_KEY_SERIAL -- Setting the key via keyring key_serial_t. 404 This operation behaves the same as ALG_SET_KEY. The decrypted 405 data is copied from a keyring key, and uses that data as the 406 key for symmetric encryption. 407 408 The passed in key_serial_t must have the KEY_(POS|USR|GRP|OTH)_SEARCH 409 permission set, otherwise -EPERM is returned. Supports key types: user, 410 logon, encrypted, and trusted. 411 412- ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size for 413 AEAD ciphers. For a encryption operation, the authentication tag of 414 the given size will be generated. For a decryption operation, the 415 provided ciphertext is assumed to contain an authentication tag of 416 the given size (see section about AEAD memory layout below). 417 418- ALG_SET_DRBG_ENTROPY -- Setting the entropy of the random number generator. 419 This option is applicable to RNG cipher type only. 420 421User space API example 422---------------------- 423 424Please see [1] for libkcapi which provides an easy-to-use wrapper around 425the aforementioned Netlink kernel interface. [1] also contains a test 426application that invokes all libkcapi API calls. 427 428[1] https://www.chronox.de/libkcapi/index.html 429