1 Kernel module signing facility
2 ------------------------------
3
4 .. CONTENTS
5 ..
6 .. - Overview.
7 .. - Configuring module signing.
8 .. - Generating signing keys.
9 .. - Public keys in the kernel.
10 .. - Manually signing modules.
11 .. - Signed modules and stripping.
12 .. - Loading signed modules.
13 .. - Non-valid signatures and unsigned modules
14 .. - Administering/protecting the private key.
15
16
17 ========
18 Overview
19 ========
20
21 The kernel module signing facility cryptograph
22 installation and then checks the signature upo
23 allows increased kernel security by disallowin
24 or modules signed with an invalid key. Module
25 making it harder to load a malicious module in
26 signature checking is done by the kernel so th
27 trusted userspace bits.
28
29 This facility uses X.509 ITU-T standard certif
30 involved. The signatures are not themselves e
31 type. The built-in facility currently only su
32 public key signing standard (though it is plug
33 used). The possible hash algorithms that can
34 sizes 256, 384, and 512 (the algorithm is sele
35
36
37 ==========================
38 Configuring module signing
39 ==========================
40
41 The module signing facility is enabled by goin
42 :menuselection:`Enable Loadable Module Support
43 the kernel configuration and turning on::
44
45 CONFIG_MODULE_SIG "Module signat
46
47 This has a number of options available:
48
49 (1) :menuselection:`Require modules to be val
50 (``CONFIG_MODULE_SIG_FORCE``)
51
52 This specifies how the kernel should deal
53 signature for which the key is not known
54
55 If this is off (ie. "permissive"), then m
56 available and modules that are unsigned a
57 be marked as being tainted, and the conce
58 tainted, shown with the character 'E'.
59
60 If this is on (ie. "restrictive"), only m
61 signature that can be verified by a publi
62 will be loaded. All other modules will g
63
64 Irrespective of the setting here, if the
65 cannot be parsed, it will be rejected out
66
67
68 (2) :menuselection:`Automatically sign all mo
69 (``CONFIG_MODULE_SIG_ALL``)
70
71 If this is on then modules will be automa
72 modules_install phase of a build. If thi
73 be signed manually using::
74
75 scripts/sign-file
76
77
78 (3) :menuselection:`Which hash algorithm shou
79
80 This presents a choice of which hash algo
81 sign the modules with:
82
83 =============================== ======
84 ``CONFIG_MODULE_SIG_SHA256`` :menus
85 ``CONFIG_MODULE_SIG_SHA384`` :menus
86 ``CONFIG_MODULE_SIG_SHA512`` :menus
87 ``CONFIG_MODULE_SIG_SHA3_256`` :menus
88 ``CONFIG_MODULE_SIG_SHA3_384`` :menus
89 ``CONFIG_MODULE_SIG_SHA3_512`` :menus
90 =============================== ======
91
92 The algorithm selected here will also be
93 than being a module) so that modules sign
94 their signatures checked without causing
95
96
97 (4) :menuselection:`File name or PKCS#11 URI
98 (``CONFIG_MODULE_SIG_KEY``)
99
100 Setting this option to something other th
101 ``certs/signing_key.pem`` will disable th
102 and allow the kernel modules to be signed
103 The string provided should identify a fil
104 and its corresponding X.509 certificate i
105 the OpenSSL ENGINE_pkcs11 is functional â
106 RFC7512. In the latter case, the PKCS#11
107 certificate and a private key.
108
109 If the PEM file containing the private ke
110 PKCS#11 token requires a PIN, this can be
111 means of the ``KBUILD_SIGN_PIN`` variable
112
113
114 (5) :menuselection:`Additional X.509 keys for
115 (``CONFIG_SYSTEM_TRUSTED_KEYS``)
116
117 This option can be set to the filename of
118 additional certificates which will be inc
119 default.
120
121 Note that enabling module signing adds a depen
122 packages to the kernel build processes for the
123
124
125 =======================
126 Generating signing keys
127 =======================
128
129 Cryptographic keypairs are required to generat
130 private key is used to generate a signature an
131 used to check it. The private key is only nee
132 it can be deleted or stored securely. The pub
133 kernel so that it can be used to check the sig
134 loaded.
135
136 Under normal conditions, when ``CONFIG_MODULE_
137 default, the kernel build will automatically g
138 openssl if one does not exist in the file::
139
140 certs/signing_key.pem
141
142 during the building of vmlinux (the public par
143 into vmlinux) using parameters in the::
144
145 certs/x509.genkey
146
147 file (which is also generated if it does not a
148
149 One can select between RSA (``MODULE_SIG_KEY_T
150 (``MODULE_SIG_KEY_TYPE_ECDSA``) to generate ei
151 P-384 keypair.
152
153 It is strongly recommended that you provide yo
154
155 Most notably, in the x509.genkey file, the req
156 should be altered from the default::
157
158 [ req_distinguished_name ]
159 #O = Unspecified company
160 CN = Build time autogenerated kernel k
161 #emailAddress = unspecified.user@unspe
162
163 The generated RSA key size can also be set wit
164
165 [ req ]
166 default_bits = 4096
167
168
169 It is also possible to manually generate the k
170 x509.genkey key generation configuration file
171 kernel sources tree and the openssl command.
172 generate the public/private key files::
173
174 openssl req -new -nodes -utf8 -sha256
175 -config x509.genkey -outform PEM -o
176 -keyout kernel_key.pem
177
178 The full pathname for the resulting kernel_key
179 in the ``CONFIG_MODULE_SIG_KEY`` option, and t
180 be used instead of an autogenerated keypair.
181
182
183 =========================
184 Public keys in the kernel
185 =========================
186
187 The kernel contains a ring of public keys that
188 in a keyring called ".builtin_trusted_keys" th
189
190 [root@deneb ~]# cat /proc/keys
191 ...
192 223c7853 I------ 1 perm 1f030000
193 302d2d52 I------ 1 perm 1f010000
194 ...
195
196 Beyond the public key generated specifically f
197 trusted certificates can be provided in a PEM-
198 ``CONFIG_SYSTEM_TRUSTED_KEYS`` configuration o
199
200 Further, the architecture code may take public
201 add those in also (e.g. from the UEFI key data
202
203 Finally, it is possible to add additional publ
204
205 keyctl padd asymmetric "" [.builtin_tr
206
207 e.g.::
208
209 keyctl padd asymmetric "" 0x223c7853 <
210
211 Note, however, that the kernel will only permi
212 ``.builtin_trusted_keys`` **if** the new key's
213 that is already resident in the ``.builtin_tru
214
215
216 ========================
217 Manually signing modules
218 ========================
219
220 To manually sign a module, use the scripts/sig
221 the Linux kernel source tree. The script requ
222
223 1. The hash algorithm (e.g., sha256)
224 2. The private key filename or PKCS#1
225 3. The public key filename
226 4. The kernel module to be signed
227
228 The following is an example to sign a kernel m
229
230 scripts/sign-file sha512 kernel-signke
231 kernel-signkey.x509 module.ko
232
233 The hash algorithm used does not have to match
234 doesn't, you should make sure that hash algori
235 kernel or can be loaded without requiring itse
236
237 If the private key requires a passphrase or PI
238 $KBUILD_SIGN_PIN environment variable.
239
240
241 ============================
242 Signed modules and stripping
243 ============================
244
245 A signed module has a digital signature simply
246 ``~Module signature appended~.`` at the end of
247 signature is present but it does not confirm t
248
249 Signed modules are BRITTLE as the signature is
250 container. Thus they MAY NOT be stripped once
251 attached. Note the entire module is the signe
252 debug information present at the time of signi
253
254
255 ======================
256 Loading signed modules
257 ======================
258
259 Modules are loaded with insmod, modprobe, ``in
260 ``finit_module()``, exactly as for unsigned mo
261 done in userspace. The signature checking is
262
263
264 =========================================
265 Non-valid signatures and unsigned modules
266 =========================================
267
268 If ``CONFIG_MODULE_SIG_FORCE`` is enabled or m
269 the kernel command line, the kernel will only
270 for which it has a public key. Otherwise, it
271 unsigned. Any module for which the kernel ha
272 a signature mismatch will not be permitted to
273
274 Any module that has an unparsable signature wi
275
276
277 =========================================
278 Administering/protecting the private key
279 =========================================
280
281 Since the private key is used to sign modules,
282 the private key to sign modules and compromise
283 private key must be either destroyed or moved
284 in the root node of the kernel source tree.
285
286 If you use the same private key to sign module
287 configurations, you must ensure that the modul
288 sufficient to prevent loading a module into a
289 set ``CONFIG_MODVERSIONS=y`` or ensure that ea
290 kernel release string by changing ``EXTRAVERSI
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.