Documentation/module-signing.txt: convert to ReST markup
- Fix identatio for the document title; - remove its index; - create a table for hash algorithm to be used; - use quote blocks where needed; - use monotonic fonts for parameters; - adjust whitespaces and blank lines; - Fix case on section titles; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
This commit is contained in:
Mauro Carvalho Chehab
parent
aeb04e52f1
commit
94e980cc45
@ -1,22 +1,21 @@
|
||||
==============================
|
||||
KERNEL MODULE SIGNING FACILITY
|
||||
==============================
|
||||
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.
|
||||
.. 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
|
||||
Overview
|
||||
========
|
||||
|
||||
The kernel module signing facility cryptographically signs modules during
|
||||
@ -36,17 +35,19 @@ SHA-512 (the algorithm is selected by data in the signature).
|
||||
|
||||
|
||||
==========================
|
||||
CONFIGURING MODULE SIGNING
|
||||
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
|
||||
The module signing facility is enabled by going to the
|
||||
:menuselection:`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)
|
||||
(1) :menuselection:`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.
|
||||
@ -64,35 +65,39 @@ This has a number of options available:
|
||||
cannot be parsed, it will be rejected out of hand.
|
||||
|
||||
|
||||
(2) "Automatically sign all modules" (CONFIG_MODULE_SIG_ALL)
|
||||
(2) :menuselection:`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:
|
||||
be signed manually using::
|
||||
|
||||
scripts/sign-file
|
||||
|
||||
|
||||
(3) "Which hash algorithm should modules be signed with?"
|
||||
(3) :menuselection:`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_MODULE_SIG_SHA1 "Sign modules with SHA-1"
|
||||
CONFIG_MODULE_SIG_SHA224 "Sign modules with SHA-224"
|
||||
CONFIG_MODULE_SIG_SHA256 "Sign modules with SHA-256"
|
||||
CONFIG_MODULE_SIG_SHA384 "Sign modules with SHA-384"
|
||||
CONFIG_MODULE_SIG_SHA512 "Sign modules with SHA-512"
|
||||
=============================== ==========================================
|
||||
``CONFIG_MODULE_SIG_SHA1`` :menuselection:`Sign modules with SHA-1`
|
||||
``CONFIG_MODULE_SIG_SHA224`` :menuselection:`Sign modules with SHA-224`
|
||||
``CONFIG_MODULE_SIG_SHA256`` :menuselection:`Sign modules with SHA-256`
|
||||
``CONFIG_MODULE_SIG_SHA384`` :menuselection:`Sign modules with SHA-384`
|
||||
``CONFIG_MODULE_SIG_SHA512`` :menuselection:`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.
|
||||
|
||||
|
||||
(4) "File name or PKCS#11 URI of module signing key" (CONFIG_MODULE_SIG_KEY)
|
||||
(4) :menuselection:`File name or PKCS#11 URI of module signing key`
|
||||
(``CONFIG_MODULE_SIG_KEY``)
|
||||
|
||||
Setting this option to something other than its default of
|
||||
"certs/signing_key.pem" will disable the autogeneration of signing keys
|
||||
``certs/signing_key.pem`` will disable the autogeneration of signing keys
|
||||
and allow the kernel modules to be signed with a key of your choosing.
|
||||
The string provided should identify a file containing both a private key
|
||||
and its corresponding X.509 certificate in PEM form, or — on systems where
|
||||
@ -102,10 +107,11 @@ This has a number of options available:
|
||||
|
||||
If the PEM file containing the private key is encrypted, or if the
|
||||
PKCS#11 token requries a PIN, this can be provided at build time by
|
||||
means of the KBUILD_SIGN_PIN variable.
|
||||
means of the ``KBUILD_SIGN_PIN`` variable.
|
||||
|
||||
|
||||
(5) "Additional X.509 keys for default system keyring" (CONFIG_SYSTEM_TRUSTED_KEYS)
|
||||
(5) :menuselection:`Additional X.509 keys for default system keyring`
|
||||
(``CONFIG_SYSTEM_TRUSTED_KEYS``)
|
||||
|
||||
This option can be set to the filename of a PEM-encoded file containing
|
||||
additional certificates which will be included in the system keyring by
|
||||
@ -116,7 +122,7 @@ packages to the kernel build processes for the tool that does the signing.
|
||||
|
||||
|
||||
=======================
|
||||
GENERATING SIGNING KEYS
|
||||
Generating signing keys
|
||||
=======================
|
||||
|
||||
Cryptographic keypairs are required to generate and check signatures. A
|
||||
@ -126,14 +132,14 @@ it can be deleted or stored securely. The public key gets built into the
|
||||
kernel so that it can be used to check the signatures as the modules are
|
||||
loaded.
|
||||
|
||||
Under normal conditions, when CONFIG_MODULE_SIG_KEY is unchanged from its
|
||||
Under normal conditions, when ``CONFIG_MODULE_SIG_KEY`` is unchanged from its
|
||||
default, the kernel build will automatically generate a new keypair using
|
||||
openssl if one does not exist in the file:
|
||||
openssl if one does not exist in the file::
|
||||
|
||||
certs/signing_key.pem
|
||||
|
||||
during the building of vmlinux (the public part of the key needs to be built
|
||||
into vmlinux) using parameters in the:
|
||||
into vmlinux) using parameters in the::
|
||||
|
||||
certs/x509.genkey
|
||||
|
||||
@ -142,14 +148,14 @@ file (which is also generated if it does not already exist).
|
||||
It is strongly recommended that you provide your own x509.genkey file.
|
||||
|
||||
Most notably, in the x509.genkey file, the req_distinguished_name section
|
||||
should be altered from the default:
|
||||
should be altered from the default::
|
||||
|
||||
[ req_distinguished_name ]
|
||||
#O = Unspecified company
|
||||
CN = Build time autogenerated kernel key
|
||||
#emailAddress = unspecified.user@unspecified.company
|
||||
|
||||
The generated RSA key size can also be set with:
|
||||
The generated RSA key size can also be set with::
|
||||
|
||||
[ req ]
|
||||
default_bits = 4096
|
||||
@ -158,23 +164,23 @@ The generated RSA key size can also be set with:
|
||||
It is also possible to manually generate the key private/public files using 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:
|
||||
generate the public/private key files::
|
||||
|
||||
openssl req -new -nodes -utf8 -sha256 -days 36500 -batch -x509 \
|
||||
-config x509.genkey -outform PEM -out kernel_key.pem \
|
||||
-keyout kernel_key.pem
|
||||
|
||||
The full pathname for the resulting kernel_key.pem file can then be specified
|
||||
in the CONFIG_MODULE_SIG_KEY option, and the certificate and key therein will
|
||||
in the ``CONFIG_MODULE_SIG_KEY`` option, and the certificate and key therein will
|
||||
be used instead of an autogenerated keypair.
|
||||
|
||||
|
||||
=========================
|
||||
PUBLIC KEYS IN THE KERNEL
|
||||
Public keys in the kernel
|
||||
=========================
|
||||
|
||||
The kernel contains a ring of public keys that can be viewed by root. They're
|
||||
in a keyring called ".system_keyring" that can be seen by:
|
||||
in a keyring called ".system_keyring" that can be seen by::
|
||||
|
||||
[root@deneb ~]# cat /proc/keys
|
||||
...
|
||||
@ -184,27 +190,27 @@ in a keyring called ".system_keyring" that can be seen by:
|
||||
|
||||
Beyond the public key generated specifically for module signing, additional
|
||||
trusted certificates can be provided in a PEM-encoded file referenced by the
|
||||
CONFIG_SYSTEM_TRUSTED_KEYS configuration option.
|
||||
``CONFIG_SYSTEM_TRUSTED_KEYS`` configuration option.
|
||||
|
||||
Further, the architecture code may take public keys from a hardware store and
|
||||
add those in also (e.g. from the UEFI key database).
|
||||
|
||||
Finally, it is possible to add additional public keys by doing:
|
||||
Finally, it is possible to add additional public keys by doing::
|
||||
|
||||
keyctl padd asymmetric "" [.system_keyring-ID] <[key-file]
|
||||
|
||||
e.g.:
|
||||
e.g.::
|
||||
|
||||
keyctl padd asymmetric "" 0x223c7853 <my_public_key.x509
|
||||
|
||||
Note, however, that the kernel will only permit keys to be added to
|
||||
.system_keyring _if_ the new key's X.509 wrapper is validly signed by a key
|
||||
``.system_keyring _if_`` the new key's X.509 wrapper is validly signed by a key
|
||||
that is already resident in the .system_keyring at the time the key was added.
|
||||
|
||||
|
||||
=========================
|
||||
MANUALLY SIGNING MODULES
|
||||
=========================
|
||||
========================
|
||||
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:
|
||||
@ -214,7 +220,7 @@ the Linux kernel source tree. The script requires 4 arguments:
|
||||
3. The public key filename
|
||||
4. The kernel module to be signed
|
||||
|
||||
The following is an example to sign a kernel module:
|
||||
The following is an example to sign a kernel module::
|
||||
|
||||
scripts/sign-file sha512 kernel-signkey.priv \
|
||||
kernel-signkey.x509 module.ko
|
||||
@ -228,11 +234,11 @@ $KBUILD_SIGN_PIN environment variable.
|
||||
|
||||
|
||||
============================
|
||||
SIGNED MODULES AND STRIPPING
|
||||
Signed modules and stripping
|
||||
============================
|
||||
|
||||
A signed module has a digital signature simply appended at the end. The string
|
||||
"~Module signature appended~." at the end of the module's file confirms that a
|
||||
``~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
|
||||
@ -242,19 +248,19 @@ debug information present at the time of signing.
|
||||
|
||||
|
||||
======================
|
||||
LOADING SIGNED MODULES
|
||||
Loading signed modules
|
||||
======================
|
||||
|
||||
Modules are loaded with insmod, modprobe, init_module() or finit_module(),
|
||||
exactly as for unsigned modules as no processing is done in userspace. The
|
||||
signature checking is all done within the kernel.
|
||||
Modules are loaded with insmod, modprobe, ``init_module()`` or
|
||||
``finit_module()``, exactly as for unsigned modules as no processing is
|
||||
done in userspace. The signature checking is all done within the kernel.
|
||||
|
||||
|
||||
=========================================
|
||||
NON-VALID SIGNATURES AND UNSIGNED MODULES
|
||||
Non-valid signatures and unsigned modules
|
||||
=========================================
|
||||
|
||||
If CONFIG_MODULE_SIG_FORCE is enabled or module.sig_enforce=1 is supplied on
|
||||
If ``CONFIG_MODULE_SIG_FORCE`` is enabled or module.sig_enforce=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
|
||||
@ -264,7 +270,7 @@ Any module that has an unparseable signature will be rejected.
|
||||
|
||||
|
||||
=========================================
|
||||
ADMINISTERING/PROTECTING THE PRIVATE KEY
|
||||
Administering/protecting the private key
|
||||
=========================================
|
||||
|
||||
Since the private key is used to sign modules, viruses and malware could use
|
||||
@ -275,5 +281,5 @@ in the root node of the kernel source tree.
|
||||
If you use the same private key to sign modules for multiple kernel
|
||||
configurations, you must ensure that the module version information is
|
||||
sufficient to prevent loading a module into a different kernel. Either
|
||||
set CONFIG_MODVERSIONS=y or ensure that each configuration has a different
|
||||
kernel release string by changing EXTRAVERSION or CONFIG_LOCALVERSION.
|
||||
set ``CONFIG_MODVERSIONS=y`` or ensure that each configuration has a different
|
||||
kernel release string by changing ``EXTRAVERSION`` or ``CONFIG_LOCALVERSION``.
|
||||
Loading…
Reference in New Issue
Block a user