Skip to contentSkip to conversation

Subject: [PATCH v1] Add Documentation/module-signing.txt file

PATCH James Solner 2 participants 2 messages Nov 5, 2013 Documentation

lore
Share & tools
lore
#0 lore raw

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.

---
 Documentation/module-signing.txt | 117 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 117 insertions(+)
 create mode 100644 Documentation/module-signing.txt
Documentation/module-signing.txt new file +117 -0
new file mode 100644
index 0000000..fdae5b2
@@ -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. 
Signature · 2 lines
1.7.12.4
---
reviewer
#1 lore raw
Quoted 26 lines · James Solner

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.

---
 Documentation/module-signing.txt | 117 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 117 insertions(+)
 create mode 100644 Documentation/module-signing.txt
Documentation/module-signing.txt new file +3 -0
new file mode 100644
index 0000000..fdae5b2
@@ -0,0 +1,117 @@
+		==============================
+		KERNEL MODULE SIGNING FACILITY
+		==============================

Documentation/module-signing.txt line 13

Quoted 10 lines
Documentation/module-signing.txt new file +10 -0
+
+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 

and [to] determine

Documentation/module-signing.txt line 16

Quoted 3 lines
Documentation/module-signing.txt new file +3 -0
+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 

Provided.... is not a sentence.

Documentation/module-signing.txt line 28

Quoted 12 lines
Documentation/module-signing.txt new file +12 -0
+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 

symbol

Documentation/module-signing.txt line 36

Quoted 8 lines
Documentation/module-signing.txt new file +8 -0
+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". 

Missing some word after "to".

Documentation/module-signing.txt line 37

Quoted 1 line
Documentation/module-signing.txt new file +1 -0
+The CONFIG_MODULE_SIG_ALL define will automatically signed the modules 

symbol sign

Documentation/module-signing.txt line 42

Quoted 5 lines
Documentation/module-signing.txt new file +5 -0
+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

Should one of these ^^^^^ be PRIVATE?

Documentation/module-signing.txt line 48

Quoted 6 lines
Documentation/module-signing.txt new file +6 -0
+================================================
+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 

^^drop "to" modules'

Documentation/module-signing.txt line 56

Quoted 8 lines
Documentation/module-signing.txt new file +8 -0
+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 

What does "in the root mode of the Linux kernel sources tree" mean?

Oh, I see later on that it is "root node". Typo.

Quoted 17 lines
Documentation/module-signing.txt new file +17 -0
+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
+	

Documentation/module-signing.txt line 83

Quoted 10 lines
Documentation/module-signing.txt new file +10 -0
+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

Quoted 6 lines
Documentation/module-signing.txt new file +6 -0
+"~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

Documentation/module-signing.txt line 99

Quoted 10 lines
Documentation/module-signing.txt new file +10 -0
+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. 

applies

Quoted 5 lines
Documentation/module-signing.txt new file +5 -0
+
+=========================================
+NON-VALID SIGNATURES AND UNSIGNED MODULES
+=========================================
+

Documentation/module-signing.txt line 114

Quoted 10 lines
Documentation/module-signing.txt new file +10 -0
+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 

sign

Documentation/module-signing.txt line 115

Quoted 1 line
Documentation/module-signing.txt new file +1 -0
+the private key to signed modules and compromise the operating system. 

sign

Documentation/module-signing.txt line 116

Quoted 1 line
Documentation/module-signing.txt new file +1 -0
+The private key must be moved to secure location and not keep in 

to a secure location and not kept in

Documentation/module-signing.txt line 117

Quoted 2 lines
Documentation/module-signing.txt new file +1 -0
+the root node of the kernel source tree. 

Finally, please strip all trailing spaces from each line (and there are many of them).

Signature · 1 line
~Randy