Commit | Line | Data |
---|---|---|
3cafea30 JS |
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 | |
66cc69e3 | 56 | be marked as being tainted, and the concerned modules will be marked as |
57673c2b | 57 | tainted, shown with the character 'E'. |
3cafea30 JS |
58 | |
59 | If this is on (ie. "restrictive"), only modules that have a valid | |
60 | signature that can be verified by a public key in the kernel's possession | |
61 | will be loaded. All other modules will generate an error. | |
62 | ||
63 | Irrespective of the setting here, if the module has a signature block that | |
64 | cannot be parsed, it will be rejected out of hand. | |
65 | ||
66 | ||
67 | (2) "Automatically sign all modules" (CONFIG_MODULE_SIG_ALL) | |
68 | ||
69 | If this is on then modules will be automatically signed during the | |
70 | modules_install phase of a build. If this is off, then the modules must | |
71 | be signed manually using: | |
72 | ||
73 | scripts/sign-file | |
74 | ||
75 | ||
76 | (3) "Which hash algorithm should modules be signed with?" | |
77 | ||
78 | This presents a choice of which hash algorithm the installation phase will | |
79 | sign the modules with: | |
80 | ||
7df2482f PB |
81 | CONFIG_MODULE_SIG_SHA1 "Sign modules with SHA-1" |
82 | CONFIG_MODULE_SIG_SHA224 "Sign modules with SHA-224" | |
83 | CONFIG_MODULE_SIG_SHA256 "Sign modules with SHA-256" | |
84 | CONFIG_MODULE_SIG_SHA384 "Sign modules with SHA-384" | |
85 | CONFIG_MODULE_SIG_SHA512 "Sign modules with SHA-512" | |
3cafea30 JS |
86 | |
87 | The algorithm selected here will also be built into the kernel (rather | |
88 | than being a module) so that modules signed with that algorithm can have | |
89 | their signatures checked without causing a dependency loop. | |
90 | ||
91 | ||
92 | ======================= | |
93 | GENERATING SIGNING KEYS | |
94 | ======================= | |
95 | ||
96 | Cryptographic keypairs are required to generate and check signatures. A | |
97 | private key is used to generate a signature and the corresponding public key is | |
98 | used to check it. The private key is only needed during the build, after which | |
99 | it can be deleted or stored securely. The public key gets built into the | |
100 | kernel so that it can be used to check the signatures as the modules are | |
101 | loaded. | |
102 | ||
103 | Under normal conditions, the kernel build will automatically generate a new | |
104 | keypair using openssl if one does not exist in the files: | |
105 | ||
106 | signing_key.priv | |
107 | signing_key.x509 | |
108 | ||
109 | during the building of vmlinux (the public part of the key needs to be built | |
110 | into vmlinux) using parameters in the: | |
111 | ||
112 | x509.genkey | |
113 | ||
114 | file (which is also generated if it does not already exist). | |
115 | ||
116 | It is strongly recommended that you provide your own x509.genkey file. | |
117 | ||
118 | Most notably, in the x509.genkey file, the req_distinguished_name section | |
119 | should be altered from the default: | |
120 | ||
121 | [ req_distinguished_name ] | |
9c4249c8 DH |
122 | #O = Unspecified company |
123 | CN = Build time autogenerated kernel key | |
124 | #emailAddress = unspecified.user@unspecified.company | |
3cafea30 JS |
125 | |
126 | The generated RSA key size can also be set with: | |
127 | ||
128 | [ req ] | |
129 | default_bits = 4096 | |
130 | ||
131 | ||
132 | It is also possible to manually generate the key private/public files using the | |
133 | x509.genkey key generation configuration file in the root node of the Linux | |
134 | kernel sources tree and the openssl command. The following is an example to | |
135 | generate the public/private key files: | |
136 | ||
137 | openssl req -new -nodes -utf8 -sha256 -days 36500 -batch -x509 \ | |
138 | -config x509.genkey -outform DER -out signing_key.x509 \ | |
139 | -keyout signing_key.priv | |
140 | ||
141 | ||
142 | ========================= | |
143 | PUBLIC KEYS IN THE KERNEL | |
144 | ========================= | |
145 | ||
146 | The kernel contains a ring of public keys that can be viewed by root. They're | |
147 | in a keyring called ".system_keyring" that can be seen by: | |
148 | ||
149 | [root@deneb ~]# cat /proc/keys | |
150 | ... | |
151 | 223c7853 I------ 1 perm 1f030000 0 0 keyring .system_keyring: 1 | |
152 | 302d2d52 I------ 1 perm 1f010000 0 0 asymmetri Fedora kernel signing key: d69a84e6bce3d216b979e9505b3e3ef9a7118079: X509.RSA a7118079 [] | |
153 | ... | |
154 | ||
155 | Beyond the public key generated specifically for module signing, any file | |
156 | placed in the kernel source root directory or the kernel build root directory | |
157 | whose name is suffixed with ".x509" will be assumed to be an X.509 public key | |
158 | and will be added to the keyring. | |
159 | ||
160 | Further, the architecture code may take public keys from a hardware store and | |
161 | add those in also (e.g. from the UEFI key database). | |
162 | ||
163 | Finally, it is possible to add additional public keys by doing: | |
164 | ||
165 | keyctl padd asymmetric "" [.system_keyring-ID] <[key-file] | |
166 | ||
167 | e.g.: | |
168 | ||
169 | keyctl padd asymmetric "" 0x223c7853 <my_public_key.x509 | |
170 | ||
171 | Note, however, that the kernel will only permit keys to be added to | |
172 | .system_keyring _if_ the new key's X.509 wrapper is validly signed by a key | |
173 | that is already resident in the .system_keyring at the time the key was added. | |
174 | ||
175 | ||
176 | ========================= | |
177 | MANUALLY SIGNING MODULES | |
178 | ========================= | |
179 | ||
180 | To manually sign a module, use the scripts/sign-file tool available in | |
181 | the Linux kernel source tree. The script requires 4 arguments: | |
182 | ||
183 | 1. The hash algorithm (e.g., sha256) | |
184 | 2. The private key filename | |
185 | 3. The public key filename | |
186 | 4. The kernel module to be signed | |
187 | ||
188 | The following is an example to sign a kernel module: | |
189 | ||
190 | scripts/sign-file sha512 kernel-signkey.priv \ | |
191 | kernel-signkey.x509 module.ko | |
192 | ||
193 | The hash algorithm used does not have to match the one configured, but if it | |
194 | doesn't, you should make sure that hash algorithm is either built into the | |
195 | kernel or can be loaded without requiring itself. | |
196 | ||
197 | ||
198 | ============================ | |
199 | SIGNED MODULES AND STRIPPING | |
200 | ============================ | |
201 | ||
202 | A signed module has a digital signature simply appended at the end. The string | |
203 | "~Module signature appended~." at the end of the module's file confirms that a | |
204 | signature is present but it does not confirm that the signature is valid! | |
205 | ||
206 | Signed modules are BRITTLE as the signature is outside of the defined ELF | |
207 | container. Thus they MAY NOT be stripped once the signature is computed and | |
208 | attached. Note the entire module is the signed payload, including any and all | |
209 | debug information present at the time of signing. | |
210 | ||
211 | ||
212 | ====================== | |
213 | LOADING SIGNED MODULES | |
214 | ====================== | |
215 | ||
216 | Modules are loaded with insmod, modprobe, init_module() or finit_module(), | |
217 | exactly as for unsigned modules as no processing is done in userspace. The | |
218 | signature checking is all done within the kernel. | |
219 | ||
220 | ||
221 | ========================================= | |
222 | NON-VALID SIGNATURES AND UNSIGNED MODULES | |
223 | ========================================= | |
224 | ||
225 | If CONFIG_MODULE_SIG_FORCE is enabled or enforcemodulesig=1 is supplied on | |
226 | the kernel command line, the kernel will only load validly signed modules | |
227 | for which it has a public key. Otherwise, it will also load modules that are | |
228 | unsigned. Any module for which the kernel has a key, but which proves to have | |
229 | a signature mismatch will not be permitted to load. | |
230 | ||
231 | Any module that has an unparseable signature will be rejected. | |
232 | ||
233 | ||
234 | ========================================= | |
235 | ADMINISTERING/PROTECTING THE PRIVATE KEY | |
236 | ========================================= | |
237 | ||
238 | Since the private key is used to sign modules, viruses and malware could use | |
239 | the private key to sign modules and compromise the operating system. The | |
240 | private key must be either destroyed or moved to a secure location and not kept | |
241 | in the root node of the kernel source tree. |