* [PATCH] Adding Documentation/module-signing.txt file
@ 2013-10-24 22:35 James Solner
2013-10-25 0:08 ` Josh Boyer
0 siblings, 1 reply; 5+ messages in thread
From: James Solner @ 2013-10-24 22:35 UTC (permalink / raw)
To: dhowells, rusty; +Cc: linux-kernel
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 <solner@alcatel-lucent.com>
---
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 0000000..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 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
--
1.7.12.4
---
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH] Adding Documentation/module-signing.txt file
2013-10-24 22:35 [PATCH] Adding Documentation/module-signing.txt file James Solner
@ 2013-10-25 0:08 ` Josh Boyer
2013-11-05 22:54 ` Rob Landley
0 siblings, 1 reply; 5+ messages in thread
From: Josh Boyer @ 2013-10-25 0:08 UTC (permalink / raw)
To: James Solner; +Cc: David Howells, Rusty Russell, Linux-Kernel@Vger. Kernel. Org
On Thu, Oct 24, 2013 at 6:35 PM, James Solner <solner@alcatel-lucent.com> wrote:
> 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 <solner@alcatel-lucent.com>
Nak. Please see below.
> ---
> 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 0000000..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.
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] Adding Documentation/module-signing.txt file
2013-10-25 0:08 ` Josh Boyer
@ 2013-11-05 22:54 ` Rob Landley
2013-11-06 3:31 ` Randy Dunlap
0 siblings, 1 reply; 5+ messages in thread
From: Rob Landley @ 2013-11-05 22:54 UTC (permalink / raw)
To: Josh Boyer
Cc: James Solner, David Howells, Rusty Russell,
Linux-Kernel@Vger. Kernel. Org
On 10/24/2013 07:08:33 PM, Josh Boyer wrote:
> On Thu, Oct 24, 2013 at 6:35 PM, James Solner
> <solner@alcatel-lucent.com> wrote:
> > 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 <solner@alcatel-lucent.com>
>
> Nak. Please see below.
>
> > ---
> > 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 0000000..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.
>
> 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
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] Adding Documentation/module-signing.txt file
2013-11-05 22:54 ` Rob Landley
@ 2013-11-06 3:31 ` Randy Dunlap
2013-11-11 8:14 ` Rob Landley
0 siblings, 1 reply; 5+ messages in thread
From: Randy Dunlap @ 2013-11-06 3:31 UTC (permalink / raw)
To: Rob Landley, Josh Boyer
Cc: James Solner, David Howells, Rusty Russell,
Linux-Kernel@Vger. Kernel. Org
On 11/05/13 14:54, Rob Landley wrote:
> On 10/24/2013 07:08:33 PM, Josh Boyer wrote:
>> On Thu, Oct 24, 2013 at 6:35 PM, James Solner <solner@alcatel-lucent.com> wrote:
>> > 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 <solner@alcatel-lucent.com>
>>
>> Nak. Please see below.
>>
>> > ---
>> > 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 0000000..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.
>>
>> 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
>
> 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.
--
~Randy
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] Adding Documentation/module-signing.txt file
2013-11-06 3:31 ` Randy Dunlap
@ 2013-11-11 8:14 ` Rob Landley
0 siblings, 0 replies; 5+ messages in thread
From: Rob Landley @ 2013-11-11 8:14 UTC (permalink / raw)
To: Randy Dunlap
Cc: Josh Boyer, James Solner, David Howells, Rusty Russell,
Linux-Kernel@Vger. Kernel. Org
On 11/05/2013 09:31:58 PM, Randy Dunlap wrote:
> On 11/05/13 14:54, Rob Landley wrote:
> > On 10/24/2013 07:08:33 PM, Josh Boyer wrote:
> >> On Thu, Oct 24, 2013 at 6:35 PM, James Solner
> <solner@alcatel-lucent.com> wrote:
> >> > 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 <solner@alcatel-lucent.com>
> >>
> >> Nak. Please see below.
...
> 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
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2013-11-11 8:14 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-10-24 22:35 [PATCH] Adding Documentation/module-signing.txt file James Solner
2013-10-25 0:08 ` Josh Boyer
2013-11-05 22:54 ` Rob Landley
2013-11-06 3:31 ` Randy Dunlap
2013-11-11 8:14 ` Rob Landley
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).