Chapter 3. Signing a kernel and modules for Secure Boot You can enhance the security of your system by using a signed kernel and signed kernel modules. On UEFI-based build systems where Secure Boot is enabled, you can self-sign a privately built kernel or kernel modules. Furthermore, you can import your public key into a target system where you want to deploy your kernel or kernel modules. If Secure Boot is enabled, all of the following components have to be signed with a private key and authenticated with the corresponding public key: UEFI operating system boot loader The Red Hat Enterprise Linux kernel All kernel modules If any of these components are not signed and authenticated, the system cannot finish the booting process. RHEL 8 includes: Signed boot loaders Signed kernels Signed kernel modules In addition, the signed first-stage boot loader and the signed kernel include embedded Red Hat public keys. These signed executable binaries and embedded keys enable RHEL 8 to install, boot, and run with the Microsoft UEFI Secure Boot Certification Authority keys. These keys are provided by the UEFI firmware on systems that support UEFI Secure Boot. Note Not all UEFI-based systems include support for Secure Boot. The build system, where you build and sign your kernel module, does not need to have UEFI Secure Boot enabled and does not even need to be a UEFI-based system. 3.1. Prerequisites To be able to sign externally built kernel modules, install the utilities from the following packages: 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 3.2. What is UEFI Secure Boot With the Unified Extensible Firmware Interface (UEFI) Secure Boot technology, you can prevent the execution of the kernel-space code that is not signed by a trusted key. The system boot loader is signed with a cryptographic key. The database of public keys in the firmware authorizes the process of signing the key. You can subsequently verify a signature in the -stage boot loader and the kernel. UEFI Secure Boot establishes a chain of trust from the firmware to the signed drivers and kernel modules as follows: 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. Secure Boot is the boot path validation component of the UEFI specification. The specification defines: 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. UEFI Secure Boot helps in the detection of unauthorized changes but does not : 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. If the boot loader or the kernel are not signed by a system trusted key, Secure Boot prevents them from starting. 3.3. UEFI Secure Boot support You can install and run RHEL 8 on systems with enabled UEFI Secure Boot if the kernel and all the loaded drivers are signed with a trusted key. Red Hat provides kernels and drivers that are signed and authenticated by the relevant Red Hat keys. If you want to load externally built kernels or drivers, you must sign them as well. 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 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. Additional resources Restrictions Imposed by UEFI Secure Boot 3.4. Requirements for authenticating kernel modules with X.509 keys In RHEL 8, when a kernel module is loaded, the kernel checks the signature of the module against the public X.509 keys from the kernel system keyring ( .builtin_trusted_keys ) and the kernel platform keyring ( .platform ). The .platform keyring provides keys from third-party platform providers and custom public keys. The keys from the kernel system .blacklist keyring are excluded from verification. You need to meet certain conditions to load kernel modules on systems with enabled UEFI Secure Boot functionality: 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. Table 3.2. Kernel module authentication requirements for loading Module signed Public key found and signature valid UEFI Secure Boot state sig_enforce Module load Kernel tainted Unsigned - Not enabled Not enabled Succeeds Yes Not enabled Enabled Fails - Enabled - Fails - Signed No Not enabled Not enabled Succeeds Yes Not enabled Enabled Fails - Enabled - Fails - Signed Yes Not enabled Not enabled Succeeds No Not enabled Enabled Succeeds No Enabled - Succeeds No 3.5. Sources for public keys During boot, the kernel loads X.509 keys from a set of persistent key stores into the following keyrings: The system keyring ( .builtin_trusted_keys ) The .platform keyring The system .blacklist keyring Table 3.3. Sources for system keyrings Source of X.509 keys User can add keys UEFI Secure Boot state Keys loaded during boot Embedded in kernel No - .builtin_trusted_keys UEFI db Limited Not enabled No Enabled .platform Embedded in the shim boot loader No Not enabled No Enabled .platform Machine Owner Key (MOK) list Yes Not enabled No Enabled .platform .builtin_trusted_keys A keyring that is built on boot. Provides trusted public keys. root privileges are required to view the keys. .platform A keyring that is built on boot. Provides keys from third-party platform providers and custom public keys. root privileges are required to view the keys. .blacklist A keyring with X.509 keys which have been revoked. A module signed by a key from .blacklist will fail authentication even if your public key is in .builtin_trusted_keys . UEFI Secure Boot db A signature database. Stores keys (hashes) of UEFI applications, UEFI drivers, and boot loaders. The keys can be loaded on the machine. UEFI Secure Boot dbx A revoked signature database. Prevents keys from getting loaded. The revoked keys from this database are added to the .blacklist keyring. 3.6. Generating a public and private key pair To use a custom kernel or custom kernel modules on a Secure Boot-enabled system, you must generate a public and private X.509 key pair. You can use the generated private key to sign the kernel or the kernel modules. You can also validate the signed kernel or kernel modules by adding the corresponding public key to the Machine Owner Key (MOK) for Secure Boot. Warning Apply strong security measures and access policies to guard the contents of your private key. In the wrong hands, the key could be used to compromise any system which is authenticated by the corresponding public key. Procedure Create an X.509 public and private key pair: If you only want to sign custom kernel modules : If you want to sign custom kernel : When the RHEL system is running FIPS mode: 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. Important It is a good security practice to sign the kernel and the kernel modules within the validity period of its signing key. However, the sign-file utility does not warn you and the key will be usable in RHEL 8 regardless of the validity dates. Additional resources openssl(1) manual page RHEL Security Guide Enrolling public key on target system by adding the public key to the MOK list 3.7. Example output of system keyrings You can display information about the keys on the system keyrings using the keyctl utility from the keyutils package. Prerequisites You have root permissions. You have installed the keyctl utility from the keyutils package. Example 3.1. Keyrings output The following is a shortened example output of .builtin_trusted_keys , .platform , and .blacklist keyrings from a RHEL 8 system where UEFI Secure Boot is enabled. The .builtin_trusted_keys keyring in the example shows the addition of two keys from the UEFI Secure Boot db keys as well as the Red Hat Secure Boot (CA key 1) , which is embedded in the shim boot loader. Example 3.2. Kernel console output The following example shows the kernel console output. The messages identify the keys with an UEFI Secure Boot related source. These include UEFI Secure Boot db , embedded shim , and MOK list. Additional resources keyctl(1) , dmesg(1) manual pages 3.8. Enrolling public key on target system by adding the public key to the MOK list You must authenticate your public key on a system for kernel or kernel module access and enroll it in the platform keyring ( .platform ) of the target system. When RHEL 8 boots on a UEFI-based system with Secure Boot enabled, the kernel imports public keys from the db key database and excludes revoked keys from the dbx database. The Machine Owner Key (MOK) facility allows expanding the UEFI Secure Boot key database. When booting RHEL 8 on UEFI-enabled systems with Secure Boot enabled, keys on the MOK list are added to the platform keyring ( .platform ), along with the keys from the Secure Boot database. The list of MOK keys is stored securely and persistently in the same way, but it is a separate facility from the Secure Boot databases. The MOK facility is supported by shim , MokManager , GRUB , and the mokutil utility that enables secure key management and authentication for UEFI-based systems. Note To get the authentication service of your kernel module on your systems, consider requesting your system vendor to incorporate your public key into the UEFI Secure Boot key database in their factory firmware image. 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 . Procedure Export your public key to the sb_cert.cer file: Import your public key into the MOK list: Enter a new password for this MOK enrollment request. Reboot the machine. The shim boot loader notices the pending MOK key enrollment request and it launches MokManager.efi to enable you to complete the enrollment from the UEFI console. Choose Enroll MOK , enter the password you previously associated with this request when prompted, and confirm the enrollment. Your public key is added to the MOK list, which is persistent. Once a key is on the MOK list, it will be automatically propagated to the .platform keyring on this and subsequent boots when UEFI Secure Boot is enabled. 3.9. Signing a kernel with the private key You can obtain enhanced security benefits on your system by loading a signed kernel if the UEFI Secure Boot mechanism is enabled. 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: Create a signed image: Replace version with the version suffix of your vmlinuz file, and Custom Secure Boot key with the name that you chose earlier. Optional: Check the signatures: Overwrite the unsigned image with the signed image: On the 64-bit ARM architecture: Decompress the vmlinuz file: Create a signed image: Optional: Check the signatures: Compress the vmlinux file: Remove the uncompressed vmlinux file: 3.10. Signing a GRUB build with the private key On a system where the UEFI Secure Boot mechanism is enabled, you can sign a GRUB build with a custom existing private key. You must do this if you are using a custom GRUB build, or if you have removed the Microsoft trust anchor from your system. 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: Create a signed GRUB EFI binary: Replace Custom Secure Boot key with the name that you chose earlier. Optional: Check the signatures: Overwrite the unsigned binary with the signed binary: On the 64-bit ARM architecture: Create a signed GRUB EFI binary: Replace Custom Secure Boot key with the name that you chose earlier. Optional: Check the signatures: Overwrite the unsigned binary with the signed binary: 3.11. Signing kernel modules with the private key You can enhance the security of your system by loading signed kernel modules if the UEFI Secure Boot mechanism is enabled. Your signed kernel module is also loadable on systems where UEFI Secure Boot is disabled or on a non-UEFI system. As a result, you do not need to provide both, a signed and unsigned version of your kernel module. 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. Procedure Export your public key to the sb_cert.cer file: Extract the key from the NSS database as a PKCS #12 file: When the command prompts, enter a new password that encrypts the private key. Export the unencrypted private key: Important Keep the unencrypted private key secure. Sign your kernel module. The following command appends the signature directly to the ELF image in your kernel module file: Your kernel module is now ready for loading. Important In RHEL 8, the validity dates of the key pair matter. The key does not expire, but the kernel module must be signed within the validity period of its signing key. The sign-file utility will not warn you of this. For example, a key that is only valid in 2019 can be used to authenticate a kernel module signed in 2019 with that key. However, users cannot use that key to sign a kernel module in 2020. Verification Display information about the kernel module's signature: Check that the signature lists your name as entered during generation. Note The appended signature is not contained in an ELF image section and is not a formal part of the ELF image. Therefore, utilities such as readelf cannot display the signature on your kernel module. Load the module: Remove (unload) the module: Additional resources Displaying information about kernel modules 3.12. Loading signed kernel modules After enrolling your public key in the system keyring ( .builtin_trusted_keys ) and the MOK list, and signing kernel modules with your private key, you can load them using the modprobe command. 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/USD(uname -r)/extra/ directory: Procedure Verify that your public keys are on the system keyring: Copy the kernel module into the extra/ directory of the kernel that you want: Update the modular dependency list: Load the kernel module: Optional: To load the module on boot, add it to the /etc/modules-loaded.d/ my_module .conf file: Verification Verify that the module was successfully loaded: Additional resources Managing kernel modules

