==============================
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. Currently only RSA keys encoded as X.509 certificates are
supported by the module signature code.
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. A file,
x509.genkey must be provided which is used to generate the X.509 keys. If
not provided, a default configuration will be provided. The Makefile target
“x509.genkey” will generate the example configuration which can be modified
in the top level of the kernel build.
From this, the private and public keys will be generated as ./signing_key.priv
and ./signing_key.x509 respectively during the kernel build process.
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.
==============
MODULE SIGNING
==============
If CONFIG_MODULE_SIG_ALL is set, all modules will be signed automatically. If
not, they can be signed manually using scripts/sign-file:
scripts/sign-file <hash algo> $(MODSECKEY) $(MODPUBKEY) module.ko
(*) The hash algorithm must be one of sha1, sha224, sha256, sha384, sha512.
The corresponding crypto algorithm must be enabled in the kernel.
CONFIG_MODULE_SIG_HASH selects the default algorithm used by sign-file as
part of the kernel build process.
(*) MODSECKEY=
This indicates the whereabouts of the keyring that is the source of
the secret key to be used. The default is "./signing_key.priv".
(*) MODPUBKEY=
This indicates the whereabouts of the keyring that is the source of
the public key to be used. The default is "./signing_key.x509".
The resulting module.ko file will be the signed module.
========================
STRIPPING SIGNED MODULES
========================
Kernel modules must be stripped before they are signed, as stripping a signed
module will remove the appended signature. As a result, care must be taken
when packaging kernel modules for distribution that initrd generation avoids
stripping modules which have signatures.
======================
LOADING SIGNED MODULES
======================
Modules are loaded with insmod, exactly as for unsigned modules. The signature
is appended to the module and the signature checker will spot it and apply
signature checking.
=========================================
NON-VALID SIGNATURES AND UNSIGNED MODULES
=========================================
If CONFIG_MODULE_SIG_FORCE is enabled or “module.sig_enforce” 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 EBADMSG EBADMSG
Corrupt ELF ENOEXEC ENOEXEC
