Documentation/admin-guide/module-signing.rst

   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``.