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