Based on kernel version 4.8. Page generated on 2016-10-06 23:18 EST.
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, and the concerned modules will be marked as 57 tainted, shown with the character 'E'. 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 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" 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 (4) "File name or PKCS#11 URI of module signing key" (CONFIG_MODULE_SIG_KEY) 93 94 Setting this option to something other than its default of 95 "certs/signing_key.pem" will disable the autogeneration of signing keys 96 and allow the kernel modules to be signed with a key of your choosing. 97 The string provided should identify a file containing both a private key 98 and its corresponding X.509 certificate in PEM form, or — on systems where 99 the OpenSSL ENGINE_pkcs11 is functional — a PKCS#11 URI as defined by 100 RFC7512. In the latter case, the PKCS#11 URI should reference both a 101 certificate and a private key. 102 103 If the PEM file containing the private key is encrypted, or if the 104 PKCS#11 token requries a PIN, this can be provided at build time by 105 means of the KBUILD_SIGN_PIN variable. 106 107 108 (5) "Additional X.509 keys for default system keyring" (CONFIG_SYSTEM_TRUSTED_KEYS) 109 110 This option can be set to the filename of a PEM-encoded file containing 111 additional certificates which will be included in the system keyring by 112 default. 113 114 Note that enabling module signing adds a dependency on the OpenSSL devel 115 packages to the kernel build processes for the tool that does the signing. 116 117 118 ======================= 119 GENERATING SIGNING KEYS 120 ======================= 121 122 Cryptographic keypairs are required to generate and check signatures. A 123 private key is used to generate a signature and the corresponding public key is 124 used to check it. The private key is only needed during the build, after which 125 it can be deleted or stored securely. The public key gets built into the 126 kernel so that it can be used to check the signatures as the modules are 127 loaded. 128 129 Under normal conditions, when CONFIG_MODULE_SIG_KEY is unchanged from its 130 default, the kernel build will automatically generate a new keypair using 131 openssl if one does not exist in the file: 132 133 certs/signing_key.pem 134 135 during the building of vmlinux (the public part of the key needs to be built 136 into vmlinux) using parameters in the: 137 138 certs/x509.genkey 139 140 file (which is also generated if it does not already exist). 141 142 It is strongly recommended that you provide your own x509.genkey file. 143 144 Most notably, in the x509.genkey file, the req_distinguished_name section 145 should be altered from the default: 146 147 [ req_distinguished_name ] 148 #O = Unspecified company 149 CN = Build time autogenerated kernel key 150 #emailAddress = firstname.lastname@example.org 151 152 The generated RSA key size can also be set with: 153 154 [ req ] 155 default_bits = 4096 156 157 158 It is also possible to manually generate the key private/public files using the 159 x509.genkey key generation configuration file in the root node of the Linux 160 kernel sources tree and the openssl command. The following is an example to 161 generate the public/private key files: 162 163 openssl req -new -nodes -utf8 -sha256 -days 36500 -batch -x509 \ 164 -config x509.genkey -outform PEM -out kernel_key.pem \ 165 -keyout kernel_key.pem 166 167 The full pathname for the resulting kernel_key.pem file can then be specified 168 in the CONFIG_MODULE_SIG_KEY option, and the certificate and key therein will 169 be used instead of an autogenerated keypair. 170 171 172 ========================= 173 PUBLIC KEYS IN THE KERNEL 174 ========================= 175 176 The kernel contains a ring of public keys that can be viewed by root. They're 177 in a keyring called ".system_keyring" that can be seen by: 178 179 [root@deneb ~]# cat /proc/keys 180 ... 181 223c7853 I------ 1 perm 1f030000 0 0 keyring .system_keyring: 1 182 302d2d52 I------ 1 perm 1f010000 0 0 asymmetri Fedora kernel signing key: d69a84e6bce3d216b979e9505b3e3ef9a7118079: X509.RSA a7118079  183 ... 184 185 Beyond the public key generated specifically for module signing, additional 186 trusted certificates can be provided in a PEM-encoded file referenced by the 187 CONFIG_SYSTEM_TRUSTED_KEYS configuration option. 188 189 Further, the architecture code may take public keys from a hardware store and 190 add those in also (e.g. from the UEFI key database). 191 192 Finally, it is possible to add additional public keys by doing: 193 194 keyctl padd asymmetric "" [.system_keyring-ID] <[key-file] 195 196 e.g.: 197 198 keyctl padd asymmetric "" 0x223c7853 <my_public_key.x509 199 200 Note, however, that the kernel will only permit keys to be added to 201 .system_keyring _if_ the new key's X.509 wrapper is validly signed by a key 202 that is already resident in the .system_keyring at the time the key was added. 203 204 205 ========================= 206 MANUALLY SIGNING MODULES 207 ========================= 208 209 To manually sign a module, use the scripts/sign-file tool available in 210 the Linux kernel source tree. The script requires 4 arguments: 211 212 1. The hash algorithm (e.g., sha256) 213 2. The private key filename or PKCS#11 URI 214 3. The public key filename 215 4. The kernel module to be signed 216 217 The following is an example to sign a kernel module: 218 219 scripts/sign-file sha512 kernel-signkey.priv \ 220 kernel-signkey.x509 module.ko 221 222 The hash algorithm used does not have to match the one configured, but if it 223 doesn't, you should make sure that hash algorithm is either built into the 224 kernel or can be loaded without requiring itself. 225 226 If the private key requires a passphrase or PIN, it can be provided in the 227 $KBUILD_SIGN_PIN environment variable. 228 229 230 ============================ 231 SIGNED MODULES AND STRIPPING 232 ============================ 233 234 A signed module has a digital signature simply appended at the end. The string 235 "~Module signature appended~." at the end of the module's file confirms that a 236 signature is present but it does not confirm that the signature is valid! 237 238 Signed modules are BRITTLE as the signature is outside of the defined ELF 239 container. Thus they MAY NOT be stripped once the signature is computed and 240 attached. Note the entire module is the signed payload, including any and all 241 debug information present at the time of signing. 242 243 244 ====================== 245 LOADING SIGNED MODULES 246 ====================== 247 248 Modules are loaded with insmod, modprobe, init_module() or finit_module(), 249 exactly as for unsigned modules as no processing is done in userspace. The 250 signature checking is all done within the kernel. 251 252 253 ========================================= 254 NON-VALID SIGNATURES AND UNSIGNED MODULES 255 ========================================= 256 257 If CONFIG_MODULE_SIG_FORCE is enabled or module.sig_enforce=1 is supplied on 258 the kernel command line, the kernel will only load validly signed modules 259 for which it has a public key. Otherwise, it will also load modules that are 260 unsigned. Any module for which the kernel has a key, but which proves to have 261 a signature mismatch will not be permitted to load. 262 263 Any module that has an unparseable signature will be rejected. 264 265 266 ========================================= 267 ADMINISTERING/PROTECTING THE PRIVATE KEY 268 ========================================= 269 270 Since the private key is used to sign modules, viruses and malware could use 271 the private key to sign modules and compromise the operating system. The 272 private key must be either destroyed or moved to a secure location and not kept 273 in the root node of the kernel source tree. 274 275 If you use the same private key to sign modules for multiple kernel 276 configurations, you must ensure that the module version information is 277 sufficient to prevent loading a module into a different kernel. Either 278 set CONFIG_MODVERSIONS=y or ensure that each configuration has a different 279 kernel release string by changing EXTRAVERSION or CONFIG_LOCALVERSION.