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