Chapter 3. Signing a kernel and modules for Secure Boot

• To be able to sign externally built kernel modules, install the utilities from the following packages:

  # yum install pesign openssl kernel-devel mokutil keyutils

  Copy to Clipboard Toggle word wrap
  Expand

  Table 3.1. Required utilities

  Utility	Provided by package	Used on	Purpose
  efikeygen	pesign	Build system	Generates public and private X.509 key pair
  openssl	openssl	Build system	Exports the unencrypted private key
  sign-file	kernel-devel	Build system	Executable file used to sign a kernel module with the private key
  mokutil	mokutil	Target system	Optional utility used to manually enroll the public key
  keyctl	keyutils	Target system	Optional utility used to display public keys in the system keyring

  Show more

• An UEFI private key signs, and a public key authenticates the shim first-stage boot loader. A certificate authority (CA) in turn signs the public key. The CA is stored in the firmware database.
• The shim file contains the Red Hat public key Red Hat Secure Boot (CA key 1) to authenticate the GRUB boot loader and the kernel.
• The kernel in turn contains public keys to authenticate drivers and modules.

• Programming interface for cryptographically protected UEFI variables in non-volatile storage.
• Storing the trusted X.509 root certificates in UEFI variables.
• Validation of UEFI applications such as boot loaders and drivers.
• Procedures to revoke known-bad certificates and application hashes.

• Prevent installation or removal of second-stage boot loaders.
• Require explicit user confirmation of such changes.
• Stop boot path manipulations. Signatures are verified during booting but, not when the boot loader is installed or updated.

Restrictions imposed by UEFI Secure Boot

• The system only runs the kernel-mode code after its signature has been properly authenticated.
• GRUB module loading is disabled because no infrastructure exists for signing and verification of GRUB modules. Allowing module loading would run untrusted code within the security perimeter defined by Secure Boot.
• Red Hat provides a signed GRUB binary that has all supported modules on RHEL 8.

• If UEFI Secure Boot is enabled or if the module.sig_enforce kernel parameter has been specified:

  • You can only load those signed kernel modules whose signatures were authenticated against keys from the system keyring (.builtin_trusted_keys) and the platform keyring (.platform).
  • The public key must not be on the system revoked keys keyring (.blacklist).

• If UEFI Secure Boot is disabled and the module.sig_enforce kernel parameter has not been specified:

  • You can load unsigned kernel modules and signed kernel modules without a public key.

• If the system is not UEFI-based or if UEFI Secure Boot is disabled:

  • Only the keys embedded in the kernel are loaded onto .builtin_trusted_keys and .platform.
  • You have no ability to augment that set of keys without rebuilding the kernel.

• The system keyring (.builtin_trusted_keys)
• The .platform keyring
• The system .blacklist keyring

Procedure

• Create an X.509 public and private key pair:

  • If you only want to sign custom kernel modules:

    # efikeygen --dbdir /etc/pki/pesign \
                --self-sign \
                --module \
                --common-name 'CN=Organization signing key' \
                --nickname 'Custom Secure Boot key'

    Copy to Clipboard Toggle word wrap

  • If you want to sign custom kernel:

    # efikeygen --dbdir /etc/pki/pesign \
                --self-sign \
                --kernel \
                --common-name 'CN=Organization signing key' \
                --nickname 'Custom Secure Boot key'

    Copy to Clipboard Toggle word wrap

  • When the RHEL system is running FIPS mode:

    # efikeygen --dbdir /etc/pki/pesign \
                --self-sign \
                --kernel \
                --common-name 'CN=Organization signing key' \
                --nickname 'Custom Secure Boot key'
                --token 'NSS FIPS 140-2 Certificate DB'

    Copy to Clipboard Toggle word wrap
    Note

    In FIPS mode, you must use the --token option so that efikeygen finds the default "NSS Certificate DB" token in the PKI database.

    The public and private keys are now stored in the /etc/pki/pesign/ directory.

Prerequisites

• You have root permissions.
• You have installed the keyctl utility from the keyutils package.

Prerequisites

• You have generated a public and private key pair and know the validity dates of your public keys. For details, see Generating a public and private key pair.

Prerequisites

• You have generated a public and private key pair and know the validity dates of your public keys. For details, see Generating a public and private key pair.
• You have enrolled your public key on the target system. For details, see Enrolling public key on target system by adding the public key to the MOK list.
• You have a kernel image in the ELF format available for signing.

