Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Merge tag 'libcrypto-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/ebiggers/linux
Pull more crypto library updates from Eric Biggers:
"Crypto library fix and documentation update:
- Fix an integer underflow in the mpi library
- Improve the crypto library documentation"
* tag 'libcrypto-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/ebiggers/linux:
lib/crypto: docs: Add rst documentation to Documentation/crypto/
docs: kdoc: Expand 'at_least' when creating parameter list
lib/crypto: mpi: Fix integer underflow in mpi_read_raw_from_sgl()
+296
-2
+1
-1
Documentation/crypto/index.rst
+1
-1
Documentation/crypto/index.rst
+19
Documentation/crypto/libcrypto-blockcipher.rst
+19
Documentation/crypto/libcrypto-blockcipher.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0-or-later
2
+
3
+
Block ciphers
4
+
=============
5
+
6
+
AES
7
+
---
8
+
9
+
Support for the AES block cipher.
10
+
11
+
.. kernel-doc:: include/crypto/aes.h
12
+
13
+
DES
14
+
---
15
+
16
+
Support for the DES block cipher. This algorithm is obsolete and is supported
17
+
only for backwards compatibility.
18
+
19
+
.. kernel-doc:: include/crypto/des.h
+86
Documentation/crypto/libcrypto-hash.rst
+86
Documentation/crypto/libcrypto-hash.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0-or-later
2
+
3
+
Hash functions, MACs, and XOFs
4
+
==============================
5
+
6
+
AES-CMAC and AES-XCBC-MAC
7
+
-------------------------
8
+
9
+
Support for the AES-CMAC and AES-XCBC-MAC message authentication codes.
10
+
11
+
.. kernel-doc:: include/crypto/aes-cbc-macs.h
12
+
13
+
BLAKE2b
14
+
-------
15
+
16
+
Support for the BLAKE2b cryptographic hash function.
17
+
18
+
.. kernel-doc:: include/crypto/blake2b.h
19
+
20
+
BLAKE2s
21
+
-------
22
+
23
+
Support for the BLAKE2s cryptographic hash function.
24
+
25
+
.. kernel-doc:: include/crypto/blake2s.h
26
+
27
+
GHASH and POLYVAL
28
+
-----------------
29
+
30
+
Support for the GHASH and POLYVAL universal hash functions. These algorithms
31
+
are used only as internal components of other algorithms.
32
+
33
+
.. kernel-doc:: include/crypto/gf128hash.h
34
+
35
+
MD5
36
+
---
37
+
38
+
Support for the MD5 cryptographic hash function and HMAC-MD5. This algorithm is
39
+
obsolete and is supported only for backwards compatibility.
40
+
41
+
.. kernel-doc:: include/crypto/md5.h
42
+
43
+
NH
44
+
--
45
+
46
+
Support for the NH universal hash function. This algorithm is used only as an
47
+
internal component of other algorithms.
48
+
49
+
.. kernel-doc:: include/crypto/nh.h
50
+
51
+
Poly1305
52
+
--------
53
+
54
+
Support for the Poly1305 universal hash function. This algorithm is used only
55
+
as an internal component of other algorithms.
56
+
57
+
.. kernel-doc:: include/crypto/poly1305.h
58
+
59
+
SHA-1
60
+
-----
61
+
62
+
Support for the SHA-1 cryptographic hash function and HMAC-SHA1. This algorithm
63
+
is obsolete and is supported only for backwards compatibility.
64
+
65
+
.. kernel-doc:: include/crypto/sha1.h
66
+
67
+
SHA-2
68
+
-----
69
+
70
+
Support for the SHA-2 family of cryptographic hash functions, including SHA-224,
71
+
SHA-256, SHA-384, and SHA-512. This also includes their corresponding HMACs:
72
+
HMAC-SHA224, HMAC-SHA256, HMAC-SHA384, and HMAC-SHA512.
73
+
74
+
.. kernel-doc:: include/crypto/sha2.h
75
+
76
+
SHA-3
77
+
-----
78
+
79
+
The SHA-3 functions are documented in :ref:`sha3`.
80
+
81
+
SM3
82
+
---
83
+
84
+
Support for the SM3 cryptographic hash function.
85
+
86
+
.. kernel-doc:: include/crypto/sm3.h
+11
Documentation/crypto/libcrypto-signature.rst
+11
Documentation/crypto/libcrypto-signature.rst
+6
Documentation/crypto/libcrypto-utils.rst
+6
Documentation/crypto/libcrypto-utils.rst
+165
Documentation/crypto/libcrypto.rst
+165
Documentation/crypto/libcrypto.rst
···
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 ``linux-crypto@vger.kernel.org`` 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
+2
Documentation/crypto/sha3.rst
+2
Documentation/crypto/sha3.rst
+1
-1
lib/crypto/mpi/mpicoder.c
+1
-1
lib/crypto/mpi/mpicoder.c
+5
tools/lib/python/kdoc/kdoc_parser.py
+5
tools/lib/python/kdoc/kdoc_parser.py
···
439
439
# Ignore argument attributes
440
440
arg = KernRe(r'\sPOS0?\s').sub(' ', arg)
441
441
442
+
# Replace '[at_least ' with '[static '. This allows sphinx to parse
443
+
# array parameter declarations like 'char A[at_least 4]', where
444
+
# 'at_least' is #defined to 'static' by the kernel headers.
445
+
arg = arg.replace('[at_least ', '[static ')
446
+
442
447
# Strip leading/trailing spaces
443
448
arg = arg.strip()
444
449
arg = KernRe(r'\s+').sub(' ', arg, count=1)