1Kernel 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======== 18Overview 19======== 20 21The kernel module signing facility cryptographically signs modules during 22installation and then checks the signature upon loading the module. This 23allows increased kernel security by disallowing the loading of unsigned modules 24or modules signed with an invalid key. Module signing increases security by 25making it harder to load a malicious module into the kernel. The module 26signature checking is done by the kernel so that it is not necessary to have 27trusted userspace bits. 28 29This facility uses X.509 ITU-T standard certificates to encode the public keys 30involved. The signatures are not themselves encoded in any industrial standard 31type. The built-in facility currently only supports the RSA & NIST P-384 ECDSA 32public key signing standard (though it is pluggable and permits others to be 33used). The possible hash algorithms that can be used are SHA-2 and SHA-3 of 34sizes 256, 384, and 512 (the algorithm is selected by data in the signature). 35 36 37========================== 38Configuring module signing 39========================== 40 41The module signing facility is enabled by going to the 42:menuselection:`Enable Loadable Module Support` section of 43the kernel configuration and turning on:: 44 45 CONFIG_MODULE_SIG "Module signature verification" 46 47This 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 121Note that enabling module signing adds a dependency on the OpenSSL devel 122packages to the kernel build processes for the tool that does the signing. 123 124 125======================= 126Generating signing keys 127======================= 128 129Cryptographic keypairs are required to generate and check signatures. A 130private key is used to generate a signature and the corresponding public key is 131used to check it. The private key is only needed during the build, after which 132it can be deleted or stored securely. The public key gets built into the 133kernel so that it can be used to check the signatures as the modules are 134loaded. 135 136Under normal conditions, when ``CONFIG_MODULE_SIG_KEY`` is unchanged from its 137default, the kernel build will automatically generate a new keypair using 138openssl if one does not exist in the file:: 139 140 certs/signing_key.pem 141 142during the building of vmlinux (the public part of the key needs to be built 143into vmlinux) using parameters in the:: 144 145 certs/x509.genkey 146 147file (which is also generated if it does not already exist). 148 149One can select between RSA (``MODULE_SIG_KEY_TYPE_RSA``) and ECDSA 150(``MODULE_SIG_KEY_TYPE_ECDSA``) to generate either RSA 4k or NIST 151P-384 keypair. 152 153It is strongly recommended that you provide your own x509.genkey file. 154 155Most notably, in the x509.genkey file, the req_distinguished_name section 156should be altered from the default:: 157 158 [ req_distinguished_name ] 159 #O = Unspecified company 160 CN = Build time autogenerated kernel key 161 #emailAddress = [email protected] 162 163The generated RSA key size can also be set with:: 164 165 [ req ] 166 default_bits = 4096 167 168 169It is also possible to manually generate the key private/public files using the 170x509.genkey key generation configuration file in the root node of the Linux 171kernel sources tree and the openssl command. The following is an example to 172generate 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 178The full pathname for the resulting kernel_key.pem file can then be specified 179in the ``CONFIG_MODULE_SIG_KEY`` option, and the certificate and key therein will 180be used instead of an autogenerated keypair. 181 182 183========================= 184Public keys in the kernel 185========================= 186 187The kernel contains a ring of public keys that can be viewed by root. They're 188in 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 196Beyond the public key generated specifically for module signing, additional 197trusted certificates can be provided in a PEM-encoded file referenced by the 198``CONFIG_SYSTEM_TRUSTED_KEYS`` configuration option. 199 200Further, the architecture code may take public keys from a hardware store and 201add those in also (e.g. from the UEFI key database). 202 203Finally, it is possible to add additional public keys by doing:: 204 205 keyctl padd asymmetric "" [.builtin_trusted_keys-ID] <[key-file] 206 207e.g.:: 208 209 keyctl padd asymmetric "" 0x223c7853 <my_public_key.x509 210 211Note, 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 213that is already resident in the ``.builtin_trusted_keys`` at the time the key was added. 214 215 216======================== 217Manually signing modules 218======================== 219 220To manually sign a module, use the scripts/sign-file tool available in 221the 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 228The 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 233The hash algorithm used does not have to match the one configured, but if it 234doesn't, you should make sure that hash algorithm is either built into the 235kernel or can be loaded without requiring itself. 236 237If the private key requires a passphrase or PIN, it can be provided in the 238$KBUILD_SIGN_PIN environment variable. 239 240 241============================ 242Signed modules and stripping 243============================ 244 245A 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 247signature is present but it does not confirm that the signature is valid! 248 249Signed modules are BRITTLE as the signature is outside of the defined ELF 250container. Thus they MAY NOT be stripped once the signature is computed and 251attached. Note the entire module is the signed payload, including any and all 252debug information present at the time of signing. 253 254 255====================== 256Loading signed modules 257====================== 258 259Modules are loaded with insmod, modprobe, ``init_module()`` or 260``finit_module()``, exactly as for unsigned modules as no processing is 261done in userspace. The signature checking is all done within the kernel. 262 263 264========================================= 265Non-valid signatures and unsigned modules 266========================================= 267 268If ``CONFIG_MODULE_SIG_FORCE`` is enabled or module.sig_enforce=1 is supplied on 269the kernel command line, the kernel will only load validly signed modules 270for which it has a public key. Otherwise, it will also load modules that are 271unsigned. Any module for which the kernel has a key, but which proves to have 272a signature mismatch will not be permitted to load. 273 274Any module that has an unparsable signature will be rejected. 275 276 277========================================= 278Administering/protecting the private key 279========================================= 280 281Since the private key is used to sign modules, viruses and malware could use 282the private key to sign modules and compromise the operating system. The 283private key must be either destroyed or moved to a secure location and not kept 284in the root node of the kernel source tree. 285 286If you use the same private key to sign modules for multiple kernel 287configurations, you must ensure that the module version information is 288sufficient to prevent loading a module into a different kernel. Either 289set ``CONFIG_MODVERSIONS=y`` or ensure that each configuration has a different 290kernel release string by changing ``EXTRAVERSION`` or ``CONFIG_LOCALVERSION``. 291