Use mokutil to Update Signature Keys for UEFI Secure Boot

Before You Begin

This tutorial explains how to use the mokutil tool to update the certificates used for UEFI Secure Boot on Oracle Linux.

Background

A system in Secure Boot mode only loads boot loaders and kernels that have been signed by Oracle. Oracle updates the kernel and grub2 packages to sign them with a valid Extended Validation (EV) certificate in the event that a key may expire or for additional security updates. The EV certificate is compiled into the shim binary and is signed by Microsoft. The UEFI Secure Boot feature is fully supported from Oracle Linux 7 Update 3 onward.

In the case that Oracle updates the EV certificate for a kernel release, or related dependency packages such as grub2 and shim, you may find it difficult to boot older kernels without downgrading packages or without updating the UEFI Secure Boot key database to recognize the certificate or hash for a particular kernel. Kernel UEFI key updates are tracked in the notice at https://docs.oracle.com/en/operating-systems/oracle-linux/notice-secure-boot/.

If you wish to downgrade to an older kernel, you may also need to downgrade any associated packages. If you are changing between kernels frequently, for testing reasons or to debug an issue, you may want to avoid constantly reinstalling the dependency packages. If you wish to update these packages independently so that you can continue to use the newer grub2 and shim packages with an older kernel or vice versa, it is possible to use the Machine Owner Key (MOK) facility to update the UEFI Secure Boot key database and import the keys manually. The MOK facility can also be used to import keys that you use to sign your own development build kernel, so that it is able to boot in UEFI Secure Boot mode. Furthermore, the MOK facility can be used to import keys used to sign third party or custom kernel modules so that these can load while in UEFI Secure Boot mode.

There are two approaches to handling the enrollment of keys within the UEFI Secure Boot key database:

Hash enrollment: The more secure approach is to enroll a hash for a particular kernel binary. You can obtain the hash for any signed kernel using the pesign tool. Use a hash to help prevent potential exploitation by limiting use of the certificate to a specific signed kernel binary. The drawback to this approach is that you must perform these steps for each kernel build or update that you wish to allow. Typical use cases are to allow an older specific kernel to boot to maintain FIPS compatibility or to use an older RHCK after you have upgraded the grub2 and shim packages.

Certificate enrollment: If you have the certificate used to sign the kernel and related packages, you can enroll the certificate within the UEFI Secure Boot key database. The advantage of this approach is that it applies to any kernel that uses the same certificate. This can be useful to rollback to multiple earlier versions of a kernel release. The drawback to this approach is that it can facilitate an exploitation as it potentially enables the user to run a vulnerable grub2 or kernel binary.

Important

Using the MOK utility with your system may depend on server firmware implementation and configuration. Check that your server supports this before attempting to manually update signature keys used for UEFI Secure Boot. If you are unsure, do not follow the instructions provided here.

There are known issues when using the MOK utility with UEK R3. If you are using UEK R3, please do not follow the instructions provided here.

Adding certificates to the UEFI Secure Boot key database by using the MOK utility requires that you have physical access to the system so that you can complete the enrollment request at the UEFI console. If you do not have physical access to the system, do not follow the instructions that are provided here.

You can repeat these steps to import additional signing certificates into the MOK list so that you can use UEFI Secure Boot to boot alternate kernels that are signed with any matching certificate. By importing both certificates into the MOK list, you are able to use UEFI Secure Boot to boot kernels that are signed with either certificate without any requirement to upgrade or downgrade related packages.

Install the mokutil and pesign packages

Install the mokutil and pesign packages. The mokutil package is used to update the MOK list with a certificate or hash. The pesign package is used to sign kernels and tools with a certificate, but it can also extract a hash from a specific kernel, that can then be added to the MOK list.

If you are using Oracle Linux 8:

# dnf install mokutil pesign

If you are using Oracle Linux 7, also, make sure that you have the yum-utils package installed so that you can use the yumdownloader command to download the shim source package.:

# yum install mokutil pesign yum-utils

Enroll a hash for a specific kernel

