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

  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

• 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, 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 there is no infrastructure for signing and verification of GRUB modules. Allowing them to be loaded constitutes execution of untrusted code inside the security perimeter that Secure Boot defines.
• Red Hat provides a signed GRUB binary that contains all the supported modules on RHEL 8.

Additional resources

• Restrictions Imposed by UEFI Secure Boot

• 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'

  • 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'

  • 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'

    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

     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

  3. Overwrite the unsigned image with the signed image:

     # mv vmlinuz-version.signed vmlinuz-version

• On the 64-bit ARM architecture:

  1. Decompress the vmlinuz file:

     # zcat vmlinuz-version > vmlinux-version

  2. Create a signed image:

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

  3. Optional: Check the signatures:

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

  4. Compress the vmlinux file:

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

  5. Remove the uncompressed vmlinux file:

     # rm vmlinux-version*

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

     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

  3. Overwrite the unsigned binary with the signed binary:

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

• 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

     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

  3. Overwrite the unsigned binary with the signed binary:

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

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

Verification

• Verify that the module was successfully loaded:

  # lsmod | grep my_module