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