Subject: [PATCH v1] Add Documentation/module-signing.txt file
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 --- 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 000..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
[PATCH v2] Add Documentation/module-signing.txt file
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 was a mixture of the old RHEL style GPG signing. Version 1 updated the documentation to described the current implementation using x509 certificate signing. This new version, version 2, fixes grammar/spelling mistakes and removes trailing white spaces. Signed-off-by: James Solner --- Documentation/module-signing.txt | 115 +++ 1 file changed, 115 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 000..29f8ec7 --- /dev/null +++ b/Documentation/module-signing.txt @@ -0,0 +1,115 @@ + == + 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 to 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. These 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 symbol is enabled +to activate this feature. This feature supports two options for sign +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. + +Modules can be sign using two methodes: "automatically" or "manually". +The CONFIG_MODULE_SIG_ALL symbol will automatically sign 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 PRIVATE 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 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 node 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 module 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 n
[PATCH v3] Add Documentation/module-signing.txt file
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 was a mixture of the old RHEL style GPG signing. Version 1 updated the documentation to described the current implementation using x509 certificate signing. Version 2, fixes grammar/spelling mistakes and removes trailing whitespaces. Version 3, fixes grammar/spelling mistakes. Signed-off-by: James Solner --- Documentation/module-signing.txt | 115 +++ 1 file changed, 115 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 000..42aa52e --- /dev/null +++ b/Documentation/module-signing.txt @@ -0,0 +1,115 @@ + == + 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 to determine 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. These 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 symbol 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. + +Modules can be signed using two methods: "automatically" or "manually". +The CONFIG_MODULE_SIG_ALL symbol will automatically sign 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 PRIVATE 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 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 node 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 module 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
[PATCH] Adding Documentation/module-signing.txt file
This patch adds the Documentation/module-signing.txt file that is missing. There is a link to Documentation/module-signing.txt file in init/Kconfig that references this file. Signed-off-by: James Solner --- Documentation/module-signing.txt | 182 +++ 1 file changed, 182 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 000..b21e1f1 --- /dev/null +++ b/Documentation/module-signing.txt @@ -0,0 +1,182 @@ + == + KERNEL MODULE SIGNING FACILITY + == + +The module signing facility applies cryptographic signature checking to modules +on module load, checking the signature against a ring of public keys compiled +into the kernel. GPG is used to do the cryptographic work and determines the +format of the signature and key data. The facility uses GPG's MPI library to +handle the huge numbers involved. + +The signature checker in the kernel is capable of handling multiple keys of +either DSA or RSA type, and can support any of MD5, RIPE-MD-160, SHA-1, +SHA-224, SHA-256, SHA-384 and SHA-512 hashes - PROVIDED(!) the requisite +algorithms are compiled into the kernel. + +(!) NOTE: Modules may only be verified initially with algorithms compiled into +the kernel. Further algorithm modules may be loaded and used - but these must +first pass a verification step using already loaded/compiled-in algorithms. + + += +SUPPLYING PUBLIC KEYS += + +A set of public keys must be supplied at kernel image build time. This is done +by taking a GPG public key file and placing it in the base of the kernel +directory in a file called modsign.pub. + +For example, a throwaway key could be generated automatically by something like +the following: + + cat >genkey <<EOF + %pubring modsign.pub + %secring modsign.sec + Key-Type: RSA + Key-Length: 4096 + Name-Real: A. N. Other + Name-Comment: Kernel Module GPG key + %commit + EOF + gpg --homedir . --batch --gen-key genkey + +The above generates fresh keys using /dev/random. If there's insufficient data +in /dev/random, more can be provided using the rngd program if there's a +hardware random number generator available. + +Note that no GPG password is used in the above scriptlet. + +The modsign.pub file is compiled into the kernel directly by the assembler by +means of an ".incbin" directive in kernel/modsign-pubkey.c. + +Once the kernel is running, the keys are visible to root as kernel crypto keys +in /proc/keys in a keyring called .module_sign: + +335ab517 I- 1 perm 1f03 0 0 keyring .module_sign: 2/4 +38d7d169 I- 1 perm 3f01 0 0 cryptomodsign.0: rsa 57532ca5 [] +195fa736 I- 1 perm 3f01 0 0 cryptomodsign.1: dsa 5acc2142 [] + +This keyring can be listed with the keyctl program. See: + + Documentation/security/keys-crypto.txt + +for more information of crypto keys. + + + +SELECTING THE HASH ALGORITHM + + +The hash algorithm to be used is selected by a multiple choice configuration +item that enables one of the following variables: + + CONFIG_SIG_SHA1 + CONFIG_SIG_SHA224 + CONFIG_SIG_SHA256 + CONFIG_SIG_SHA384 + CONFIG_SIG_SHA512 + +These cause an appropriate "--digest-algo=" parameter to be passed to gpg when +signing a module and force the appropriate hash algorithm to be compiled +directly into the kernel rather than being built as a module. + + +== +MODULE SIGNING +== + +Modules will then be signed automatically. The kernel make command line can +include the following options: + + (*) MODSECKEY=<secret-key-ring-path> + + This indicates the whereabouts of the GPG keyring that is the source of + the secret key to be used. The default is "./modsign.sec". + + (*) MODPUBKEY=<public-key-ring-path> + + This indicates the whereabouts of the GPG keyring that is the source of + the public key to be used. The default is "./modsign.pub". + + (*) MODKEYNAME=<key-name> + + The name of the key pair to be used from the aforementioned keyrings. + This defaults to being unset, thus leaving the choice of default key to + gpg. + + (*) KEYFLAGS="gpg-options" + + Override the complete gpg command line, including the preceding three + options. The default options supplied to gpg are: + + --no-default-keyring + --secret-keyring $(MODSECKEY) + --keyring $(MODPUBKEY) + --no-default-keyring + --homedir . + --no-options + --no-auto-check-trustdb + --no-perm
[PATCH v4] Add Documentation/module-signing.txt file
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 was a mixture of the old RHEL style GPG signing. Version 1: Updated the documentation to described the current implementation using x509 certificate signing. Version 2: fixes grammar/spelling mistakes and removes trailing whitespaces. Version 3, fixes grammar/spelling mistakes. Version 4: Include updates from David Howells and fixes for spelling mistakes. Signed-off-by: James Solner diff --git a/Documentation/module-signing.txt b/Documentation/module-signing.txt new file mode 100644 index 000..c34815d --- /dev/null +++ b/Documentation/module-signing.txt @@ -0,0 +1,240 @@ + == + KERNEL MODULE SIGNING FACILITY + == + +CONTENTS + + - Overview. + - Configuring module signing. + - Generating signing keys. + - Public keys in the kernel. + - Manually signing modules. + - Signed modules and stripping. + - Loading signed modules. + - Non-valid signatures and unsigned modules. + - Administering/protecting the private key. + + + +OVERVIEW + + +The kernel module signing facility cryptographically signs modules during +installation and then checks the signature upon loading the module. This +allows increased kernel security by disallowing the loading of unsigned modules +or modules signed with an invalid key. Module signing increases security by +making it harder to load a malicious module into the kernel. The module +signature checking is done by the kernel so that it is not necessary to have +trusted userspace bits. + +This facility uses X.509 ITU-T standard certificates to encode the public keys +involved. The signatures are not themselves encoded in any industrial standard +type. The facility currently only supports the RSA public key encryption +standard (though it is pluggable and permits others to be used). The possible +hash algorithms that can be used are SHA-1, SHA-224, SHA-256, SHA-384, and +SHA-512 (the algorithm is selected by data in the signature). + + +== +CONFIGURING MODULE SIGNING +== + +The module signing facility is enabled by going to the "Enable Loadable Module +Support" section of the kernel configuration and turning on + + CONFIG_MODULE_SIG "Module signature verification" + +This has a number of options available: + + (1) "Require modules to be validly signed" (CONFIG_MODULE_SIG_FORCE) + + This specifies how the kernel should deal with a module that has a + signature for which the key is not known or a module that is unsigned. + + If this is off (ie. "permissive"), then modules for which the key is not + available and modules that are unsigned are permitted, but the kernel will + be marked as being tainted. + + If this is on (ie. "restrictive"), only modules that have a valid + signature that can be verified by a public key in the kernel's possession + will be loaded. All other modules will generate an error. + + Irrespective of the setting here, if the module has a signature block that + cannot be parsed, it will be rejected out of hand. + + + (2) "Automatically sign all modules" (CONFIG_MODULE_SIG_ALL) + + If this is on then modules will be automatically signed during the + modules_install phase of a build. If this is off, then the modules must + be signed manually using: + + scripts/sign-file + + + (3) "Which hash algorithm should modules be signed with?" + + This presents a choice of which hash algorithm the installation phase will + sign the modules with: + + CONFIG_SIG_SHA1 "Sign modules with SHA-1" + CONFIG_SIG_SHA224 "Sign modules with SHA-224" + CONFIG_SIG_SHA256 "Sign modules with SHA-256" + CONFIG_SIG_SHA384 "Sign modules with SHA-384" + CONFIG_SIG_SHA512 "Sign modules with SHA-512" + + The algorithm selected here will also be built into the kernel (rather + than being a module) so that modules signed with that algorithm can have + their signatures checked without causing a dependency loop. + + +=== +GENERATING SIGNING KEYS +=== + +Cryptographic keypairs are required to generate and check signatures. A +private key is used to generate a signature and the corresponding public key is +used to check it. The private key is only needed during the build, after which +it can be deleted
