1.. SPDX-License-Identifier: GPL-2.0-or-later 2 3============== 4Crypto library 5============== 6 7The Linux kernel's crypto library (``lib/crypto/``) provides kernel-internal 8users of cryptographic algorithms with faster and easier access to those 9algorithms than the traditional kernel crypto API. 10 11Each cryptographic algorithm is supported via a set of dedicated functions. 12"Crypto agility", where needed, is left to calling code. 13 14The crypto library functions are intended to be boring and straightforward, and 15to follow familiar conventions. Their primary documentation is their (fairly 16extensive) kernel-doc. This page just provides some extra high-level context. 17 18Note that the crypto library isn't entirely new. ``lib/`` has contained some 19crypto functions since 2005. Rather, it's just an approach that's been expanded 20over time as it's been found to work well. It also largely just matches how the 21kernel already does things elsewhere. 22 23Scope and intended audience 24=========================== 25 26The crypto library documentation is primarily meant for kernel developers who 27need to use a particular cryptographic algorithm(s) in kernel code. For 28example, "I just need to compute a SHA-256 hash." A secondary audience is 29developers working on the crypto algorithm implementations themselves. 30 31If you're looking for more general information about cryptography, like the 32differences between the different crypto algorithms or how to select an 33appropriate algorithm, you should refer to external sources which cover that 34type of information much more comprehensively. If you need help selecting 35algorithms for a new kernel feature that doesn't already have its algorithms 36predefined, please reach out to ``linux-crypto@vger.kernel.org`` for advice. 37 38Code organization 39================= 40 41- ``lib/crypto/*.c``: the crypto algorithm implementations 42 43- ``lib/crypto/$(SRCARCH)/``: architecture-specific code for crypto algorithms. 44 It is here rather than somewhere in ``arch/`` partly because this allows 45 generic and architecture-optimized code to be easily built into a single 46 loadable module (when the algorithm is set to 'm' in the kconfig). 47 48- ``lib/crypto/tests/``: KUnit tests for the crypto algorithms 49 50- ``include/crypto/``: crypto headers, for both the crypto library and the 51 traditional crypto API 52 53Generally, there is one kernel module per algorithm. Sometimes related 54algorithms are grouped into one module. There is intentionally no common 55framework, though there are some utility functions that multiple algorithms use. 56 57Each algorithm module is controlled by a tristate kconfig symbol 58``CRYPTO_LIB_$(ALGORITHM)``. As is the norm for library functions in the 59kernel, these are hidden symbols which don't show up in the kconfig menu. 60Instead, they are just selected by all the kconfig symbols that need them. 61 62Many of the algorithms have multiple implementations: a generic implementation 63and architecture-optimized implementation(s). Each module initialization 64function, or initcall in the built-in case, automatically enables the best 65implementation based on the available CPU features. 66 67Note that the crypto library doesn't use the ``crypto/``, 68``arch/$(SRCARCH)/crypto/``, or ``drivers/crypto/`` directories. These 69directories are used by the traditional crypto API. When possible, algorithms 70in the traditional crypto API are implemented by calls into the library. 71 72Advantages 73========== 74 75Some of the advantages of the library over the traditional crypto API are: 76 77- The library functions tend to be much easier to use. For example, a hash 78 value can be computed using only a single function call. Most of the library 79 functions always succeed and return void, eliminating the need to write 80 error-handling code. Most also accept standard virtual addresses, rather than 81 scatterlists which are difficult and less efficient to work with. 82 83- The library functions are usually faster, especially for short inputs. They 84 call the crypto algorithms directly without inefficient indirect calls, memory 85 allocations, string parsing, lookups in an algorithm registry, and other 86 unnecessary API overhead. Architecture-optimized code is enabled by default. 87 88- The library functions use standard link-time dependencies instead of 89 error-prone dynamic loading by name. There's no need for workarounds such as 90 forcing algorithms to be built-in or adding module soft dependencies. 91 92- The library focuses on the approach that works the best on the vast majority 93 of systems: CPU-based implementations of the crypto algorithms, utilizing 94 on-CPU acceleration (such as AES instructions) when available. 95 96- The library uses standard KUnit tests, rather than custom ad-hoc tests. 97 98- The library tends to have higher assurance implementations of the crypto 99 algorithms. This is both due to its simpler design and because more of its 100 code is being regularly tested. 101 102- The library supports features that don't fit into the rigid framework of the 103 traditional crypto API, for example interleaved hashing and XOFs. 104 105When to use it 106============== 107 108In-kernel users should use the library (rather than the traditional crypto API) 109whenever possible. Many subsystems have already been converted. It usually 110simplifies their code significantly and improves performance. 111 112Some kernel features allow userspace to provide an arbitrary string that selects 113an arbitrary algorithm from the traditional crypto API by name. These features 114generally will have to keep using the traditional crypto API for backwards 115compatibility. 116 117Note: new kernel features shouldn't support every algorithm, but rather make a 118deliberate choice about what algorithm(s) to support. History has shown that 119making a deliberate, thoughtful choice greatly simplifies code maintenance, 120reduces the chance for mistakes (such as using an obsolete, insecure, or 121inappropriate algorithm), and makes your feature easier to use. 122 123Testing 124======= 125 126The crypto library uses standard KUnit tests. Like many of the kernel's other 127KUnit tests, they are included in the set of tests that is run by 128``tools/testing/kunit/kunit.py run --alltests``. 129 130A ``.kunitconfig`` file is also provided to run just the crypto library tests. 131For example, here's how to run them in user-mode Linux: 132 133.. code-block:: sh 134 135 tools/testing/kunit/kunit.py run --kunitconfig=lib/crypto/ 136 137Many of the crypto algorithms have architecture-optimized implementations. 138Testing those requires building an appropriate kernel and running the tests 139either in QEMU or on appropriate hardware. Here's one example with QEMU: 140 141.. code-block:: sh 142 143 tools/testing/kunit/kunit.py run --kunitconfig=lib/crypto/ --arch=arm64 --make_options LLVM=1 144 145Depending on the code being tested, flags may need to be passed to QEMU to 146emulate the correct type of hardware for the code to be reached. 147 148Since correctness is essential in cryptographic code, new architecture-optimized 149code is accepted only if it can be tested in QEMU. 150 151Note: the crypto library also includes FIPS 140 self-tests. These are 152lightweight, are designed specifically to meet FIPS 140 requirements, and exist 153*only* to meet those requirements. Normal testing done by kernel developers and 154integrators should use the much more comprehensive KUnit tests instead. 155 156API documentation 157================= 158 159.. toctree:: 160 :maxdepth: 2 161 162 libcrypto-blockcipher 163 libcrypto-hash 164 libcrypto-signature 165 libcrypto-utils 166 sha3 167