Skip to contentSkip to conversation

Adding Documentation/module-signing.txt file

PATCH Superseded James Solner 4 participants 5 messages Oct 24, 2013 – Nov 11, 2013 Documentation

v1 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 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.

---
 Documentation/module-signing.txt | 182 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 182 insertions(+)
 create mode 100644 Documentation/module-signing.txt
Documentation/module-signing.txt new file +182 -0
new file mode 100644
index 0000000..b21e1f1
@@ -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 1f030000     0     0 keyring   .module_sign: 2/4
+38d7d169 I-----     1 perm 3f010000     0     0 crypto    modsign.0: rsa 57532ca5 []
+195fa736 I-----     1 perm 3f010000     0     0 crypto    modsign.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-permission-warning
+	--digest-algo=<hash-algorithm>
+
+      with:
+
+	--default-key $(MODKEYNAME)
+
+      being added if requested.
+
+The resulting module.ko file will be the signed module.
+
+
+============================
+SIGNED MODULES AND STRIPPING
+============================
+
+The module signature is just appended to the module binary with a magic number
+at the end of file, a couple of fixed-size lengths prior to that and the
+signature prior to that.
+
+WARNING! 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, lest the signature be discarded or the payload be modified.  Note
+that the entire module is the signed payload, including all the debug
+information present at the time of signing so it must still be present when the
+signature is checked.
+
+As the module may need to be included in a ramdisk image of limited capacity,
+modules are maximally stripped prior to signing by the build process.
+
+Note that if FIPS mode is engaged, a module for which the signature does not
+match the payload will panic the box.
+
+
+======================
+LOADING SIGNED MODULES
+======================
+
+Modules are loaded with insmod, exactly as for unsigned modules.  The signature
+checker will check at the end of the file for the signature marker and apply
+signature checking if found.
+
+
+=========================================
+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 (returning EKEYREJECTED).
+
+This table indicates the behaviours of the various situations:
+
+	MODULE STATE				PERMISSIVE MODE	ENFORCING MODE
+	=======================================	===============	===============
+	Unsigned				Ok		EKEYREJECTED
+	Signed, no public key			ENOKEY		ENOKEY
+	Validly signed, public key		Ok		Ok
+	Invalidly signed, public key		EKEYREJECTED	EKEYREJECTED
+	Validly signed, expired key		EKEYEXPIRED	EKEYEXPIRED
+	Signed, hash algorithm unavailable	ENOPKG		ENOPKG
+	Corrupt signature			EBADMSG		EBADMSG
Signature · 2 lines
1.7.12.4
---
#1 lore raw
Quoted 5 lines · James Solner

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.

Nak. Please see below.

Quoted 48 lines
---
 Documentation/module-signing.txt | 182 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 182 insertions(+)
 create mode 100644 Documentation/module-signing.txt
Documentation/module-signing.txt new file +37 -0
new file mode 100644
index 0000000..b21e1f1
@@ -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

Documentation/module-signing.txt line 47

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

This is inaccurate and doesn't match how module signing is done today.
The document you have here is a weird mix of the old RHEL style GPG
signing and the current appended-signature x509 certificate signing.

It needs to be updated to match the fact that x509 keys and signatures are used now.

josh

#2 lore raw
Quoted 89 lines · Josh Boyer
Quoted 5 lines · James Solner

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.

Nak. Please see below.

Quoted 2 lines
---
 Documentation/module-signing.txt | 182  

+++++++++++++++++++++++++++++++++++++++

Review

Quoted 4 lines
 1 file changed, 182 insertions(+)
 create mode 100644 Documentation/module-signing.txt
(quoted diff) +0 -0

b/Documentation/module-signing.txt

Documentation/module-signing.txt line 5

Quoted 10 lines

new file mode 100644
index 0000000..b21e1f1

Documentation/module-signing.txt new file +5 -0
@@ -0,0 +1,182 @@
+                       ==============================
+                       KERNEL MODULE SIGNING FACILITY
+                       ==============================
+
+The module signing facility applies cryptographic signature  

checking to modules

Documentation/module-signing.txt line 6

Quoted 1 line
Documentation/module-signing.txt new file +1 -0
+on module load, checking the signature against a ring of public  

keys compiled

Documentation/module-signing.txt line 7

Quoted 1 line
Documentation/module-signing.txt new file +1 -0
+into the kernel.  GPG is used to do the cryptographic work and  

determines the

Documentation/module-signing.txt line 8

Quoted 1 line
Documentation/module-signing.txt new file +1 -0
+format of the signature and key data.  The facility uses GPG's  

MPI library to

Documentation/module-signing.txt

Quoted 3 lines
Documentation/module-signing.txt new file +3 -0
+handle the huge numbers involved.
+
+The signature checker in the kernel is capable of handling  

multiple keys of

