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