Commands:
yum install pesign openssl kernel-devel mokutil keyutils
efikeygen --dbdir /etc/pki/pesign --self-sign --module --common-name 'CN= Organization signing key ' --nickname ' Custom Secure Boot key '
efikeygen --dbdir /etc/pki/pesign --self-sign --kernel --common-name 'CN= Organization signing key ' --nickname ' Custom Secure Boot key '
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'
keyctl list %:.builtin_trusted_keys 6 keys in keyring: ...asymmetric: Red Hat Enterprise Linux Driver Update Program (key 3): bf57f3e87 ...asymmetric: Red Hat Secure Boot (CA key 1): 4016841644ce3a810408050766e8f8a29 ...asymmetric: Microsoft Corporation UEFI CA 2011: 13adbf4309bd82709c8cd54f316ed ...asymmetric: Microsoft Windows Production PCA 2011: a92902398e16c49778cd90f99e ...asymmetric: Red Hat Enterprise Linux kernel signing key: 4249689eefc77e95880b ...asymmetric: Red Hat Enterprise Linux kpatch signing key: 4d38fd864ebe18c5f0b7 keyctl list %:.platform 4 keys in keyring: ...asymmetric: VMware, Inc.: 4ad8da0472073 ...asymmetric: Red Hat Secure Boot CA 5: cc6fafe72 ...asymmetric: Microsoft Windows Production PCA 2011: a929f298e1 ...asymmetric: Microsoft Corporation UEFI CA 2011: 13adbf4e0bd82 keyctl list %:.blacklist 4 keys in keyring: ...blacklist: bin:f5ff83a ...blacklist: bin:0dfdbec ...blacklist: bin:38f1d22 ...blacklist: bin:51f831f
dmesg | egrep 'integrity.*cert' [1.512966] integrity: Loading X.509 certificate: UEFI:db [1.513027] integrity: Loaded X.509 cert 'Microsoft Windows Production PCA 2011: a929023 [1.513028] integrity: Loading X.509 certificate: UEFI:db [1.513057] integrity: Loaded X.509 cert 'Microsoft Corporation UEFI CA 2011: 13adbf4309 [1.513298] integrity: Loading X.509 certificate: UEFI:MokListRT (MOKvar table) [1.513549] integrity: Loaded X.509 cert 'Red Hat Secure Boot CA 5: cc6fa5e72868ba494e93
certutil -d /etc/pki/pesign -n ' Custom Secure Boot key ' -Lr > sb_cert.cer
mokutil --import sb_cert.cer
pesign --certificate ' Custom Secure Boot key ' --in vmlinuz- version --sign --out vmlinuz- version .signed
pesign --show-signature --in vmlinuz- version .signed
mv vmlinuz- version .signed vmlinuz- version
zcat vmlinuz- version > vmlinux- version
pesign --certificate ' Custom Secure Boot key ' --in vmlinux- version --sign --out vmlinux- version .signed
pesign --show-signature --in vmlinux- version .signed
gzip --to-stdout vmlinux- version .signed > vmlinuz- version
rm vmlinux- version *
pesign --in /boot/efi/EFI/redhat/grubx64.efi --out /boot/efi/EFI/redhat/grubx64.efi.signed --certificate ' Custom Secure Boot key ' --sign
pesign --in /boot/efi/EFI/redhat/grubx64.efi.signed --show-signature
mv /boot/efi/EFI/redhat/grubx64.efi.signed /boot/efi/EFI/redhat/grubx64.efi
pesign --in /boot/efi/EFI/redhat/grubaa64.efi --out /boot/efi/EFI/redhat/grubaa64.efi.signed --certificate ' Custom Secure Boot key ' --sign
pesign --in /boot/efi/EFI/redhat/grubaa64.efi.signed --show-signature
mv /boot/efi/EFI/redhat/grubaa64.efi.signed /boot/efi/EFI/redhat/grubaa64.efi
certutil -d /etc/pki/pesign -n ' Custom Secure Boot key ' -Lr > sb_cert.cer
pk12util -o sb_cert.p12 -n ' Custom Secure Boot key ' -d /etc/pki/pesign
openssl pkcs12 -in sb_cert.p12 -out sb_cert.priv -nocerts -nodes
/usr/src/kernels/USD(uname -r)/scripts/sign-file sha256 sb_cert.priv sb_cert.cer my_module .ko
modinfo my_module .ko | grep signer signer: Your Name Key
insmod my_module .ko
modprobe -r my_module .ko
yum -y install kernel-modules-extra
keyctl list %:.platform
cp my_module .ko /lib/modules/USD(uname -r)/extra/
depmod -a
modprobe -v my_module
echo " my_module " > /etc/modules-load.d/ my_module .conf
lsmod | grep my_module