Securely boot a VM

Secure boot helps to ensure that the system runs only authentic software by verifying the digital signature of all boot components, and stopping the boot process if signature verification fails.

Google Distributed Cloud (GDC) air-gapped uses the Unified Extensible Firmware Interface (UEFI) firmware to manage certificates and keys used for signing software.

The UEFI firmware securely manages the certificates that contain the keys the software manufacturers use to sign the system firmware, the system boot loader, and any binaries they load. To see the UEFI documentation, visit https://uefi.org/sites/default/files/resources/UEFI_Secure_Boot_in_Modern_Computer_Security_Solutions_2013.pdf.

On each boot, the UEFI firmware verifies the digital signature of each boot component against the secure store of approved keys. Any boot component that you don't sign properly, or you don't sign at all, isn't allowed to run. To enable secure boot, you must set the VM's bootloader type to uefi.

A vTPM is a virtualized trusted platform module. See https://trustedcomputinggroup.org/trusted-platform-module-tpm-summary/ for more information about vTPMs. It's a specialized computer chip you can use to protect objects, like keys and certificates, that you use to authenticate access to your system. You can also use the vTPM to protect secrets through shielding or sealing. For more information on sealed storage, see https://en.wikipedia.org/wiki/Trusted_Computing#SEALED-STORAGE. See the Go-TPM project on GitHub - https://github.com/google/go-tpm - for Go language examples that illustrate how to use a vTPM for this purpose.

Before you begin

To use gdcloud command-line interface (CLI) commands, ensure that you have downloaded, installed, and configured the gdcloud CLI. All commands for Distributed Cloud use the gdcloud or kubectl CLI, and require an operating system (OS) environment.

Get the kubeconfig file path

To run commands against the Management API server, ensure you have the following resources:

Sign in and generate the kubeconfig file for the Management API server if you don't have one.
Use the path to the kubeconfig file of the Management API server to replace MANAGEMENT_API_SERVER in these instructions.

Request permissions and access

To perform the tasks listed on this page, you must have the Project VirtualMachine Admin role. Follow the steps to verify that you have the Project VirtualMachine Admin (project-vm-admin) role in the namespace of the project where the VM resides.

Enable secure boot

Enable secure boot for a VM. Use the following instructions for a VM called VM_NAME in the project's namespace (PROJECT_NAMESPACE).

Update your VM custom resource to enable secure boot:

kubectl --kubeconfig MANAGEMENT_API_SERVER patch virtualmachines.virtualmachine.gdc.goog VM_NAME -n PROJECT_NAMESPACE --type merge --patch $'
spec:
 shieldConfig:
   bootType: uefi
   enableSecureBoot: true
'

If the VM is running, restart it using the instructions to restart a VM.
Verify that you've enabled secure boot. Establish an SSH connection to your VM and run the following command:
```
mokutil --sb-state
```
If you've successfully enabled secure boot, the command returns SecureBoot enabled.

If the mokutil tool reports that you have not enabled secure boot, follow the steps in the section Troubleshoot secure boot configuration.

Troubleshoot secure boot configuration

Open your VM custom resource in an editor:

kubectl --kubeconfig MANAGEMENT_API_SERVER edit virtualmachines.virtualmachine.gdc.goog VM_NAME -n PROJECT_NAMESPACE

Look for missing fields or values as shown in the spec field in "Run the following command". These are required.
If any are missing or are incorrect, edit spec to add the missing fields and correct erroneous values.
Save the file.
Follow the steps in Restart the VM.

If the previous steps don't resolve your issue, check the documentation corresponding to the VM's operating system (OS) to verify that the OS version supports the secure boot.

Enable virtual trusted platform module (vTPM)

Enable vTPM for a VM. Use the following instructions for a VM called VM_NAME in the project's namespace (PROJECT_NAMESPACE).

Update your VM custom resource to enable vTPM:

kubectl --kubeconfig MANAGEMENT_API_SERVER patch virtualmachines.virtualmachine.gdc.goog VM_NAME -n PROJECT_NAMESPACE --type merge --patch $'
spec:
   shieldConfig:
      enableVtpm: true
'

If the VM is running, restart it using the instructions to restart a VM.
Verify that you've enabled vTPM. Establish an SSH connection to your VM and run the following command:
```
dmesg | grep -i tpm
```
If you've successfully enabled vTPM, the command returns the TPM Module as part of the ACPI tables. The output looks similar to the following:
```
[    7.620985] tpm_tis MSFT0101:00: 2.0 TPM (device-id 0x1, rev-id 1)
```
If the ACPI tables don't display the TPM module, follow the steps in the section Troubleshoot vTPM configuration.

Troubleshoot vTPM configuration

Open your VM custom resource in an editor:

kubectl --kubeconfig MANAGEMENT_API_SERVER edit virtualmachines.virtualmachine.gdc.goog VM_NAME -n PROJECT_NAMESPACE

Look for missing fields or values as shown in the spec field in Run the following command. These are required.
If any are missing or are incorrect, edit spec to add the missing fields and correct erroneous values.
Save the file.
Follow the steps in Restart the VM.

If the previous steps don't resolve your issue, check the documentation corresponding to the VM's operating system (OS) to verify that the OS version supports vTPM.