Commit | Line | Data |
---|---|---|
94e980cc MCC |
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. | |
3cafea30 JS |
15 | |
16 | ||
17 | ======== | |
94e980cc | 18 | Overview |
3cafea30 JS |
19 | ======== |
20 | ||
21 | The kernel module signing facility cryptographically signs modules during | |
22 | installation and then checks the signature upon loading the module. This | |
23 | allows increased kernel security by disallowing the loading of unsigned modules | |
24 | or modules signed with an invalid key. Module signing increases security by | |
25 | making it harder to load a malicious module into the kernel. The module | |
26 | signature checking is done by the kernel so that it is not necessary to have | |
27 | trusted userspace bits. | |
28 | ||
29 | This facility uses X.509 ITU-T standard certificates to encode the public keys | |
30 | involved. The signatures are not themselves encoded in any industrial standard | |
31 | type. The facility currently only supports the RSA public key encryption | |
32 | standard (though it is pluggable and permits others to be used). The possible | |
33 | hash algorithms that can be used are SHA-1, SHA-224, SHA-256, SHA-384, and | |
34 | SHA-512 (the algorithm is selected by data in the signature). | |
35 | ||
36 | ||
37 | ========================== | |
94e980cc | 38 | Configuring module signing |
3cafea30 JS |
39 | ========================== |
40 | ||
94e980cc MCC |
41 | The module signing facility is enabled by going to the |
42 | :menuselection:`Enable Loadable Module Support` section of | |
43 | the kernel configuration and turning on:: | |
3cafea30 JS |
44 | |
45 | CONFIG_MODULE_SIG "Module signature verification" | |
46 | ||
47 | This has a number of options available: | |
48 | ||
94e980cc MCC |
49 | (1) :menuselection:`Require modules to be validly signed` |
50 | (``CONFIG_MODULE_SIG_FORCE``) | |
3cafea30 JS |
51 | |
52 | This specifies how the kernel should deal with a module that has a | |
53 | signature for which the key is not known or a module that is unsigned. | |
54 | ||
55 | If this is off (ie. "permissive"), then modules for which the key is not | |
56 | available and modules that are unsigned are permitted, but the kernel will | |
66cc69e3 | 57 | be marked as being tainted, and the concerned modules will be marked as |
57673c2b | 58 | tainted, shown with the character 'E'. |
3cafea30 JS |
59 | |
60 | If this is on (ie. "restrictive"), only modules that have a valid | |
61 | signature that can be verified by a public key in the kernel's possession | |
62 | will be loaded. All other modules will generate an error. | |
63 | ||
64 | Irrespective of the setting here, if the module has a signature block that | |
65 | cannot be parsed, it will be rejected out of hand. | |
66 | ||
67 | ||
94e980cc MCC |
68 | (2) :menuselection:`Automatically sign all modules` |
69 | (``CONFIG_MODULE_SIG_ALL``) | |
3cafea30 JS |
70 | |
71 | If this is on then modules will be automatically signed during the | |
72 | modules_install phase of a build. If this is off, then the modules must | |
94e980cc | 73 | be signed manually using:: |
3cafea30 JS |
74 | |
75 | scripts/sign-file | |
76 | ||
77 | ||
94e980cc | 78 | (3) :menuselection:`Which hash algorithm should modules be signed with?` |
3cafea30 JS |
79 | |
80 | This presents a choice of which hash algorithm the installation phase will | |
81 | sign the modules with: | |
82 | ||
94e980cc MCC |
83 | =============================== ========================================== |
84 | ``CONFIG_MODULE_SIG_SHA1`` :menuselection:`Sign modules with SHA-1` | |
85 | ``CONFIG_MODULE_SIG_SHA224`` :menuselection:`Sign modules with SHA-224` | |
86 | ``CONFIG_MODULE_SIG_SHA256`` :menuselection:`Sign modules with SHA-256` | |
87 | ``CONFIG_MODULE_SIG_SHA384`` :menuselection:`Sign modules with SHA-384` | |
88 | ``CONFIG_MODULE_SIG_SHA512`` :menuselection:`Sign modules with SHA-512` | |
89 | =============================== ========================================== | |
3cafea30 JS |
90 | |
91 | The algorithm selected here will also be built into the kernel (rather | |
92 | than being a module) so that modules signed with that algorithm can have | |
93 | their signatures checked without causing a dependency loop. | |
94 | ||
99d27b1b | 95 | |
94e980cc MCC |
96 | (4) :menuselection:`File name or PKCS#11 URI of module signing key` |
97 | (``CONFIG_MODULE_SIG_KEY``) | |
19e91b69 DW |
98 | |
99 | Setting this option to something other than its default of | |
94e980cc | 100 | ``certs/signing_key.pem`` will disable the autogeneration of signing keys |
cfc411e7 DH |
101 | and allow the kernel modules to be signed with a key of your choosing. |
102 | The string provided should identify a file containing both a private key | |
103 | and its corresponding X.509 certificate in PEM form, or — on systems where | |
104 | the OpenSSL ENGINE_pkcs11 is functional — a PKCS#11 URI as defined by | |
105 | RFC7512. In the latter case, the PKCS#11 URI should reference both a | |
106 | certificate and a private key. | |
19e91b69 DW |
107 | |
108 | If the PEM file containing the private key is encrypted, or if the | |
751d5b27 | 109 | PKCS#11 token requires a PIN, this can be provided at build time by |
94e980cc | 110 | means of the ``KBUILD_SIGN_PIN`` variable. |
19e91b69 | 111 | |
3cafea30 | 112 | |
94e980cc MCC |
113 | (5) :menuselection:`Additional X.509 keys for default system keyring` |
114 | (``CONFIG_SYSTEM_TRUSTED_KEYS``) | |
99d27b1b DW |
115 | |
116 | This option can be set to the filename of a PEM-encoded file containing | |
117 | additional certificates which will be included in the system keyring by | |
118 | default. | |
119 | ||
228c37ff DH |
120 | Note that enabling module signing adds a dependency on the OpenSSL devel |
121 | packages to the kernel build processes for the tool that does the signing. | |
122 | ||
99d27b1b | 123 | |
3cafea30 | 124 | ======================= |
94e980cc | 125 | Generating signing keys |
3cafea30 JS |
126 | ======================= |
127 | ||
128 | Cryptographic keypairs are required to generate and check signatures. A | |
129 | private key is used to generate a signature and the corresponding public key is | |
130 | used to check it. The private key is only needed during the build, after which | |
131 | it can be deleted or stored securely. The public key gets built into the | |
132 | kernel so that it can be used to check the signatures as the modules are | |
133 | loaded. | |
134 | ||
94e980cc | 135 | Under normal conditions, when ``CONFIG_MODULE_SIG_KEY`` is unchanged from its |
fb117949 | 136 | default, the kernel build will automatically generate a new keypair using |
94e980cc | 137 | openssl if one does not exist in the file:: |
3cafea30 | 138 | |
cfc411e7 | 139 | certs/signing_key.pem |
3cafea30 JS |
140 | |
141 | during the building of vmlinux (the public part of the key needs to be built | |
94e980cc | 142 | into vmlinux) using parameters in the:: |
3cafea30 | 143 | |
cfc411e7 | 144 | certs/x509.genkey |
3cafea30 JS |
145 | |
146 | file (which is also generated if it does not already exist). | |
147 | ||
148 | It is strongly recommended that you provide your own x509.genkey file. | |
149 | ||
150 | Most notably, in the x509.genkey file, the req_distinguished_name section | |
94e980cc | 151 | should be altered from the default:: |
3cafea30 JS |
152 | |
153 | [ req_distinguished_name ] | |
9c4249c8 DH |
154 | #O = Unspecified company |
155 | CN = Build time autogenerated kernel key | |
156 | #emailAddress = unspecified.user@unspecified.company | |
3cafea30 | 157 | |
94e980cc | 158 | The generated RSA key size can also be set with:: |
3cafea30 JS |
159 | |
160 | [ req ] | |
161 | default_bits = 4096 | |
162 | ||
163 | ||
164 | It is also possible to manually generate the key private/public files using the | |
165 | x509.genkey key generation configuration file in the root node of the Linux | |
166 | kernel sources tree and the openssl command. The following is an example to | |
94e980cc | 167 | generate the public/private key files:: |
3cafea30 JS |
168 | |
169 | openssl req -new -nodes -utf8 -sha256 -days 36500 -batch -x509 \ | |
19e91b69 DW |
170 | -config x509.genkey -outform PEM -out kernel_key.pem \ |
171 | -keyout kernel_key.pem | |
172 | ||
173 | The full pathname for the resulting kernel_key.pem file can then be specified | |
94e980cc | 174 | in the ``CONFIG_MODULE_SIG_KEY`` option, and the certificate and key therein will |
19e91b69 | 175 | be used instead of an autogenerated keypair. |
3cafea30 JS |
176 | |
177 | ||
178 | ========================= | |
94e980cc | 179 | Public keys in the kernel |
3cafea30 JS |
180 | ========================= |
181 | ||
182 | The kernel contains a ring of public keys that can be viewed by root. They're | |
dddc7231 | 183 | in a keyring called ".builtin_trusted_keys" that can be seen by:: |
3cafea30 JS |
184 | |
185 | [root@deneb ~]# cat /proc/keys | |
186 | ... | |
dddc7231 | 187 | 223c7853 I------ 1 perm 1f030000 0 0 keyring .builtin_trusted_keys: 1 |
3cafea30 JS |
188 | 302d2d52 I------ 1 perm 1f010000 0 0 asymmetri Fedora kernel signing key: d69a84e6bce3d216b979e9505b3e3ef9a7118079: X509.RSA a7118079 [] |
189 | ... | |
190 | ||
99d27b1b DW |
191 | Beyond the public key generated specifically for module signing, additional |
192 | trusted certificates can be provided in a PEM-encoded file referenced by the | |
94e980cc | 193 | ``CONFIG_SYSTEM_TRUSTED_KEYS`` configuration option. |
3cafea30 JS |
194 | |
195 | Further, the architecture code may take public keys from a hardware store and | |
196 | add those in also (e.g. from the UEFI key database). | |
197 | ||
94e980cc | 198 | Finally, it is possible to add additional public keys by doing:: |
3cafea30 | 199 | |
dddc7231 | 200 | keyctl padd asymmetric "" [.builtin_trusted_keys-ID] <[key-file] |
3cafea30 | 201 | |
94e980cc | 202 | e.g.:: |
3cafea30 JS |
203 | |
204 | keyctl padd asymmetric "" 0x223c7853 <my_public_key.x509 | |
205 | ||
206 | Note, however, that the kernel will only permit keys to be added to | |
29b26ae4 PH |
207 | ``.builtin_trusted_keys`` **if** the new key's X.509 wrapper is validly signed by a key |
208 | that is already resident in the ``.builtin_trusted_keys`` at the time the key was added. | |
3cafea30 JS |
209 | |
210 | ||
94e980cc MCC |
211 | ======================== |
212 | Manually signing modules | |
213 | ======================== | |
3cafea30 JS |
214 | |
215 | To manually sign a module, use the scripts/sign-file tool available in | |
216 | the Linux kernel source tree. The script requires 4 arguments: | |
217 | ||
218 | 1. The hash algorithm (e.g., sha256) | |
19e91b69 | 219 | 2. The private key filename or PKCS#11 URI |
3cafea30 JS |
220 | 3. The public key filename |
221 | 4. The kernel module to be signed | |
222 | ||
94e980cc | 223 | The following is an example to sign a kernel module:: |
3cafea30 JS |
224 | |
225 | scripts/sign-file sha512 kernel-signkey.priv \ | |
226 | kernel-signkey.x509 module.ko | |
227 | ||
228 | The hash algorithm used does not have to match the one configured, but if it | |
229 | doesn't, you should make sure that hash algorithm is either built into the | |
230 | kernel or can be loaded without requiring itself. | |
231 | ||
af1eb291 DW |
232 | If the private key requires a passphrase or PIN, it can be provided in the |
233 | $KBUILD_SIGN_PIN environment variable. | |
234 | ||
3cafea30 JS |
235 | |
236 | ============================ | |
94e980cc | 237 | Signed modules and stripping |
3cafea30 JS |
238 | ============================ |
239 | ||
240 | A signed module has a digital signature simply appended at the end. The string | |
94e980cc | 241 | ``~Module signature appended~.`` at the end of the module's file confirms that a |
3cafea30 JS |
242 | signature is present but it does not confirm that the signature is valid! |
243 | ||
244 | Signed modules are BRITTLE as the signature is outside of the defined ELF | |
245 | container. Thus they MAY NOT be stripped once the signature is computed and | |
246 | attached. Note the entire module is the signed payload, including any and all | |
247 | debug information present at the time of signing. | |
248 | ||
249 | ||
250 | ====================== | |
94e980cc | 251 | Loading signed modules |
3cafea30 JS |
252 | ====================== |
253 | ||
94e980cc MCC |
254 | Modules are loaded with insmod, modprobe, ``init_module()`` or |
255 | ``finit_module()``, exactly as for unsigned modules as no processing is | |
256 | done in userspace. The signature checking is all done within the kernel. | |
3cafea30 JS |
257 | |
258 | ||
259 | ========================================= | |
94e980cc | 260 | Non-valid signatures and unsigned modules |
3cafea30 JS |
261 | ========================================= |
262 | ||
94e980cc | 263 | If ``CONFIG_MODULE_SIG_FORCE`` is enabled or module.sig_enforce=1 is supplied on |
3cafea30 JS |
264 | the kernel command line, the kernel will only load validly signed modules |
265 | for which it has a public key. Otherwise, it will also load modules that are | |
266 | unsigned. Any module for which the kernel has a key, but which proves to have | |
267 | a signature mismatch will not be permitted to load. | |
268 | ||
269 | Any module that has an unparseable signature will be rejected. | |
270 | ||
271 | ||
272 | ========================================= | |
94e980cc | 273 | Administering/protecting the private key |
3cafea30 JS |
274 | ========================================= |
275 | ||
276 | Since the private key is used to sign modules, viruses and malware could use | |
277 | the private key to sign modules and compromise the operating system. The | |
278 | private key must be either destroyed or moved to a secure location and not kept | |
279 | in the root node of the kernel source tree. | |
b8612e51 BH |
280 | |
281 | If you use the same private key to sign modules for multiple kernel | |
282 | configurations, you must ensure that the module version information is | |
283 | sufficient to prevent loading a module into a different kernel. Either | |
94e980cc MCC |
284 | set ``CONFIG_MODVERSIONS=y`` or ensure that each configuration has a different |
285 | kernel release string by changing ``EXTRAVERSION`` or ``CONFIG_LOCALVERSION``. |