|
| 1 | +.. SPDX-License-Identifier: GPL-2.0-or-later |
| 2 | +
|
| 3 | +============== |
| 4 | +Crypto library |
| 5 | +============== |
| 6 | + |
| 7 | +``lib/crypto/`` provides faster and easier access to cryptographic algorithms |
| 8 | +than the traditional crypto API. |
| 9 | + |
| 10 | +Each cryptographic algorithm is supported via a set of dedicated functions. |
| 11 | +"Crypto agility", where needed, is left to calling code. |
| 12 | + |
| 13 | +The crypto library functions are intended to be boring and straightforward, and |
| 14 | +to follow familiar conventions. Their primary documentation is their (fairly |
| 15 | +extensive) kernel-doc. This page just provides some extra high-level context. |
| 16 | + |
| 17 | +Note that the crypto library isn't entirely new. ``lib/`` has contained some |
| 18 | +crypto functions since 2005. Rather, it's just an approach that's been expanded |
| 19 | +over time as it's been found to work well. It also largely just matches how the |
| 20 | +kernel already does things elsewhere. |
| 21 | + |
| 22 | +Scope and intended audience |
| 23 | +=========================== |
| 24 | + |
| 25 | +The crypto library documentation is primarily meant for kernel developers who |
| 26 | +need to use a particular cryptographic algorithm(s) in kernel code. For |
| 27 | +example, "I just need to compute a SHA-256 hash." A secondary audience is |
| 28 | +developers working on the crypto algorithm implementations themselves. |
| 29 | + |
| 30 | +If you're looking for more general information about cryptography, like the |
| 31 | +differences between the different crypto algorithms or how to select an |
| 32 | +appropriate algorithm, you should refer to external sources which cover that |
| 33 | +type of information much more comprehensively. If you need help selecting |
| 34 | +algorithms for a new kernel feature that doesn't already have its algorithms |
| 35 | +predefined, please reach out to `` [email protected]`` for advice. |
| 36 | + |
| 37 | +Code 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 | + |
| 52 | +Generally, there is one kernel module per algorithm. Sometimes related |
| 53 | +algorithms are grouped into one module. There is intentionally no common |
| 54 | +framework, though there are some utility functions that multiple algorithms use. |
| 55 | + |
| 56 | +Each algorithm module is controlled by a tristate kconfig symbol |
| 57 | +``CRYPTO_LIB_$(ALGORITHM)``. As is the norm for library functions in the |
| 58 | +kernel, these are hidden symbols which don't show up in the kconfig menu. |
| 59 | +Instead, they are just selected by all the kconfig symbols that need them. |
| 60 | + |
| 61 | +Many of the algorithms have multiple implementations: a generic implementation |
| 62 | +and architecture-optimized implementation(s). Each module initialization |
| 63 | +function, or initcall in the built-in case, automatically enables the best |
| 64 | +implementation based on the available CPU features. |
| 65 | + |
| 66 | +Note that the crypto library doesn't use the ``crypto/``, |
| 67 | +``arch/$(SRCARCH)/crypto/``, or ``drivers/crypto/`` directories. These |
| 68 | +directories are used by the traditional crypto API. When possible, algorithms |
| 69 | +in the traditional crypto API are implemented by calls into the library. |
| 70 | + |
| 71 | +Advantages |
| 72 | +========== |
| 73 | + |
| 74 | +Some 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 | + |
| 104 | +When to use it |
| 105 | +============== |
| 106 | + |
| 107 | +In-kernel users should use the library (rather than the traditional crypto API) |
| 108 | +whenever possible. Many subsystems have already been converted. It usually |
| 109 | +simplifies their code significantly and improves performance. |
| 110 | + |
| 111 | +Some kernel features allow userspace to provide an arbitrary string that selects |
| 112 | +an arbitrary algorithm from the traditional crypto API by name. These features |
| 113 | +generally will have to keep using the traditional crypto API for backwards |
| 114 | +compatibility. |
| 115 | + |
| 116 | +Note: new kernel features shouldn't support every algorithm, but rather make a |
| 117 | +deliberate choice about what algorithm(s) to support. History has shown that |
| 118 | +making a deliberate, thoughtful choice greatly simplifies code maintenance, |
| 119 | +reduces the chance for mistakes (such as using an obsolete, insecure, or |
| 120 | +inappropriate algorithm), and makes your feature easier to use. |
| 121 | + |
| 122 | +Testing |
| 123 | +======= |
| 124 | + |
| 125 | +The crypto library uses standard KUnit tests. Like many of the kernel's other |
| 126 | +KUnit tests, they are included in the set of tests that is run by |
| 127 | +``tools/testing/kunit/kunit.py run --alltests``. |
| 128 | + |
| 129 | +A ``.kunitconfig`` file is also provided to run just the crypto library tests. |
| 130 | +For 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 | +
|
| 136 | +Many of the crypto algorithms have architecture-optimized implementations. |
| 137 | +Testing those requires building an appropriate kernel and running the tests |
| 138 | +either 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 | +
|
| 144 | +Depending on the code being tested, flags may need to be passed to QEMU to |
| 145 | +emulate the correct type of hardware for the code to be reached. |
| 146 | + |
| 147 | +Since correctness is essential in cryptographic code, new architecture-optimized |
| 148 | +code is accepted only if it can be tested in QEMU. |
| 149 | + |
| 150 | +Note: the crypto library also includes FIPS 140 self-tests. These are |
| 151 | +lightweight, are designed specifically to meet FIPS 140 requirements, and exist |
| 152 | +*only* to meet those requirements. Normal testing done by kernel developers and |
| 153 | +integrators should use the much more comprehensive KUnit tests instead. |
| 154 | + |
| 155 | +API documentation |
| 156 | +================= |
| 157 | + |
| 158 | +.. toctree:: |
| 159 | + :maxdepth: 2 |
| 160 | + |
| 161 | + libcrypto-blockcipher |
| 162 | + libcrypto-hash |
| 163 | + libcrypto-signature |
| 164 | + libcrypto-utils |
| 165 | + sha3 |
0 commit comments