tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Add Documentation/module-signing.txt file
This patch adds the Documentation/module-signing.txt file that is
currently missing from the Documentation directory. The init/Kconfig
file references the Documentation/module-signing.txt file to explain
how kernel module signing works. This patch supplies this documentation.
The initial version of this patch provided old documentation
that was a mixture of the old RHEL style GPG signing.
Version 1: Updated the documentation to described the current
implementation using x509 certificate signing.
Version 2: fixes grammar/spelling mistakes and removes
trailing whitespaces.
Version 3, fixes grammar/spelling mistakes.
Version 4: Include updates from David Howells and fixes for
spelling mistakes.
Signed-off-by: James Solner <solner@alcatel-lucent.com>
Signed-off-by: David Howells <dhowells@redhat.com>
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
authored by
James Solner
and committed by
Rusty Russell
160e01ac
af91706d
+240
+240
Documentation/module-signing.txt
+240
Documentation/module-signing.txt
···
1
+
==============================
2
+
KERNEL MODULE SIGNING FACILITY
3
+
==============================
4
+
5
+
CONTENTS
6
+
7
+
- Overview.
8
+
- Configuring module signing.
9
+
- Generating signing keys.
10
+
- Public keys in the kernel.
11
+
- Manually signing modules.
12
+
- Signed modules and stripping.
13
+
- Loading signed modules.
14
+
- Non-valid signatures and unsigned modules.
15
+
- Administering/protecting the private key.
16
+
17
+
18
+
========
19
+
OVERVIEW
20
+
========
21
+
22
+
The kernel module signing facility cryptographically signs modules during
23
+
installation and then checks the signature upon loading the module. This
24
+
allows increased kernel security by disallowing the loading of unsigned modules
25
+
or modules signed with an invalid key. Module signing increases security by
26
+
making it harder to load a malicious module into the kernel. The module
27
+
signature checking is done by the kernel so that it is not necessary to have
28
+
trusted userspace bits.
29
+
30
+
This facility uses X.509 ITU-T standard certificates to encode the public keys
31
+
involved. The signatures are not themselves encoded in any industrial standard
32
+
type. The facility currently only supports the RSA public key encryption
33
+
standard (though it is pluggable and permits others to be used). The possible
34
+
hash algorithms that can be used are SHA-1, SHA-224, SHA-256, SHA-384, and
35
+
SHA-512 (the algorithm is selected by data in the signature).
36
+
37
+
38
+
==========================
39
+
CONFIGURING MODULE SIGNING
40
+
==========================
41
+
42
+
The module signing facility is enabled by going to the "Enable Loadable Module
43
+
Support" section of the kernel configuration and turning on
44
+
45
+
CONFIG_MODULE_SIG "Module signature verification"
46
+
47
+
This has a number of options available:
48
+
49
+
(1) "Require modules to be validly signed" (CONFIG_MODULE_SIG_FORCE)
50
+
51
+
This specifies how the kernel should deal with a module that has a
52
+
signature for which the key is not known or a module that is unsigned.
53
+
54
+
If this is off (ie. "permissive"), then modules for which the key is not
55
+
available and modules that are unsigned are permitted, but the kernel will
56
+
be marked as being tainted.
57
+
58
+
If this is on (ie. "restrictive"), only modules that have a valid
59
+
signature that can be verified by a public key in the kernel's possession
60
+
will be loaded. All other modules will generate an error.
61
+
62
+
Irrespective of the setting here, if the module has a signature block that
63
+
cannot be parsed, it will be rejected out of hand.
64
+
65
+
66
+
(2) "Automatically sign all modules" (CONFIG_MODULE_SIG_ALL)
67
+
68
+
If this is on then modules will be automatically signed during the
69
+
modules_install phase of a build. If this is off, then the modules must
70
+
be signed manually using:
71
+
72
+
scripts/sign-file
73
+
74
+
75
+
(3) "Which hash algorithm should modules be signed with?"
76
+
77
+
This presents a choice of which hash algorithm the installation phase will
78
+
sign the modules with:
79
+
80
+
CONFIG_SIG_SHA1 "Sign modules with SHA-1"
81
+
CONFIG_SIG_SHA224 "Sign modules with SHA-224"
82
+
CONFIG_SIG_SHA256 "Sign modules with SHA-256"
83
+
CONFIG_SIG_SHA384 "Sign modules with SHA-384"
84
+
CONFIG_SIG_SHA512 "Sign modules with SHA-512"
85
+
86
+
The algorithm selected here will also be built into the kernel (rather
87
+
than being a module) so that modules signed with that algorithm can have
88
+
their signatures checked without causing a dependency loop.
89
+
90
+
91
+
=======================
92
+
GENERATING SIGNING KEYS
93
+
=======================
94
+
95
+
Cryptographic keypairs are required to generate and check signatures. A
96
+
private key is used to generate a signature and the corresponding public key is
97
+
used to check it. The private key is only needed during the build, after which
98
+
it can be deleted or stored securely. The public key gets built into the
99
+
kernel so that it can be used to check the signatures as the modules are
100
+
loaded.
101
+
102
+
Under normal conditions, the kernel build will automatically generate a new
103
+
keypair using openssl if one does not exist in the files:
104
+
105
+
signing_key.priv
106
+
signing_key.x509
107
+
108
+
during the building of vmlinux (the public part of the key needs to be built
109
+
into vmlinux) using parameters in the:
110
+
111
+
x509.genkey
112
+
113
+
file (which is also generated if it does not already exist).
114
+
115
+
It is strongly recommended that you provide your own x509.genkey file.
116
+
117
+
Most notably, in the x509.genkey file, the req_distinguished_name section
118
+
should be altered from the default:
119
+
120
+
[ req_distinguished_name ]
121
+
O = Magrathea
122
+
CN = Glacier signing key
123
+
emailAddress = slartibartfast@magrathea.h2g2
124
+
125
+
The generated RSA key size can also be set with:
126
+
127
+
[ req ]
128
+
default_bits = 4096
129
+
130
+
131
+
It is also possible to manually generate the key private/public files using the
132
+
x509.genkey key generation configuration file in the root node of the Linux
133
+
kernel sources tree and the openssl command. The following is an example to
134
+
generate the public/private key files:
135
+
136
+
openssl req -new -nodes -utf8 -sha256 -days 36500 -batch -x509 \
137
+
-config x509.genkey -outform DER -out signing_key.x509 \
138
+
-keyout signing_key.priv
139
+
140
+
141
+
=========================
142
+
PUBLIC KEYS IN THE KERNEL
143
+
=========================
144
+
145
+
The kernel contains a ring of public keys that can be viewed by root. They're
146
+
in a keyring called ".system_keyring" that can be seen by:
147
+
148
+
[root@deneb ~]# cat /proc/keys
149
+
...
150
+
223c7853 I------ 1 perm 1f030000 0 0 keyring .system_keyring: 1
151
+
302d2d52 I------ 1 perm 1f010000 0 0 asymmetri Fedora kernel signing key: d69a84e6bce3d216b979e9505b3e3ef9a7118079: X509.RSA a7118079 []
152
+
...
153
+
154
+
Beyond the public key generated specifically for module signing, any file
155
+
placed in the kernel source root directory or the kernel build root directory
156
+
whose name is suffixed with ".x509" will be assumed to be an X.509 public key
157
+
and will be added to the keyring.
158
+
159
+
Further, the architecture code may take public keys from a hardware store and
160
+
add those in also (e.g. from the UEFI key database).
161
+
162
+
Finally, it is possible to add additional public keys by doing:
163
+
164
+
keyctl padd asymmetric "" [.system_keyring-ID] <[key-file]
165
+
166
+
e.g.:
167
+
168
+
keyctl padd asymmetric "" 0x223c7853 <my_public_key.x509
169
+
170
+
Note, however, that the kernel will only permit keys to be added to
171
+
.system_keyring _if_ the new key's X.509 wrapper is validly signed by a key
172
+
that is already resident in the .system_keyring at the time the key was added.
173
+
174
+
175
+
=========================
176
+
MANUALLY SIGNING MODULES
177
+
=========================
178
+
179
+
To manually sign a module, use the scripts/sign-file tool available in
180
+
the Linux kernel source tree. The script requires 4 arguments:
181
+
182
+
1. The hash algorithm (e.g., sha512)
183
+
2. The private key filename
184
+
3. The public key filename
185
+
4. The kernel module to be signed
186
+
187
+
The following is an example to sign a kernel module:
188
+
189
+
scripts/sign-file sha512 signkey.priv \
190
+
signkey.x509 module.ko
191
+
192
+
The hash algorithm used does not have to match the one configured, but if it
193
+
doesn't, you should make sure that hash algorithm is either built into the
194
+
kernel or can be loaded without requiring itself.
195
+
196
+
197
+
============================
198
+
SIGNED MODULES AND STRIPPING
199
+
============================
200
+
201
+
A signed module has a digital signature simply appended at the end. The string
202
+
"~Module signature appended~." at the end of the module's file confirms that a
203
+
signature is present but it does not confirm that the signature is valid!
204
+
205
+
Signed modules are BRITTLE as the signature is outside of the defined ELF
206
+
container. Thus they MAY NOT be stripped once the signature is computed and
207
+
attached. Note the entire module is the signed payload, including any and all
208
+
debug information present at the time of signing.
209
+
210
+
211
+
======================
212
+
LOADING SIGNED MODULES
213
+
======================
214
+
215
+
Modules are loaded with insmod, modprobe, init_module() or finit_module(),
216
+
exactly as for unsigned modules as no processing is done in userspace. The
217
+
signature checking is all done within the kernel.
218
+
219
+
220
+
=========================================
221
+
NON-VALID SIGNATURES AND UNSIGNED MODULES
222
+
=========================================
223
+
224
+
If CONFIG_MODULE_SIG_FORCE is enabled or enforcemodulesig=1 is supplied on
225
+
the kernel command line, the kernel will only load validly signed modules
226
+
for which it has a public key. Otherwise, it will also load modules that are
227
+
unsigned. Any module for which the kernel has a key, but which proves to have
228
+
a signature mismatch will not be permitted to load.
229
+
230
+
Any module that has an unparseable signature will be rejected.
231
+
232
+
233
+
=========================================
234
+
ADMINISTERING/PROTECTING THE PRIVATE KEY
235
+
=========================================
236
+
237
+
Since the private key is used to sign modules, viruses and malware could use
238
+
the private key to sign modules and compromise the operating system. The
239
+
private key must be either destroyed or moved to a secure location and not kept
240
+
in the root node of the kernel source tree.