From 8c2f1288250a90a4b5cabed5d888d7e3aeed4035 Mon Sep 17 00:00:00 2001 From: Lukas Wunner Date: Sun, 12 Apr 2026 16:19:47 +0200 Subject: [PATCH 1/3] lib/crypto: mpi: Fix integer underflow in mpi_read_raw_from_sgl() Yiming reports an integer underflow in mpi_read_raw_from_sgl() when subtracting "lzeros" from the unsigned "nbytes". For this to happen, the scatterlist "sgl" needs to occupy more bytes than the "nbytes" parameter and the first "nbytes + 1" bytes of the scatterlist must be zero. Under these conditions, the while loop iterating over the scatterlist will count more zeroes than "nbytes", subtract the number of zeroes from "nbytes" and cause the underflow. When commit 2d4d1eea540b ("lib/mpi: Add mpi sgl helpers") originally introduced the bug, it couldn't be triggered because all callers of mpi_read_raw_from_sgl() passed a scatterlist whose length was equal to "nbytes". However since commit 63ba4d67594a ("KEYS: asymmetric: Use new crypto interface without scatterlists"), the underflow can now actually be triggered. When invoking a KEYCTL_PKEY_ENCRYPT system call with a larger "out_len" than "in_len" and filling the "in" buffer with zeroes, crypto_akcipher_sync_prep() will create an all-zero scatterlist used for both the "src" and "dst" member of struct akcipher_request and thereby fulfil the conditions to trigger the bug: sys_keyctl() keyctl_pkey_e_d_s() asymmetric_key_eds_op() software_key_eds_op() crypto_akcipher_sync_encrypt() crypto_akcipher_sync_prep() crypto_akcipher_encrypt() rsa_enc() mpi_read_raw_from_sgl() To the user this will be visible as a DoS as the kernel spins forever, causing soft lockup splats as a side effect. Fix it. Reported-by: Yiming Qian # off-list Fixes: 2d4d1eea540b ("lib/mpi: Add mpi sgl helpers") Signed-off-by: Lukas Wunner Cc: stable@vger.kernel.org # v4.4+ Reviewed-by: Ignat Korchagin Reviewed-by: Jarkko Sakkinen Link: https://lore.kernel.org/r/59eca92ff4f87e2081777f1423a0efaaadcfdb39.1776003111.git.lukas@wunner.de Signed-off-by: Eric Biggers --- lib/crypto/mpi/mpicoder.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/crypto/mpi/mpicoder.c b/lib/crypto/mpi/mpicoder.c index bf716a03c704..9359a58c29ec 100644 --- a/lib/crypto/mpi/mpicoder.c +++ b/lib/crypto/mpi/mpicoder.c @@ -347,7 +347,7 @@ MPI mpi_read_raw_from_sgl(struct scatterlist *sgl, unsigned int nbytes) lzeros = 0; len = 0; while (nbytes > 0) { - while (len && !*buff) { + while (len && !*buff && lzeros < nbytes) { lzeros++; len--; buff++; From 6fa6b5cb60490db2591bb93872b95f72315e5f53 Mon Sep 17 00:00:00 2001 From: Eric Biggers Date: Sat, 18 Apr 2026 12:21:37 -0700 Subject: [PATCH 2/3] docs: kdoc: Expand 'at_least' when creating parameter list sphinx doesn't know that the kernel headers do: #define at_least static Do this replacement before declarations are passed to it. This prevents errors like the following from appearing once the lib/crypto/ kernel-doc is wired up to the sphinx build: linux/Documentation/crypto/libcrypto:128: ./include/crypto/sha2.h:773: WARNING: Error in declarator or parameters Error in declarator or parameters Invalid C declaration: Expected ']' in end of array operator. [error at 59] void sha512_final (struct sha512_ctx *ctx, u8 out[at_least SHA512_DIGEST_SIZE]) Acked-by: Jonathan Corbet Reviewed-by: Ard Biesheuvel Acked-by: Randy Dunlap Tested-by: Randy Dunlap Link: https://lore.kernel.org/r/20260418192138.15556-2-ebiggers@kernel.org Signed-off-by: Eric Biggers --- tools/lib/python/kdoc/kdoc_parser.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py index ca00695b47b3..901e02e3c043 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -571,6 +571,11 @@ class KernelDoc: # Ignore argument attributes arg = KernRe(r'\sPOS0?\s').sub(' ', arg) + # Replace '[at_least ' with '[static '. This allows sphinx to parse + # array parameter declarations like 'char A[at_least 4]', where + # 'at_least' is #defined to 'static' by the kernel headers. + arg = arg.replace('[at_least ', '[static ') + # Strip leading/trailing spaces arg = arg.strip() arg = KernRe(r'\s+').sub(' ', arg, count=1) From e9af4f47d4a036b4be67e4be361f62e05081f7bf Mon Sep 17 00:00:00 2001 From: Eric Biggers Date: Sat, 18 Apr 2026 12:21:38 -0700 Subject: [PATCH 3/3] lib/crypto: docs: Add rst documentation to Documentation/crypto/ Add a documentation file Documentation/crypto/libcrypto.rst which provides a high-level overview of lib/crypto/. Also add several sub-pages which include the kernel-doc for the algorithms that have it. This makes the existing, quite extensive kernel-doc start being included in the HTML and PDF documentation. Note that the intent is very much *not* that everyone has to read these Documentation/ files. The library is intended to be straightforward and use familiar conventions; generally it should be possible to dive right into the kernel-doc. You shouldn't need to read a lot of documentation to just call `sha256()`, for example, or to run the unit tests if you're already familiar with KUnit. (This differs from the traditional crypto API which has a larger barrier to entry.) Nevertheless, this seems worth adding. Hopefully it is useful and makes LWN no longer consider the library to be "meticulously undocumented". Reviewed-by: Ard Biesheuvel Tested-by: Randy Dunlap Reviewed-by: Randy Dunlap Link: https://lore.kernel.org/r/20260418192138.15556-3-ebiggers@kernel.org Signed-off-by: Eric Biggers --- Documentation/crypto/index.rst | 2 +- .../crypto/libcrypto-blockcipher.rst | 19 ++ Documentation/crypto/libcrypto-hash.rst | 86 +++++++++ Documentation/crypto/libcrypto-signature.rst | 11 ++ Documentation/crypto/libcrypto-utils.rst | 6 + Documentation/crypto/libcrypto.rst | 165 ++++++++++++++++++ Documentation/crypto/sha3.rst | 2 + 7 files changed, 290 insertions(+), 1 deletion(-) create mode 100644 Documentation/crypto/libcrypto-blockcipher.rst create mode 100644 Documentation/crypto/libcrypto-hash.rst create mode 100644 Documentation/crypto/libcrypto-signature.rst create mode 100644 Documentation/crypto/libcrypto-utils.rst create mode 100644 Documentation/crypto/libcrypto.rst diff --git a/Documentation/crypto/index.rst b/Documentation/crypto/index.rst index 4ee667c446f9..705f186d662b 100644 --- a/Documentation/crypto/index.rst +++ b/Documentation/crypto/index.rst @@ -13,6 +13,7 @@ for cryptographic use cases, as well as programming examples. :caption: Table of contents :maxdepth: 2 + libcrypto intro api-intro architecture @@ -27,4 +28,3 @@ for cryptographic use cases, as well as programming examples. descore-readme device_drivers/index krb5 - sha3 diff --git a/Documentation/crypto/libcrypto-blockcipher.rst b/Documentation/crypto/libcrypto-blockcipher.rst new file mode 100644 index 000000000000..dd5ce2f8b515 --- /dev/null +++ b/Documentation/crypto/libcrypto-blockcipher.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Block ciphers +============= + +AES +--- + +Support for the AES block cipher. + +.. kernel-doc:: include/crypto/aes.h + +DES +--- + +Support for the DES block cipher. This algorithm is obsolete and is supported +only for backwards compatibility. + +.. kernel-doc:: include/crypto/des.h diff --git a/Documentation/crypto/libcrypto-hash.rst b/Documentation/crypto/libcrypto-hash.rst new file mode 100644 index 000000000000..4248e6fdc952 --- /dev/null +++ b/Documentation/crypto/libcrypto-hash.rst @@ -0,0 +1,86 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Hash functions, MACs, and XOFs +============================== + +AES-CMAC and AES-XCBC-MAC +------------------------- + +Support for the AES-CMAC and AES-XCBC-MAC message authentication codes. + +.. kernel-doc:: include/crypto/aes-cbc-macs.h + +BLAKE2b +------- + +Support for the BLAKE2b cryptographic hash function. + +.. kernel-doc:: include/crypto/blake2b.h + +BLAKE2s +------- + +Support for the BLAKE2s cryptographic hash function. + +.. kernel-doc:: include/crypto/blake2s.h + +GHASH and POLYVAL +----------------- + +Support for the GHASH and POLYVAL universal hash functions. These algorithms +are used only as internal components of other algorithms. + +.. kernel-doc:: include/crypto/gf128hash.h + +MD5 +--- + +Support for the MD5 cryptographic hash function and HMAC-MD5. This algorithm is +obsolete and is supported only for backwards compatibility. + +.. kernel-doc:: include/crypto/md5.h + +NH +-- + +Support for the NH universal hash function. This algorithm is used only as an +internal component of other algorithms. + +.. kernel-doc:: include/crypto/nh.h + +Poly1305 +-------- + +Support for the Poly1305 universal hash function. This algorithm is used only +as an internal component of other algorithms. + +.. kernel-doc:: include/crypto/poly1305.h + +SHA-1 +----- + +Support for the SHA-1 cryptographic hash function and HMAC-SHA1. This algorithm +is obsolete and is supported only for backwards compatibility. + +.. kernel-doc:: include/crypto/sha1.h + +SHA-2 +----- + +Support for the SHA-2 family of cryptographic hash functions, including SHA-224, +SHA-256, SHA-384, and SHA-512. This also includes their corresponding HMACs: +HMAC-SHA224, HMAC-SHA256, HMAC-SHA384, and HMAC-SHA512. + +.. kernel-doc:: include/crypto/sha2.h + +SHA-3 +----- + +The SHA-3 functions are documented in :ref:`sha3`. + +SM3 +--- + +Support for the SM3 cryptographic hash function. + +.. kernel-doc:: include/crypto/sm3.h diff --git a/Documentation/crypto/libcrypto-signature.rst b/Documentation/crypto/libcrypto-signature.rst new file mode 100644 index 000000000000..e80d59fa51b6 --- /dev/null +++ b/Documentation/crypto/libcrypto-signature.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Digital signature algorithms +============================ + +ML-DSA +------ + +Support for the ML-DSA digital signature algorithm. + +.. kernel-doc:: include/crypto/mldsa.h diff --git a/Documentation/crypto/libcrypto-utils.rst b/Documentation/crypto/libcrypto-utils.rst new file mode 100644 index 000000000000..9d833f47ed39 --- /dev/null +++ b/Documentation/crypto/libcrypto-utils.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Utility functions +================= + +.. kernel-doc:: include/crypto/utils.h diff --git a/Documentation/crypto/libcrypto.rst b/Documentation/crypto/libcrypto.rst new file mode 100644 index 000000000000..a1557d45b0e5 --- /dev/null +++ b/Documentation/crypto/libcrypto.rst @@ -0,0 +1,165 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +============== +Crypto library +============== + +``lib/crypto/`` provides faster and easier access to cryptographic algorithms +than the traditional crypto API. + +Each cryptographic algorithm is supported via a set of dedicated functions. +"Crypto agility", where needed, is left to calling code. + +The crypto library functions are intended to be boring and straightforward, and +to follow familiar conventions. Their primary documentation is their (fairly +extensive) kernel-doc. This page just provides some extra high-level context. + +Note that the crypto library isn't entirely new. ``lib/`` has contained some +crypto functions since 2005. Rather, it's just an approach that's been expanded +over time as it's been found to work well. It also largely just matches how the +kernel already does things elsewhere. + +Scope and intended audience +=========================== + +The crypto library documentation is primarily meant for kernel developers who +need to use a particular cryptographic algorithm(s) in kernel code. For +example, "I just need to compute a SHA-256 hash." A secondary audience is +developers working on the crypto algorithm implementations themselves. + +If you're looking for more general information about cryptography, like the +differences between the different crypto algorithms or how to select an +appropriate algorithm, you should refer to external sources which cover that +type of information much more comprehensively. If you need help selecting +algorithms for a new kernel feature that doesn't already have its algorithms +predefined, please reach out to ``linux-crypto@vger.kernel.org`` for advice. + +Code organization +================= + +- ``lib/crypto/*.c``: the crypto algorithm implementations + +- ``lib/crypto/$(SRCARCH)/``: architecture-specific code for crypto algorithms. + It is here rather than somewhere in ``arch/`` partly because this allows + generic and architecture-optimized code to be easily built into a single + loadable module (when the algorithm is set to 'm' in the kconfig). + +- ``lib/crypto/tests/``: KUnit tests for the crypto algorithms + +- ``include/crypto/``: crypto headers, for both the crypto library and the + traditional crypto API + +Generally, there is one kernel module per algorithm. Sometimes related +algorithms are grouped into one module. There is intentionally no common +framework, though there are some utility functions that multiple algorithms use. + +Each algorithm module is controlled by a tristate kconfig symbol +``CRYPTO_LIB_$(ALGORITHM)``. As is the norm for library functions in the +kernel, these are hidden symbols which don't show up in the kconfig menu. +Instead, they are just selected by all the kconfig symbols that need them. + +Many of the algorithms have multiple implementations: a generic implementation +and architecture-optimized implementation(s). Each module initialization +function, or initcall in the built-in case, automatically enables the best +implementation based on the available CPU features. + +Note that the crypto library doesn't use the ``crypto/``, +``arch/$(SRCARCH)/crypto/``, or ``drivers/crypto/`` directories. These +directories are used by the traditional crypto API. When possible, algorithms +in the traditional crypto API are implemented by calls into the library. + +Advantages +========== + +Some of the advantages of the library over the traditional crypto API are: + +- The library functions tend to be much easier to use. For example, a hash + value can be computed using only a single function call. Most of the library + functions always succeed and return void, eliminating the need to write + error-handling code. Most also accept standard virtual addresses, rather than + scatterlists which are difficult and less efficient to work with. + +- The library functions are usually faster, especially for short inputs. They + call the crypto algorithms directly without inefficient indirect calls, memory + allocations, string parsing, lookups in an algorithm registry, and other + unnecessary API overhead. Architecture-optimized code is enabled by default. + +- The library functions use standard link-time dependencies instead of + error-prone dynamic loading by name. There's no need for workarounds such as + forcing algorithms to be built-in or adding module soft dependencies. + +- The library focuses on the approach that works the best on the vast majority + of systems: CPU-based implementations of the crypto algorithms, utilizing + on-CPU acceleration (such as AES instructions) when available. + +- The library uses standard KUnit tests, rather than custom ad-hoc tests. + +- The library tends to have higher assurance implementations of the crypto + algorithms. This is both due to its simpler design and because more of its + code is being regularly tested. + +- The library supports features that don't fit into the rigid framework of the + traditional crypto API, for example interleaved hashing and XOFs. + +When to use it +============== + +In-kernel users should use the library (rather than the traditional crypto API) +whenever possible. Many subsystems have already been converted. It usually +simplifies their code significantly and improves performance. + +Some kernel features allow userspace to provide an arbitrary string that selects +an arbitrary algorithm from the traditional crypto API by name. These features +generally will have to keep using the traditional crypto API for backwards +compatibility. + +Note: new kernel features shouldn't support every algorithm, but rather make a +deliberate choice about what algorithm(s) to support. History has shown that +making a deliberate, thoughtful choice greatly simplifies code maintenance, +reduces the chance for mistakes (such as using an obsolete, insecure, or +inappropriate algorithm), and makes your feature easier to use. + +Testing +======= + +The crypto library uses standard KUnit tests. Like many of the kernel's other +KUnit tests, they are included in the set of tests that is run by +``tools/testing/kunit/kunit.py run --alltests``. + +A ``.kunitconfig`` file is also provided to run just the crypto library tests. +For example, here's how to run them in user-mode Linux: + +.. code-block:: sh + + tools/testing/kunit/kunit.py run --kunitconfig=lib/crypto/ + +Many of the crypto algorithms have architecture-optimized implementations. +Testing those requires building an appropriate kernel and running the tests +either in QEMU or on appropriate hardware. Here's one example with QEMU: + +.. code-block:: sh + + tools/testing/kunit/kunit.py run --kunitconfig=lib/crypto/ --arch=arm64 --make_options LLVM=1 + +Depending on the code being tested, flags may need to be passed to QEMU to +emulate the correct type of hardware for the code to be reached. + +Since correctness is essential in cryptographic code, new architecture-optimized +code is accepted only if it can be tested in QEMU. + +Note: the crypto library also includes FIPS 140 self-tests. These are +lightweight, are designed specifically to meet FIPS 140 requirements, and exist +*only* to meet those requirements. Normal testing done by kernel developers and +integrators should use the much more comprehensive KUnit tests instead. + +API documentation +================= + +.. toctree:: + :maxdepth: 2 + + libcrypto-blockcipher + libcrypto-hash + libcrypto-signature + libcrypto-utils + sha3 diff --git a/Documentation/crypto/sha3.rst b/Documentation/crypto/sha3.rst index 37640f295118..250669c98f6b 100644 --- a/Documentation/crypto/sha3.rst +++ b/Documentation/crypto/sha3.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0-or-later +.. _sha3: + ========================== SHA-3 Algorithm Collection ==========================