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