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