Documentation/crypto/userspace-if.rst

Source file repositories/reference/linux-study-clean/Documentation/crypto/userspace-if.rst

File Facts

System
Linux kernel
Corpus path
Documentation/crypto/userspace-if.rst
Extension
.rst
Size
17445 bytes
Lines
449
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

User Space Interface
====================

Introduction
------------

AF_ALG provides unprivileged userspace programs access to arbitrary hash,
symmetric cipher, AEAD, and RNG algorithms that are implemented in kernel-mode
code.

AF_ALG is insecure and is deprecated. Originally added to the kernel in 2010,
most kernel developers now consider it to be a mistake. Support for hardware
accelerators, which was the original purpose of AF_ALG, has been removed.

AF_ALG continues to be supported only for backwards compatibility. On systems
where no programs using AF_ALG remain, the support for it should be disabled by
disabling ``CONFIG_CRYPTO_USER_API_*``.

Deprecation
-----------

AF_ALG was originally intended to provide userspace programs access to crypto
accelerators that they wouldn't otherwise have access to.

However, that capability turned out to not be useful on very many systems. More
significantly, the actual implementation exposes a vastly greater amount of
functionality than that. It actually provides access to all software algorithms.

This includes arbitrary compositions of different algorithms created via a
complex template system, as well as algorithms that only make sense as internal
implementation details of other algorithms. In the past, it also included full
zero-copy support, which was difficult for the kernel to implement securely.

Ultimately, these algorithms are just math computations. They use the same
instructions that userspace programs already have access to, just accessed in a
much more convoluted and less efficient way.

Indeed, userspace code is nearly always what is being used anyway. These same
algorithms are widely implemented in userspace crypto libraries.

Even when zero-copy and off-CPU accelerators were supported, AF_ALG was usually
much slower than optimized software cryptography in userspace. This was
especially true for the small message sizes usually seen in performance-critical
workloads. While it was possible to demonstrate performance wins for hashing
large files on embedded devices, it is hard to imagine a situation where this
would be performance-critical.

Nowadays, AF_ALG no longer supports zero-copy or off-CPU accelerators.
Therefore, it is *always* slower than an optimized userspace implementation,
even for large messages. The only possible advantage left is that it avoids
duplicating code between kernel and userspace. However, userspace
implementations, especially hardware-accelerated ones, do not need to be large.
Just because OpenSSL is huge does not mean that all userspace cryptography
libraries are.

Meanwhile, AF_ALG hasn't been withstanding modern vulnerability discovery tools
such as syzbot and large language models. It receives a steady stream of CVEs.
Some of the examples include:

- CVE-2026-31677
- CVE-2026-31431 (https://copy.fail)
- CVE-2025-38079
- CVE-2025-37808
- CVE-2024-26824
- CVE-2022-48781
- CVE-2019-8912
- CVE-2018-14619
- CVE-2017-18075
- CVE-2017-17806
- CVE-2017-17805

Annotation

Implementation Notes