Documentation/module-signing.txt line 12

Quoted 1 line
Documentation/module-signing.txt new file +1 -0
+either DSA or RSA type, and can support any of MD5, RIPE-MD-160,  

SHA-1,

Documentation/module-signing.txt line 13

Quoted 1 line
Documentation/module-signing.txt new file +1 -0
+SHA-224, SHA-256, SHA-384 and SHA-512 hashes - PROVIDED(!) the  

requisite

Documentation/module-signing.txt

Quoted 3 lines
Documentation/module-signing.txt new file +3 -0
+algorithms are compiled into the kernel.
+
+(!) NOTE: Modules may only be verified initially with algorithms  

compiled into

Documentation/module-signing.txt line 17

Quoted 1 line
Documentation/module-signing.txt new file +1 -0
+the kernel.  Further algorithm modules may be loaded and used -  

but these must

Documentation/module-signing.txt line 18

Quoted 1 line
Documentation/module-signing.txt new file +1 -0
+first pass a verification step using already loaded/compiled-in  

algorithms.

Documentation/module-signing.txt

Quoted 7 lines
Documentation/module-signing.txt new file +7 -0
+
+
+=====================
+SUPPLYING PUBLIC KEYS
+=====================
+
+A set of public keys must be supplied at kernel image build time.   

This is done

Documentation/module-signing.txt line 26

Quoted 1 line
Documentation/module-signing.txt new file +1 -0
+by taking a GPG public key file and placing it in the base of the  

kernel

Documentation/module-signing.txt

Quoted 3 lines
Documentation/module-signing.txt new file +3 -0
+directory in a file called modsign.pub.
+
+For example, a throwaway key could be generated automatically by  

something like

Quoted 4 lines
Documentation/module-signing.txt new file +4 -0
+the following:
+
+       cat >genkey <<EOF
+       %pubring modsign.pub

Documentation/module-signing.txt

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

Documentation/module-signing.txt line 44

Quoted 1 line
Documentation/module-signing.txt new file +1 -0
+in /dev/random, more can be provided using the rngd program if  

there's a

Documentation/module-signing.txt line 47

Quoted 3 lines
Documentation/module-signing.txt new file +3 -0
+hardware random number generator available.
+
+Note that no GPG password is used in the above scriptlet.

This is inaccurate and doesn't match how module signing is done today.
The document you have here is a weird mix of the old RHEL style GPG
signing and the current appended-signature x509 certificate signing.

Quoted 4 lines

It needs to be updated to match the fact that x509 keys and signatures are used now.

josh

What's the current status of this? I'm collating my Documentation patch stack to submit upstream, and this is the most recent message on this one?

(Googling for Documentation/module-signing.txt brings up dhowells tree on googlesource.com, so presumably something could be fished out of that, but maybe it's going upstream via Rusty's tree, or...?)

*shrug* Just trying to keep tabs...

Rob

reviewer
#3 lore raw
Quoted 76 lines · Rob Landley
Quoted 75 lines · Josh Boyer
Quoted 5 lines · James Solner

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.

Nak. Please see below.

Quoted 48 lines
---
 Documentation/module-signing.txt | 182 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 182 insertions(+)
 create mode 100644 Documentation/module-signing.txt
Documentation/module-signing.txt new file +37 -0
new file mode 100644
index 0000000..b21e1f1
@@ -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

Documentation/module-signing.txt line 47

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

This is inaccurate and doesn't match how module signing is done today.
The document you have here is a weird mix of the old RHEL style GPG
signing and the current appended-signature x509 certificate signing.

It needs to be updated to match the fact that x509 keys and signatures are used now.

Quoted 7 lines
Quoted 1 line

josh

What's the current status of this? I'm collating my Documentation patch stack to submit upstream, and this is the most recent message on this one?

(Googling for Documentation/module-signing.txt brings up dhowells tree on googlesource.com, so presumably something could be fished out of that, but maybe it's going upstream via Rusty's tree, or...?)

*shrug* Just trying to keep tabs...

There was a new version posted earlier today:
http://marc.info/?l=linux-kernel&m=138369435917393&w=2

It still needs to be cleaned up IMO.

Signature · 1 line
~Randy
#4 lore raw
Quoted 11 lines · Randy Dunlap
Quoted 2 lines · Rob Landley
Quoted 1 line · Josh Boyer

On Thu, Oct 24, 2013 at 6:35 PM, James Solner

Quoted 7 lines · <[email protected]> wrote:
Quoted 7 lines
Quoted 5 lines

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.

Nak. Please see below.

...

Quoted 5 lines

There was a new version posted earlier today:
http://marc.info/?l=linux-kernel&m=138369435917393&w=2

It still needs to be cleaned up IMO.

Is there any place other than the top level Documentation directory to put it? (Start a modules subdirectory, maybe?)

Rob