Something went wrong. Try again.
(I'm so sorry!) Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
8.3 kB · 182 lines
at master
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183.. SPDX-License-Identifier: GPL-2.0-or-later
==============Crypto library==============
The Linux kernel's crypto library (``lib/crypto/``) provides kernel-internalusers of cryptographic algorithms with faster and easier access to thosealgorithms than the traditional kernel 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, andto follow familiar conventions. Their primary documentation is their (fairlyextensive) kernel-doc. This page just provides some extra high-level context.
Note that the crypto library isn't entirely new. ``lib/`` has contained somecrypto functions since 2005. Rather, it's just an approach that's been expandedover time as it's been found to work well. It also largely just matches how thekernel already does things elsewhere.
Scope and intended audience===========================
The crypto library documentation is primarily meant for kernel developers whoneed to use a particular cryptographic algorithm(s) in kernel code. Forexample, "I just need to compute a SHA-256 hash." A secondary audience isdevelopers working on the crypto algorithm implementations themselves.
If you're looking for more general information about cryptography, like thedifferences between the different crypto algorithms or how to select anappropriate algorithm, you should refer to external sources which cover thattype of information much more comprehensively. If you need help selectingalgorithms for a new kernel feature that doesn't already have its algorithmspredefined, 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 relatedalgorithms are grouped into one module. There is intentionally no commonframework, 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 thekernel, 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 implementationand architecture-optimized implementation(s). Each module initializationfunction, or initcall in the built-in case, automatically enables the bestimplementation based on the available CPU features.
Note that the crypto library doesn't use the ``crypto/``,``arch/$(SRCARCH)/crypto/``, or ``drivers/crypto/`` directories. Thesedirectories are used by the traditional crypto API. When possible, algorithmsin 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 usuallysimplifies their code significantly and improves performance.
Some kernel features allow userspace to provide an arbitrary string that selectsan arbitrary algorithm from the traditional crypto API by name. These featuresgenerally will have to keep using the traditional crypto API for backwardscompatibility.
Note: new kernel features shouldn't support every algorithm, but rather make adeliberate choice about what algorithm(s) to support. History has shown thatmaking a deliberate, thoughtful choice greatly simplifies code maintenance,reduces the chance for mistakes (such as using an obsolete, insecure, orinappropriate algorithm), and makes your feature easier to use.
Testing=======
The crypto library uses standard KUnit tests. Like many of the kernel's otherKUnit tests, they are included in the set of tests that is run by``tools/testing/kunit/kunit.py run --alltests``.
For more information about KUnit, see Documentation/dev-tools/kunit/start.rst.
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 testseither 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 toemulate the correct type of hardware for the code to be reached.
Since correctness is essential in cryptographic code, new architecture-optimizedcode is accepted only if it can be tested in QEMU.
Most of the crypto KUnit tests also include benchmarks. To enable these, enable``CONFIG_CRYPTO_LIB_BENCHMARK=y`` (in addition to the tests themselves). Thebenchmark results are printed to the kernel log when the test runs.
Of course, the crypto KUnit tests can also be run on real hardware. Note thatit is generally still possible to test and benchmark non-default code paths inthis case (for example, the software implementation of AES when the CPU hashardware-accelerated AES), since on many architectures the kernel supportsdisabling CPU features via the kernel command line. For example, on x86,the ``clearcpuid=aes`` kernel command line option disables AES acceleration.
Note: the crypto library also includes FIPS 140 self-tests. These arelightweight, are designed specifically to meet FIPS 140 requirements, and exist*only* to meet those requirements. Normal testing done by kernel developers andintegrators should use the much more comprehensive KUnit tests instead.
API documentation=================
.. toctree:: :maxdepth: 2
libcrypto-auth-encryption libcrypto-blockcipher libcrypto-hash libcrypto-signature libcrypto-unauth-encryption libcrypto-utils libcrypto-zeroization sha3