Procedure

• On the x64 architecture:

  1. Create a signed image:

     # pesign --certificate 'Custom Secure Boot key' \
              --in vmlinuz-version \
              --sign \
              --out vmlinuz-version.signed

     Copy to Clipboard Toggle word wrap

     Replace version with the version suffix of your vmlinuz file, and Custom Secure Boot key with the name that you chose earlier.

  2. Optional: Check the signatures:

     # pesign --show-signature \
              --in vmlinuz-version.signed

     Copy to Clipboard Toggle word wrap

  3. Overwrite the unsigned image with the signed image:

     # mv vmlinuz-version.signed vmlinuz-version

     Copy to Clipboard Toggle word wrap

• On the 64-bit ARM architecture:

  1. Decompress the vmlinuz file:

     # zcat vmlinuz-version > vmlinux-version

     Copy to Clipboard Toggle word wrap

  2. Create a signed image:

     # pesign --certificate 'Custom Secure Boot key' \
              --in vmlinux-version \
              --sign \
              --out vmlinux-version.signed

     Copy to Clipboard Toggle word wrap

  3. Optional: Check the signatures:

     # pesign --show-signature \
              --in vmlinux-version.signed

     Copy to Clipboard Toggle word wrap

  4. Compress the vmlinux file:

     # gzip --to-stdout vmlinux-version.signed > vmlinuz-version

     Copy to Clipboard Toggle word wrap

  5. Remove the uncompressed vmlinux file:

     # rm vmlinux-version*

     Copy to Clipboard Toggle word wrap

Prerequisites

• You have generated a public and private key pair and know the validity dates of your public keys. For details, see Generating a public and private key pair.
• You have enrolled your public key on the target system. For details, see Enrolling public key on target system by adding the public key to the MOK list.
• You have a GRUB EFI binary available for signing.

Procedure

• On the x64 architecture:

  1. Create a signed GRUB EFI binary:

     # pesign --in /boot/efi/EFI/redhat/grubx64.efi \
              --out /boot/efi/EFI/redhat/grubx64.efi.signed \
              --certificate 'Custom Secure Boot key' \
              --sign

     Copy to Clipboard Toggle word wrap

     Replace Custom Secure Boot key with the name that you chose earlier.

  2. Optional: Check the signatures:

     # pesign --in /boot/efi/EFI/redhat/grubx64.efi.signed \
              --show-signature

     Copy to Clipboard Toggle word wrap

  3. Overwrite the unsigned binary with the signed binary:

     # mv /boot/efi/EFI/redhat/grubx64.efi.signed \
          /boot/efi/EFI/redhat/grubx64.efi

     Copy to Clipboard Toggle word wrap

• On the 64-bit ARM architecture:

  1. Create a signed GRUB EFI binary:

     # pesign --in /boot/efi/EFI/redhat/grubaa64.efi \
              --out /boot/efi/EFI/redhat/grubaa64.efi.signed \
              --certificate 'Custom Secure Boot key' \
              --sign

     Copy to Clipboard Toggle word wrap

     Replace Custom Secure Boot key with the name that you chose earlier.

  2. Optional: Check the signatures:

     # pesign --in /boot/efi/EFI/redhat/grubaa64.efi.signed \
              --show-signature

     Copy to Clipboard Toggle word wrap

  3. Overwrite the unsigned binary with the signed binary:

     # mv /boot/efi/EFI/redhat/grubaa64.efi.signed \
          /boot/efi/EFI/redhat/grubaa64.efi

     Copy to Clipboard Toggle word wrap

Prerequisites

• You have generated a public and private key pair and know the validity dates of your public keys. For details, see Generating a public and private key pair.
• You have enrolled your public key on the target system. For details, see Enrolling public key on target system by adding the public key to the MOK list.
• You have a kernel module in ELF image format available for signing.

Prerequisites

• You have generated the public and private key pair. For details, see Generating a public and private key pair.
• You have enrolled the public key into the system keyring. For details, see Enrolling public key on target system by adding the public key to the MOK list.
• You have signed a kernel module with the private key. For details, see Signing kernel modules with the private key.

• Install the kernel-modules-extra package, which creates the /lib/modules/$(uname -r)/extra/ directory:

  # yum -y install kernel-modules-extra

  Copy to Clipboard Toggle word wrap

Verification

• Verify that the module was successfully loaded:

  # lsmod | grep my_module

  Copy to Clipboard Toggle word wrap