Adding Documentation/module-signing.txt file
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
@@ -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 ---
Quoted 5 lines · James Solner
This patch adds the
Documentation/module-signing.txtfile that is missing. There is a link toDocumentation/module-signing.txtfile in init/Kconfig that references this file.Signed-off-by James Solner <[email protected]>
Nak. Please see below.
Quoted 48 lines
--- Documentation/module-signing.txt | 182 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 Documentation/module-signing.txtDocumentation/module-signing.txt new file +37
-0@@ -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
Quoted 89 lines · Josh Boyer
Quoted 5 lines · James Solner
This patch adds the
Documentation/module-signing.txtfile that is missing. There is a link toDocumentation/module-signing.txtfile in init/Kconfig that references this file.Signed-off-by James Solner <[email protected]>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.txtDocumentation/module-signing.txt line 5
Quoted 10 lines
new file mode 100644
index 0000000..b21e1f1Documentation/module-signing.txt new file +5
-0@@ -0,0 +1,182 @@ + ============================== + KERNEL MODULE SIGNING FACILITY + ============================== + +The module signing facility applies cryptographic signaturechecking 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 publickeys 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 anddetermines 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'sMPI 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 handlingmultiple 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(!) therequisite
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 algorithmscompiled 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-inalgorithms.
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 thekernel
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 bysomething like
Quoted 4 lines
Documentation/module-signing.txt new file +4
-0+the following: + + cat >genkey <<EOF + %pubring modsign.pubDocumentation/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'sinsufficient 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 ifthere'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
Randy Dunlap
reviewerQuoted 76 lines · Rob Landley
Quoted 75 lines · Josh Boyer
Quoted 5 lines · James Solner
This patch adds the
Documentation/module-signing.txtfile that is missing. There is a link toDocumentation/module-signing.txtfile in init/Kconfig that references this file.Signed-off-by James Solner <[email protected]>Nak. Please see below.
Quoted 48 lines
--- Documentation/module-signing.txt | 182 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 Documentation/module-signing.txtDocumentation/module-signing.txt new file +37
-0@@ -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. OtherDocumentation/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.txtbrings 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
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.txtfile that is missing. There is a link toDocumentation/module-signing.txtfile in init/Kconfig that references this file.Signed-off-by James Solner <[email protected]>Nak. Please see below.
...
Quoted 5 lines
There was a new version posted earlier today:
http://marc.info/?l=linux-kernel&m=138369435917393&w=2It 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