Secure Boot Custom Certificates

Products

VMware VMware vSphere ESXi

Issue/Introduction

This article provides instructions to run custom signed operating systems or drivers while keeping Secure Boot enabled on a virtual machine (VM) using UEFI.

For VMs running Linux operating systems, there are a few solutions, such as the Machine Owner Key or building the Linux kernel with certificates embedded. On kernels with this option CONFIG_MODULE_SIG_UEFI set, you must change the VM secure boot configuration in order to make use of the option if the kernels or drivers are not signed by certificates in the default VMware Secure Boot configuration.

Environment

VMware vSphere ESXi 7.0

VMware vSphere ESXi 8.0

VMware vSphere ESXi 9.0

Resolution

Custom Secure Boot configuration while deploying a new Virtual Machine

The Secure Boot configuration is stored in NVRAM. If the NVRAM contains no Secure Boot configuration (a freshly deployed VM, or a VM for which the .nvram file has been deleted from the datastore), then the Secure Boot configuration is reset to the defaults described in the UEFI Specification (the variables named PKDefault, KEKDefault, dbDefault and dbxDefault). You can use the advanced VM config options to control those defaults, through which you can pre-populate the Secure Boot configuration before the VM is first powered on.

If you want to deploy the certificates as part of the VM's configuration, copy the DER-encoded certificate into the VM's directory and add the following advanced VM config options:

uefi.secureBoot.dbDefault.file0 = "custom-cert.der"

where "custom-cert.der" is the name of the DER-encoded certificate file within the VM's directory. You can repeat that for file1, file2, file3, etc., to add multiple certificates. It is also possible to specify a full path to the certificate so that it doesn't need to be in the VM's directory, such as "/vmfs/volumes/datastore1/custom-cert.der".

If you want to pre-configure SHA-256 hashes into the Secure Boot approved database (db) or revoked database (dbx), put a hexadecimal representation of the file's Authenticode hash (Note: this is not the regular SHA-256 sum over the whole file) into an advanced VM config option like this:

uefi.secureBoot.dbDefault.value0 = "01b##71##80##fe##1b##1a7##51###64##ece96##09c0###f8f###5da##54##"

If you want to replace the default certs so that only your custom certs, also add:

uefi.secureBoot.dbDefault.append = "FALSE"

which removes the default certs before starting to add your custom certs. By default, your custom certificates are appended to the default set of custom certificates.

If the custom Secure Boot configuration was successfully added, the VM's vmware.log should show a message similar to Added uefi.secureBoot.dbDefault.file0 to dbDefault. or Added uefi.secureBoot.dbDefault.value0 to dbDefault.

If the custom Secure Boot configuration was not successful, the log messages begin with Unable to load uefi.secureBoot... or Unable to convert uefi.secureBoot... Ensure the custom Secure Boot configuration is successful before continuing to configure the VM.

Setting a custom Secure Boot configuration on an existing Virtual Machine

As mentioned, the method described above only works on a freshly deployed VM, or a VM for which the .nvram file has been deleted from the datastore. To apply a custom Secure Boot configuration on an existing VM, starting from VMware vSphere ESXi 9.0:

Set the advanced VM config options mentioned in the previous section.
Set the following advanced VM config option:

uefi.secureBoot.db.resetOnce = "TRUE"

You can replace "db" with "PK", "KEK", or "dbx" depending on the Secure Boot that you wish to reset.

Note: This clears the Secure Boot variable and applies the default value for the Secure Boot variable, so if the advanced VM config options to set the default values (as in the previous section) are not set, the in-built defaults are used. These are the same defaults as you would have in a new VM without any advanced VM config options. If the resetting of the Secure Boot variable is successful, the VM's vmware.log should show a message starting with Clearing Secure Boot variable ... When the Secure Boot variable is reset successfully, the advanced VM config option uefi.secureBoot.db.resetOnce is removed from the advanced VM config options.

Note: Resetting the Secure Boot variables may impact functionality in the VM. For example, if the VM is a Microsoft Windows Server guest and has both vTPM and Secure Boot configured and BitLocker enabled in the guest, resetting a Secure Boot variable may cause BitLocker to require the recovery key to be entered.