Securely boot a VM

This document explains how to enable secure boot or a virtualized trusted platform module (vTPM) on a virtual machine (VM) instance in Google Distributed Cloud (GDC) air-gapped.

This document is for developers in platform administrator or application operator groups that configure secure boot and vTPMs on VMs in a Distributed Cloud environment. For more information, see Audiences for GDC air-gapped documentation.

About secure boot

Secure boot is a feature that ensures the system runs only authentic software by verifying the digital signature of all boot components and stops the process if verification fails. It uses the Unified Extensible Firmware Interface (UEFI) firmware to manage certificates and keys that manufacturers use to sign system firmware, boot loaders, and loaded binaries.

On each boot, the UEFI firmware verifies each component's digital signature against stored approved keys and blocks any unsigned or improperly signed components. To enable secure boot on your VM instance, you must set the VM's bootloader type to uefi.

To view the official UEFI documentation, see https://uefi.org/sites/default/files/resources/UEFI_Secure_Boot_in_Modern_Computer_Security_Solutions_2013.pdf.

About virtual trusted platform modules

A vTPM is a specialized virtual computer chip that protects the keys and certificates used to authenticate system access. See https://trustedcomputinggroup.org/trusted-platform-module-tpm-summary/ for more information about vTPMs.

You can also use a 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 IAM roles

To enable secure boot or vTPM on your VM, contact your Project IAM Admin to request the Virtual Machine Project Admin (project-vm-admin) role.

All VM roles must bind to the namespace of the project where the VM resides. Follow the steps to verify your access.

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).

Stop your VM if it's running before applying the patch. If you attempt to patch shieldConfig while the VM is running, the API returns a Forbidden error: Changes to shieldConfig are not allowed while the VM is running. For instructions, see Stop a VM.

Update your VM custom resource to enable secure boot:

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

After you successfully apply the patch, start your VM using the instructions to start 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 \
  -n PROJECT_NAMESPACE \
  edit virtualmachines.virtualmachine.gdc.goog VM_NAME

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 vTPM

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

Stop your VM if it's running before applying the patch. If you attempt to patch shieldConfig while the VM is running, the API returns a Forbidden error: Changes to shieldConfig are not allowed while the VM is running. For instructions, see Stop a VM.

Update your VM custom resource to enable vTPM:

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

After you successfully apply the patch, start your VM using the instructions to start 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