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 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 built-in facility currently only supports the RSA & NIST P-384 ECDSA 32 public key signing standard (though it is pluggable and permits others to be 33 used). The possible hash algorithms that can be used are SHA-2 and SHA-3 of 34 sizes 256, 384, and 512 (the algorithm is selected by data in the signature). 35 36 37 ========================== 38 Configuring module signing 39 ========================== 40 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:: 44 45 CONFIG_MODULE_SIG "Module signature verification" 46 47 This has a number of options available: 48 49 (1) :menuselection:`Require modules to be validly signed` 50 (``CONFIG_MODULE_SIG_FORCE``) 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 57 be marked as being tainted, and the concerned modules will be marked as 58 tainted, shown with the character 'E'. 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 68 (2) :menuselection:`Automatically sign all modules` 69 (``CONFIG_MODULE_SIG_ALL``) 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 73 be signed manually using:: 74 75 scripts/sign-file 76 77 78 (3) :menuselection:`Which hash algorithm should modules be signed with?` 79 80 This presents a choice of which hash algorithm the installation phase will 81 sign the modules with: 82 83 =============================== ========================================== 84 ``CONFIG_MODULE_SIG_SHA256`` :menuselection:`Sign modules with SHA-256` 85 ``CONFIG_MODULE_SIG_SHA384`` :menuselection:`Sign modules with SHA-384` 86 ``CONFIG_MODULE_SIG_SHA512`` :menuselection:`Sign modules with SHA-512` 87 ``CONFIG_MODULE_SIG_SHA3_256`` :menuselection:`Sign modules with SHA3-256` 88 ``CONFIG_MODULE_SIG_SHA3_384`` :menuselection:`Sign modules with SHA3-384` 89 ``CONFIG_MODULE_SIG_SHA3_512`` :menuselection:`Sign modules with SHA3-512` 90 =============================== ========================================== 91 92 The algorithm selected here will also be built into the kernel (rather 93 than being a module) so that modules signed with that algorithm can have 94 their signatures checked without causing a dependency loop. 95 96 97 (4) :menuselection:`File name or PKCS#11 URI of module signing key` 98 (``CONFIG_MODULE_SIG_KEY``) 99 100 Setting this option to something other than its default of 101 ``certs/signing_key.pem`` will disable the autogeneration of signing keys 102 and allow the kernel modules to be signed with a key of your choosing. 103 The string provided should identify a file containing both a private key 104 and its corresponding X.509 certificate in PEM form, or — on systems where 105 the OpenSSL ENGINE_pkcs11 is functional — a PKCS#11 URI as defined by 106 RFC7512. In the latter case, the PKCS#11 URI should reference both a 107 certificate and a private key. 108 109 If the PEM file containing the private key is encrypted, or if the 110 PKCS#11 token requires a PIN, this can be provided at build time by 111 means of the ``KBUILD_SIGN_PIN`` variable. 112 113 114 (5) :menuselection:`Additional X.509 keys for default system keyring` 115 (``CONFIG_SYSTEM_TRUSTED_KEYS``) 116 117 This option can be set to the filename of a PEM-encoded file containing 118 additional certificates which will be included in the system keyring by 119 default. 120 121 Note that enabling module signing adds a dependency on the OpenSSL devel 122 packages to the kernel build processes for the tool that does the signing. 123 124 125 ======================= 126 Generating signing keys 127 ======================= 128 129 Cryptographic keypairs are required to generate and check signatures. A 130 private key is used to generate a signature and the corresponding public key is 131 used to check it. The private key is only needed during the build, after which 132 it can be deleted or stored securely. The public key gets built into the 133 kernel so that it can be used to check the signatures as the modules are 134 loaded. 135 136 Under normal conditions, when ``CONFIG_MODULE_SIG_KEY`` is unchanged from its 137 default, the kernel build will automatically generate a new keypair using 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 part of the key needs to be built 143 into vmlinux) using parameters in the:: 144 145 certs/x509.genkey 146 147 file (which is also generated if it does not already exist). 148 149 One can select between RSA (``MODULE_SIG_KEY_TYPE_RSA``) and ECDSA 150 (``MODULE_SIG_KEY_TYPE_ECDSA``) to generate either RSA 4k or NIST 151 P-384 keypair. 152 153 It is strongly recommended that you provide your own x509.genkey file. 154 155 Most notably, in the x509.genkey file, the req_distinguished_name section 156 should be altered from the default:: 157 158 [ req_distinguished_name ] 159 #O = Unspecified company 160 CN = Build time autogenerated kernel key 161 #emailAddress = unspecified.user@unspecified.company 162 163 The generated RSA key size can also be set with:: 164 165 [ req ] 166 default_bits = 4096 167 168 169 It is also possible to manually generate the key private/public files using the 170 x509.genkey key generation configuration file in the root node of the Linux 171 kernel sources tree and the openssl command. The following is an example to 172 generate the public/private key files:: 173 174 openssl req -new -nodes -utf8 -sha256 -days 36500 -batch -x509 \ 175 -config x509.genkey -outform PEM -out kernel_key.pem \ 176 -keyout kernel_key.pem 177 178 The full pathname for the resulting kernel_key.pem file can then be specified 179 in the ``CONFIG_MODULE_SIG_KEY`` option, and the certificate and key therein will 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 can be viewed by root. They're 188 in a keyring called ".builtin_trusted_keys" that can be seen by:: 189 190 [root@deneb ~]# cat /proc/keys 191 ... 192 223c7853 I------ 1 perm 1f030000 0 0 keyring .builtin_trusted_keys: 1 193 302d2d52 I------ 1 perm 1f010000 0 0 asymmetri Fedora kernel signing key: d69a84e6bce3d216b979e9505b3e3ef9a7118079: X509.RSA a7118079 [] 194 ... 195 196 Beyond the public key generated specifically for module signing, additional 197 trusted certificates can be provided in a PEM-encoded file referenced by the 198 ``CONFIG_SYSTEM_TRUSTED_KEYS`` configuration option. 199 200 Further, the architecture code may take public keys from a hardware store and 201 add those in also (e.g. from the UEFI key database). 202 203 Finally, it is possible to add additional public keys by doing:: 204 205 keyctl padd asymmetric "" [.builtin_trusted_keys-ID] <[key-file] 206 207 e.g.:: 208 209 keyctl padd asymmetric "" 0x223c7853 <my_public_key.x509 210 211 Note, however, that the kernel will only permit keys to be added to 212 ``.builtin_trusted_keys`` **if** the new key's X.509 wrapper is validly signed by a key 213 that is already resident in the ``.builtin_trusted_keys`` at the time the key was added. 214 215 216 ======================== 217 Manually signing modules 218 ======================== 219 220 To manually sign a module, use the scripts/sign-file tool available in 221 the Linux kernel source tree. The script requires 4 arguments: 222 223 1. The hash algorithm (e.g., sha256) 224 2. The private key filename or PKCS#11 URI 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 module:: 229 230 scripts/sign-file sha512 kernel-signkey.priv \ 231 kernel-signkey.x509 module.ko 232 233 The hash algorithm used does not have to match the one configured, but if it 234 doesn't, you should make sure that hash algorithm is either built into the 235 kernel or can be loaded without requiring itself. 236 237 If the private key requires a passphrase or PIN, it can be provided in the 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 appended at the end. The string 246 ``~Module signature appended~.`` at the end of the module's file confirms that a 247 signature is present but it does not confirm that the signature is valid! 248 249 Signed modules are BRITTLE as the signature is outside of the defined ELF 250 container. Thus they MAY NOT be stripped once the signature is computed and 251 attached. Note the entire module is the signed payload, including any and all 252 debug information present at the time of signing. 253 254 255 ====================== 256 Loading signed modules 257 ====================== 258 259 Modules are loaded with insmod, modprobe, ``init_module()`` or 260 ``finit_module()``, exactly as for unsigned modules as no processing is 261 done in userspace. The signature checking is all done within the kernel. 262 263 264 ========================================= 265 Non-valid signatures and unsigned modules 266 ========================================= 267 268 If ``CONFIG_MODULE_SIG_FORCE`` is enabled or module.sig_enforce=1 is supplied on 269 the kernel command line, the kernel will only load validly signed modules 270 for which it has a public key. Otherwise, it will also load modules that are 271 unsigned. Any module for which the kernel has a key, but which proves to have 272 a signature mismatch will not be permitted to load. 273 274 Any module that has an unparsable signature will be rejected. 275 276 277 ========================================= 278 Administering/protecting the private key 279 ========================================= 280 281 Since the private key is used to sign modules, viruses and malware could use 282 the private key to sign modules and compromise the operating system. The 283 private key must be either destroyed or moved to a secure location and not kept 284 in the root node of the kernel source tree. 285 286 If you use the same private key to sign modules for multiple kernel 287 configurations, you must ensure that the module version information is 288 sufficient to prevent loading a module into a different kernel. Either 289 set ``CONFIG_MODVERSIONS=y`` or ensure that each configuration has a different 290 kernel release string by changing ``EXTRAVERSION`` or ``CONFIG_LOCALVERSION``.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.