291 lines · plain
1Kernel module signing facility2------------------------------3 4.. CONTENTS5..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========18Overview19========20 21The kernel module signing facility cryptographically signs modules during22installation and then checks the signature upon loading the module. This23allows increased kernel security by disallowing the loading of unsigned modules24or modules signed with an invalid key. Module signing increases security by25making it harder to load a malicious module into the kernel. The module26signature checking is done by the kernel so that it is not necessary to have27trusted userspace bits.28 29This facility uses X.509 ITU-T standard certificates to encode the public keys30involved. The signatures are not themselves encoded in any industrial standard31type. The built-in facility currently only supports the RSA & NIST P-384 ECDSA32public key signing standard (though it is pluggable and permits others to be33used). The possible hash algorithms that can be used are SHA-2 and SHA-3 of34sizes 256, 384, and 512 (the algorithm is selected by data in the signature).35 36 37==========================38Configuring module signing39==========================40 41The module signing facility is enabled by going to the42:menuselection:`Enable Loadable Module Support` section of43the 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 a53 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 not56 available and modules that are unsigned are permitted, but the kernel will57 be marked as being tainted, and the concerned modules will be marked as58 tainted, shown with the character 'E'.59 60 If this is on (ie. "restrictive"), only modules that have a valid61 signature that can be verified by a public key in the kernel's possession62 will be loaded. All other modules will generate an error.63 64 Irrespective of the setting here, if the module has a signature block that65 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 the72 modules_install phase of a build. If this is off, then the modules must73 be signed manually using::74 75 scripts/sign-file76 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 will81 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 (rather93 than being a module) so that modules signed with that algorithm can have94 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 of101 ``certs/signing_key.pem`` will disable the autogeneration of signing keys102 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 key104 and its corresponding X.509 certificate in PEM form, or — on systems where105 the OpenSSL ENGINE_pkcs11 is functional — a PKCS#11 URI as defined by106 RFC7512. In the latter case, the PKCS#11 URI should reference both a107 certificate and a private key.108 109 If the PEM file containing the private key is encrypted, or if the110 PKCS#11 token requires a PIN, this can be provided at build time by111 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 containing118 additional certificates which will be included in the system keyring by119 default.120 121Note that enabling module signing adds a dependency on the OpenSSL devel122packages to the kernel build processes for the tool that does the signing.123 124 125=======================126Generating signing keys127=======================128 129Cryptographic keypairs are required to generate and check signatures. A130private key is used to generate a signature and the corresponding public key is131used to check it. The private key is only needed during the build, after which132it can be deleted or stored securely. The public key gets built into the133kernel so that it can be used to check the signatures as the modules are134loaded.135 136Under normal conditions, when ``CONFIG_MODULE_SIG_KEY`` is unchanged from its137default, the kernel build will automatically generate a new keypair using138openssl if one does not exist in the file::139 140 certs/signing_key.pem141 142during the building of vmlinux (the public part of the key needs to be built143into vmlinux) using parameters in the::144 145 certs/x509.genkey146 147file (which is also generated if it does not already exist).148 149One can select between RSA (``MODULE_SIG_KEY_TYPE_RSA``) and ECDSA150(``MODULE_SIG_KEY_TYPE_ECDSA``) to generate either RSA 4k or NIST151P-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 section156should be altered from the default::157 158 [ req_distinguished_name ]159 #O = Unspecified company160 CN = Build time autogenerated kernel key161 #emailAddress = unspecified.user@unspecified.company162 163The generated RSA key size can also be set with::164 165 [ req ]166 default_bits = 4096167 168 169It is also possible to manually generate the key private/public files using the170x509.genkey key generation configuration file in the root node of the Linux171kernel sources tree and the openssl command. The following is an example to172generate 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.pem177 178The full pathname for the resulting kernel_key.pem file can then be specified179in the ``CONFIG_MODULE_SIG_KEY`` option, and the certificate and key therein will180be used instead of an autogenerated keypair.181 182 183=========================184Public keys in the kernel185=========================186 187The kernel contains a ring of public keys that can be viewed by root. They're188in a keyring called ".builtin_trusted_keys" that can be seen by::189 190 [root@deneb ~]# cat /proc/keys191 ...192 223c7853 I------ 1 perm 1f030000 0 0 keyring .builtin_trusted_keys: 1193 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, additional197trusted certificates can be provided in a PEM-encoded file referenced by the198``CONFIG_SYSTEM_TRUSTED_KEYS`` configuration option.199 200Further, the architecture code may take public keys from a hardware store and201add 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.x509210 211Note, however, that the kernel will only permit keys to be added to212``.builtin_trusted_keys`` **if** the new key's X.509 wrapper is validly signed by a key213that is already resident in the ``.builtin_trusted_keys`` at the time the key was added.214 215 216========================217Manually signing modules218========================219 220To manually sign a module, use the scripts/sign-file tool available in221the 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 URI225 3. The public key filename226 4. The kernel module to be signed227 228The following is an example to sign a kernel module::229 230 scripts/sign-file sha512 kernel-signkey.priv \231 kernel-signkey.x509 module.ko232 233The hash algorithm used does not have to match the one configured, but if it234doesn't, you should make sure that hash algorithm is either built into the235kernel or can be loaded without requiring itself.236 237If the private key requires a passphrase or PIN, it can be provided in the238$KBUILD_SIGN_PIN environment variable.239 240 241============================242Signed modules and stripping243============================244 245A signed module has a digital signature simply appended at the end. The string246``~Module signature appended~.`` at the end of the module's file confirms that a247signature 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 ELF250container. Thus they MAY NOT be stripped once the signature is computed and251attached. Note the entire module is the signed payload, including any and all252debug information present at the time of signing.253 254 255======================256Loading signed modules257======================258 259Modules are loaded with insmod, modprobe, ``init_module()`` or260``finit_module()``, exactly as for unsigned modules as no processing is261done in userspace. The signature checking is all done within the kernel.262 263 264=========================================265Non-valid signatures and unsigned modules266=========================================267 268If ``CONFIG_MODULE_SIG_FORCE`` is enabled or module.sig_enforce=1 is supplied on269the kernel command line, the kernel will only load validly signed modules270for which it has a public key. Otherwise, it will also load modules that are271unsigned. Any module for which the kernel has a key, but which proves to have272a 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 key279=========================================280 281Since the private key is used to sign modules, viruses and malware could use282the private key to sign modules and compromise the operating system. The283private key must be either destroyed or moved to a secure location and not kept284in the root node of the kernel source tree.285 286If you use the same private key to sign modules for multiple kernel287configurations, you must ensure that the module version information is288sufficient to prevent loading a module into a different kernel. Either289set ``CONFIG_MODVERSIONS=y`` or ensure that each configuration has a different290kernel release string by changing ``EXTRAVERSION`` or ``CONFIG_LOCALVERSION``.291