The pesign command is the tool used to create the shim with Oracle's signed keys, but it can equally be used to create your own shim with your own signed keys if required. In this example, the command is used to extract a padded hash of from a specific signed kernel binary. This hash is imported into the MOK list so that the associated kernel can load at boot time. This approach is more secure than importing an entire certificate into the MOK list as it is restricted to a specific kernel binary.

Import the hash into the MOK list

Use the mokutil command with the pesign command to extract the hash from a selected kernel binary and import it into the MOK list. This can be achieved as a single command. For example to import the hash for the kernel image at /boot/vmlinuz-4.18.0-193.el8.x86_64:

# mokutil --import-hash $(pesign -P -h -i /boot/vmlinuz-4.18.0-193.el8.x86_64  | cut -f 2 -d ' ')

The command prompts you to enter and confirm a password for the MOK enrollment request. You can use any password for this purpose, but you should note the password that you use, as you are prompted for it again when the system reboots.

Enroll a certificate for a kernel or package

To enroll a certificate for a set of kernels that are signed using the same certificate, you must first obtain the certificate file for the appropriate set of kernel binaries. The certificate keys that are used to sign each kernel and shim are contained in the source packages. If you download the appropriate source package and extract the certificate, you can use the mokutil command to import this certificate into the MOK list.

Download the kernel source package

On Oracle Linux 8, use dnf to download the kernel or kernel-uek source package that you require. For example, to download the latest UEK source package:

# dnf download --source kernel-uek

On Oracle Linux 7 run the yumdownloader command to download the kernel or kernel-uek source package that you require. For example, to download the kernel-uek-4.14.35-1902.303.4.1.el7uek version of this package:

# yumdownloader --source kernel-uek-4.14.35-1902.303.4.1.el7uek

Note that you can repeat the instructions in this tutorial to download multiple versions of each source package and extract the certificates from each, to import into the UEFI Secure Boot database, as you require. Use the Oracle Linux UEFI Secure Boot Update Notices to find guidance on the package versions that you might need for different minimum kernel versions.

Extract the source package

Extract the source package to access the EV certificate that is included for the kernel or kernel-uek package:

# rpm2cpio ./kernel-uek*.rpm | cpio -idmv

Import certificate into the MOK list

Use the mokutil command to request that the certificate that you have extracted from the source package is included in the MOK list:

# mokutil --import ./secureboot.cer

Do not import the CA certificate, securebootca.cer, that is included in the source packages. Importing the CA certificate allows any kernel that uses a certificate signed by the same CA to load and renders UEFI Secure Boot ineffective.

Reboot the system and complete enrollment

Reboot the system.

The pending MOK key enrollment request is detected, and you must complete the enrollment from the UEFI console. You are prompted for the password that you set when you imported the certificate. When you have entered the correct password, the certificate is added to the MOK list and is automatically propagated to the system key ring on this boot, as well as subsequent boots.

Want to Learn More?

Oracle Linux UEFI Secure Boot Update Notices
Oracle Linux Documentation
Oracle Linux and Unbreakable Enterprise Kernel (UEK) Releases
MOKUTIL(1) manual page.
PESIGN(1) manual page and pesign --help

Title and Copyright Information

Use mokutil to Update Signature Keys for UEFI Secure Boot

F34063_02

October 2020

This tutorial explains how to use the mokutils tool to update the certificates used for UEFI SecureBoot on Oracle Linux.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software, any programs embedded, installed or activated on delivered hardware, and modifications of such programs) and Oracle computer documentation or other Oracle data delivered to or accessed by U.S. Government end users are "commercial computer software" or "commercial computer software documentation" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, reproduction, duplication, release, display, disclosure, modification, preparation of derivative works, and/or adaptation of i) Oracle programs (including any operating system, integrated software, any programs embedded, installed or activated on delivered hardware, and modifications of such programs), ii) Oracle computer documentation and/or iii) other Oracle data, is subject to the rights and limitations specified in the license contained in the applicable contract. The terms governing the U.S. Government's use of Oracle cloud services are defined by the applicable contract for such services. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Epyc, and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.