==============================
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.
This facility is enabled through CONFIG_MODULE_SIG. Turning on signature
checking will also force the module’s ELF metadata to be verified before the
signature is checked.
=====================
SUPPLYING PUBLIC KEYS
=====================
A set of public keys must be supplied at main kernel compile time. This is
done by taking a GPG public key file, running it through the kernel’s bin2c
program and writing the result over crypto/signature/key.h. To automate this
process, something like this could be done:
cat >genkey <<EOF
%pubring kernel.pub
%secring kernel.sec
Key-Type: DSA
Key-Length: 512
Name-Real: A. N. Other
Name-Comment: Kernel Module GPG key
%commit
EOF
make scripts/bin2c
gpg --homedir . --batch --gen-key genkey
gpg --homedir . --export --keyring kernel.pub keyname |
scripts/bin2c ksign_def_public_key __initdata >crypto/signature/key.h
The above generates fresh keys using /dev/random. If there’s insufficient data
in /dev/random, more can be provided more by running:
rngd -r /dev/urandom
in the background.
Note:
(1) That “keyname” is the name of the key in the keyring. This differentiates
it from any other keys that may be added to the keyring.
(2) That no GPG password is used in the above scriptlet.
==============
MODULE SIGNING
==============
Modules will then be signed automatically. The kernel make command line can
include the following options:
(*) MODSECKEY=
This indicates the whereabouts of the GPG keyring that is the source of
the secret key to be used. The default is "./kernel.sec".
(*) MODPUBKEY=
This indicates the whereabouts of the GPG keyring that is the source of
the public key to be used. The default is "./kernel.pub".
(*) MODKEYNAME=
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
with:
--default-key $(MODKEYNAME)
being added if requested.
The resulting module.ko file will be the signed module.
========================
STRIPPING SIGNED MODULES
========================
Signed modules may be safely stripped as the signature only covers those parts
of the module the kernel actually uses and any ELF metadata required to deal
with them. Any necessary ELF metadata that is affected by stripping is
canonicalised by the sig generator and the sig checker to hide strip effects.
This permits the debuginfo to be detached from the module and placed in another
spot so that gdb can find it when referring to that module without the need for
multiple signed versions of the module. Such is done by rpmbuild when
producing RPMs.
It also permits the module to be stripped as far as possible for when modules
are being reduced prior to being included in an initial ramdisk composition.
======================
LOADING SIGNED MODULES
======================
Modules are loaded with insmod, exactly as for unsigned modules. The signature
is inserted into the module object file as an ELF section called “.module_sig”.
The signature checker will spot it 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 (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
Corrupt signature ELIBBAD ELIBBAD
Corrupt ELF ELIBBAD ELIBBAD
