This patch adds the Documentation/module-signing.txt file that is currently missing from the Documentation directory. The init/Kconfig file references the Documentation/module-signing.txt file to explain how kernel module signing works. This patch supplies this documentation. The initial version of this patch provided old documentation that used that was a mix of the old RHEL style GPG signing. This new version, version 1, is updated to the current appended-signature x509 certificate signing. Signed-off-by: James Solner <solner@xxxxxxxxxxxxxxxxxx> --- Documentation/module-signing.txt | 117 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 Documentation/module-signing.txt diff --git a/Documentation/module-signing.txt b/Documentation/module-signing.txt new file mode 100644 index 0000000..fdae5b2 --- /dev/null +++ b/Documentation/module-signing.txt @@ -0,0 +1,117 @@ + ============================== + KERNEL MODULE SIGNING FACILITY + ============================== + +The module signing facility applies cryptographic signature checking +when loading modules by checking its signature against a public key. +This allows increased kernel security by disallowing loading unsigned +modules or modules signed with an invalid key. Module signing increases +the kernel security and reduces the odds of malicious modules being +loading into Linux operating system. + +This facility uses X.509 ITU-T standard to perform the cryptographic +work and determines the format of the signatures and key data. The +key type used is RSA and the possible hash algorithms that can be +used are SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512. Provided +the requisite algorithms are configured and compiled into the +kernel. The following hash algorithms can be selected during the kernel +configuration build: + + CONFIG_SIG_SHA1 + CONFIG_SIG_SHA224 + CONFIG_SIG_SHA256 + CONFIG_SIG_SHA384 + CONFIG_SIG_SHA512 + +The module signing facility is a kernel feature and is enabled through the +Linux kernel configuration builder. In the "Enable Loadable Module Support" +section of the kernel configuration, the CONFIG_MODULE_SIG define is enabled +to activate this feature. This feature supports two options for signed +module support: "permissive" and "restrictive". The default is the +"permissive" option and allows a module with a valid signature to be loaded. +If the signature is invalid, the module is still loaded, but the kernel is +marked as "tainted". The "restrictive" option (CONFIG_MODULE_SIG_FORCE) +requires a valid signature before the module can be loaded. + +There are two ways to signed modules: "automatically" or "manually". +The CONFIG_MODULE_SIG_ALL define will automatically signed the modules +during the "modules_install" part of the kernel build. A module can also +be signed manually using the scripts/sign-file tool. + +================================================ +AUTOMATICALLY GENERATING PUBLIC AND PUBLIC KEYS +================================================ +As part of "modules_install" kernel build, the Linux kernel build +infrastructure will automatically create two files in the root node +of the Linux kernel source tree. These files contain the public/private +keys and are called "signing_key.x509" and "signing_key.priv". +The public key is built into to the kernel and used to verify modules +signatures when the modules are loaded. + +================================================= +MANUALLY GENERATING PUBLIC AND PRIVATE KEYS +================================================= +To manually generate the key private/public files, use the x509.genkey key +generation configuration file in the root mode of the Linux kernel +sources tree and the openssl command. The following is an example to +generate the public/private key files: + + openssl req -new -nodes -utf8 -sha256 -days 36500 -batch -x509 \ + -config x509.genkey -outform DER -out signing_key.x509 \ + -keyout signing_key.priv + +========================= +MANUALLY SIGNING MODULES +========================= +To manually sign a module, use the scripts/sign-file tool available in +the Linux kernel source tree. The script requires 4 arguments: + + 1. The hash algorithm (e.g., sha256) + 2. The private key + 3. The public key + 4. The kernel module to be signed + +The following is an example to sign a kernel module: + + scripts/sign-file sha512 kernel-signkey.priv \ + kernel-signkey.x509 module.ko + +============================ +SIGNED MODULES AND STRIPPING +============================ + +A signed modules has a digital signature appended at the end. The string +"~Module signature appended~." at the end of the module's file confirms +that a signature is present. But, it does not confirm that the +signature is valid! + +Signed modules are BRITTLE as the signature is outside of the defined +ELF container. Thus they MAY NOT be stripped once the signature is computed +and attached. Note the entire module is the signed payload, including +all the debug information present at the time of signing. + +====================== +LOADING SIGNED MODULES +====================== + +Modules are loaded with insmod, exactly as for unsigned modules. +The signature checker checks at the end of the file for the signature +marker and apply signature checking. + +========================================= +NON-VALID SIGNATURES AND UNSIGNED MODULES +========================================= + +If CONFIG_MODULE_SIG_FORCE is enabled or enforcemodulesig=1 is supplied on +the kernel command line, the kernel will only load validly signed modules +for which it has a public key. Otherwise, it will also load modules that are +unsigned. Any module for which the kernel has a key, but which proves to have +a signature mismatch will not be permitted to load. + +========================================= +ADMINISTERING/PROTECTING THE PRIVATE KEY +========================================= +Since the private key is used to signed modules, malware can use +the private key to signed modules and compromise the operating system. +The private key must be moved to secure location and not keep in +the root node of the kernel source tree. -- 1.7.12.4 --- -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
