Skip to content

Tools to support Signed Kernel Modules with DKMS in Arch Linux

License

Notifications You must be signed in to change notification settings

itoffshore/Arch-SKM

 
 

Repository files navigation

shellcheck Pylint

🔒 Arch Linux Sign Modules:


Automated Linux kernel building with Signed Kernel Modules (In Tree & Out of Tree) for:

  • linux
  • linux-lts
  • linux-hardened
  • linux-hardened-git
  • linux-zen
  • linux-rt
  • linux-amd
  • linux-ck
  • linux-libre
  • linux-xanmod
  • AUR kernels

With DKMS support for the following Out of Tree Kernel Modules:


This AUR Package arch-sign-modules provides the abk helper script for Gene's Arch-SKM & packages his python scripts.

  • Gene's original manual steps are set out further below in the context of building officially supported Arch Linux kernels.
  • See also Gene's README for technical details of his Signed Kernel Module implementation.
  • Kernel modules are now signed with ECDSA signatures in pure python.

abk reduces the manual steps for building a fully signed custom kernel to 3 commands to Update / Build & Install the kernel:

abk -u kernel-name
abk -b kernel-name
abk -i kernel-name

Since abk version 0.3.2 the initial update stage will first try to automatically update a PKGBUILD for officially supported kernels (& some AUR kernels):

Automated Upgrade

Now that automated mode is well tested abk version 0.4+ can be run on headless systems.

If a patch cannot be applied cleanly abk will fall back to the original manual mode & generate a new patch:


🔒 Signed Kernel Modules:


Signed kernel modules provide a mechanism for the kernel to verify the integrity of a module. This provides the tools needed to build a kernel with support for signed modules.

Contents

1 Introduction
2 How to sign kernel modules using a custom kernel
3 Summary of what needs to be done
4 Kernel configuration
    4.1 Kernel command line
5 Tools needed
    5.1 kernel build package
    5.2 dkms support
6 Modify PKGBUILD
    6.1 prepare()
    6.2 _package-headers()
7 Files Required
    7.1 certs-local/x509.oot.genkey
    7.2 certs-local/genkeys.py
    7.3 certs-local/sign_manual.sh
    7.4 certs-local/dkms/kernel-sign.conf
    7.5 certs-local/dkms/kernel-sign.sh

1. Introduction


The Linux kernel distinguishes and keeps separate the verification of modules from requiring or forcing modules to verify before allowing them to be loaded. Kernel modules fall into 2 classes:

Standard "in tree" modules which come with the kernel source code. They are compiled during the normal kernel build.

Out of tree modules which are not part of the kernel source distribution. They are built outside of the kernel tree, requiring the kernel headers package for each kernel they are to be built for. They can be built manually for a specific kernel and packaged, or they can be built whenever needed using DKMS.

Examples of such packages, provided by Arch, include:

During a standard kernel compilation, the kernel build tools create a private/public key pair and sign every in tree module (using the private key). The public key is saved in the kernel itself. When a module is subsequently loaded, the public key can then be used to verify that the module is unchanged.

The kernel can be enabled to always verify modules and report any failures to standard logs. The choice to permit the loading and use of a module which could not be verified can be either compiled into kernel or turned on at run time using a kernel parameter.


2. How to sign kernel modules using a custom kernel


The starting point is based on a custom kernel package as outlined in this article Kernel/Arch Build System

We will modify the build to:

  • Sign the standard in tree kernel modules
  • Provide what is needed to have signed out of tree modules and for the kernel to verify those modules.

Note: The goal here is to have:

  • In tree modules signed during the standard kernel build process. The standard kernel build creates a fresh public/private key pair on each build.

  • Out of tree modules are signed and the associated public key is compiled in to the kernel. We will create a separate public/private key pair on each build.


3. Summary of what needs to be done


Each kernel build needs to made aware of the key/cert being used. Fresh keys are generated with each new kernel build.

A kernel config parameter is now used to make kernel aware of additional signing key:

CONFIG_SYSTEM_TRUSTED_KEYS="/path/to/oot-signing_keys.pem"

Keys and signing tools will be stored in current module build directory. Nothing needs to be done to clean this as removal is handled by the standard module cleanup. Certs are thus installed in /usr/lib/modules/<kernel-vers>-<build>/certs-local


4. Kernel configuration


CONFIG_SYSTEM_TRUSTED_KEYS will be added automatically as explained below. In addition the following config options should be set by either manually editing the 'config' file, or via make menuconfig in the linux 'src' area and subsequently copying the updated .config file back to the build file config.

  Enable Loadable module suppot --->
  Module Signature Verification           -  activate

        CONFIG_MODULE_SIG=y

  Require modules to be validly signed -> leave off

        CONFIG_MODULE_SIG_FORCE=n

This allows the decision to enforce verified modules only as boot command line. If you are comfortable all is working then by all means change this to 'y'


Automatically sign all modules  - activate
Which hash algorithm    -> SHA-512

Compress modules on installation        - activate
     Compression algorithm (zstd)

Allow loading of modules with missing namespace imports - set to no


4.1 Kernel command line


After you are comfortable things are working well you can enable the kernel parameter to require that the kernel only permit verified modules to be loaded:

module.sig_enforce=1


5. Tools needed


5.1 kernel build package


In the directory where the kernel package is built:

  • mkdir certs-local

This directory will provide the tools to create the keys, as well as signing kernel modules.

  • put the 4 files into certs-local:
genkeys.py
x509.oot.genkey
install-certs.py
sign_module.py

The files genkeys.py and its config x509.oot.genkey are used to create key pairs.

It also provides the kernel with the key to sign the out of tree modules by updating the config file used to build the kernel.

The script sign_module.py is used to sign out of tree kernel modules by hand.

genkeys.py will create the key pairs in a directory named by date-time. It defaults to refreshing the keys every 7 days but this can be changed with a command line option.

It also creates a soft link named 'current' which points to the newly created directory with the 'current' keys.

The actual key directory is named by date and time.

genkeys.py will check and update kernel configs given by the --config config(s) option. This takes either a single config file, or a shell glob for mulitple files. e.g. --config 'conf/config.*'. All configs will be updated with the same key. The default keytype is ec (elliptic curve) and the default hash is sha512. These can be changed with command line options. See genkeys.py -h for more details.

install-certs.py is to be called from the package_headers() function of a PKGBUILD to install the signing keys.

These files are all provided.


5.2 DKMS support


mkdir certs-local/dkms

Add 2 files to the dkms dir:

kernel-sign.conf
kernel-sign.sh

These will be installed in /etc/dkms and provide a mechanism for dkms to automatically sign modules (using the local key above) - this is the reccommended way to sign kernel modules. As explained, below - once this is installed - all that is needed to have dkms automatically sign modules is to make a soft link:

  cd /etc/dkms
  ln -s kernel-sign.conf <package-name>

For example:

ln -s kernel-sign.conf virtualbox

The link creation can easily be added to an Arch Linux package to simplify further if desired.


6. Modify PKGBUILD


6.1 prepare()



6.2 _package-headers()


  • Add the following to the bottom of the _package-headers() function:

  • PKGBUILD example


7. Files Required


These are the 6 supporting files referenced above.

* certs-local/genkeys.py
* certs-local/install-certs.py
* certs-local/x509.oot.genkey
* certs-local/sign_module.py
* certs-local/dkms/kernel-sign.conf
* certs-local/dkms/kernel-sign.sh

❗ Do not forget to make the scripts executable with chmod +x certs-local/*.py