This topic describes how to prepare the disk, generate security certificates,
and enable any necessary operating system (OS) features to create a custom
shielded image.

By default, Shielded VM supports
[Container-Optimized OS](https://docs.cloud.google.com/container-optimized-os/docs), various
distributions of Linux, and multiple versions of Windows Server. But if you
require custom images for your application, you can still take advantage of
Shielded VM.

> [!NOTE]
> **Note:** For the full list of operating systems that Shielded VM supports, see [Images with Shielded VM
> support](https://docs.cloud.google.com/compute/docs/images/os-details#security-features).

## Preparing the disk

Shielded VM relies on [Unified Extensible Firmware Interface
(UEFI)](http://www.uefi.org/sites/default/files/resources/UEFI_Secure_Boot_in_Modern_Computer_Security_Solutions_2013.pdf)-compliant
firmware to support features such as Secure Boot. Shielded VM requires
a GUID Partition Table (GPT) scheme; master boot record (MBR) is not
supported.

The disk must have at least two partitions:

- **EFI System Partition (ESP):** 100 megabytes (MB) is sufficient for this partition, and is only a suggestion. You can create a larger partition if necessary. The only requirement for the ESP is that it should be formatted with a File Allocation Table (FAT) filesystem.
- **OS Partition:** The rest of the disk. This partition contains the boot OS (Linux or Windows). There is no restriction on the size of this partition.

You can create more data partitions as necessary.

## Copying the OS to the OS partition

Once the disk is formatted and partitioned correctly, copy the OS files into
the OS partition. The OS has a boot loader that must be located at a valid path
on the ESP, as specified in the [UEFI specification](https://uefi.org/sites/default/files/resources/UEFI_Spec_2_7.pdf):
`\EFI\Boot\bootx64.efi`. Note that it may be necessary to copy the OS boot
loader to the given location.

For Windows, there is command called `bcdboot` that can be used to copy the OS
boot loader to the correct location, in addition to other actions that Windows
requires (such as copying the BCD store). For more information, see [BCDBoot
Command-Line
Options](https://docs.microsoft.com/windows-hardware/manufacture/desktop/bcdboot-command-line-options-techref-di) on the Microsoft Hardware Dev Center.

When using Shielded VM images, you can also take advantage of two
additional security features: virtual Trusted Platform Module (vTPM) and
integrity monitoring. The following sections outline the benefits of these
features and the OS requirements.

### Virtual Trusted Platform Module (vTPM)

A trusted platform module is a specialized device to protect objects, like keys
and certificates, that you use to authenticate access to your system. On
Shielded VM images, virtualized versions of TPM devices are used to
enable [Measured Boot](https://docs.cloud.google.com/compute/shielded-vm/docs/shielded-vm#measured-boot). In
brief, Measured Boot ensures the integrity of the critical load path of boot
and kernel drivers. vTPM and Measured Boot are covered in more detail in the
[Shielded VM documentation](https://docs.cloud.google.com/compute/shielded-vm/docs/shielded-vm#vtpm).

In order to take advantage of the vTPM and Measured Boot, a driver is required.
The minimum OS versions with TPM 2.0 support are:

- Windows Server 2012
- Linux version 3.20
- Red Hat Enterprise Linux 7.3

### Integrity monitoring

Integrity monitoring provides a way to understand and make decisions about the
state of your VM instances. Monitoring uses the data generated by [Measured
Boot](https://docs.cloud.google.com/compute/shielded-vm/docs/shielded-vm#measured-boot) to report on the VM
instance. The Shielded VM documentation has more information about
[integrity monitoring](https://docs.cloud.google.com/compute/shielded-vm/docs/shielded-vm#integrity-monitoring) and
[automating responses to integrity validation failures](https://docs.cloud.google.com/compute/shielded-vm/docs/automating-responses-integrity-failures).

To support the Shielded VM integrity monitoring feature, the image must
produce integrity signals:

- Windows generates integrity signals by default.
- Linux must have the [Integrity Measurement Architecture (IMA)
  module](https://sourceforge.net/p/linux-ima/wiki/Home/) installed and enabled. The module must have `CONFIG_IMA_MEASURE_PCR_IDX` set to 10. This is the default value for the IMA module.

## Importing the disk image to Compute Engine

Once the image is prepared, you have to upload the image into
Compute Engine. For the necessary steps to upload the image to
Google Cloud, see [Importing boot disk images to
Compute Engine](https://docs.cloud.google.com/compute/docs/images/import-existing-image).

> [!WARNING]
> **Warning:** While importing the image using the instructions from the referenced document, don't import the image file into your custom images list. Shielded VM requires additional steps and arguments that are explained in the following sections.

## Setting up certificates for Secure Boot

You can't add certificates to Compute Engine UEFI variables directly
with a tool like `mokutil`. This is because interactive UEFI and MOK management
menus don't support serial console input on Google Cloud. Instead, you add
certificates to a key database when you create a Shielded VM image.

When the Shielded VM image is added to a VM instance, a set of Secure
Boot, Distinguished Encoding Rules (DER)-encoded X.509 public certificates and
databases are passed into Compute Engine. These files are stored in
corresponding UEFI variables and used to establish trust relationships between
the platform, firmware, and OS.

The databases can be either a certificate or raw binary. There are four values
in total:

- **Platform Key (`pk`):** A key used to establish the trust relationship between the platform owner and the firmware. You may only specify *one* platform key, and it must be a valid X.509 certificate.
- **Key Exchange Key (`kek`):** A key used to establish a trust relationship between the firmware and the OS. You may specify multiple keys for this value.
- **Forbidden Key Database (`dbx`):** A database of certificates that have been revoked and will cause the system to stop booting if a boot file is signed with one of them. You may specify single or multiple values for this value.
- **Key Database (`db`):** A database of certificates that are trusted and can be used to sign boot files. You may specify single or multiple values for this value.

The [UEFI specification](https://uefi.org/specifications)
contains more information about these values and how they work.

In the following example [OpenSSL](https://www.openssl.org/)
is used to create the Secure Boot keys and certificates.

- Generate a 2048-bit RSA key pair

      openssl genrsa -out secure-boot-key.rsa 2048

- Generate a self-signed X.509 certificate from the key in DER format

      openssl req -new -x509 -sha256 \
          -subj '/CN=secure-boot' \
          -key secure-boot-key.rsa \
          -outform DER \
          -out secure-boot-cert.pem

## Adding the shielded image to Google Cloud

Using the uploaded image and certificates, you can now add the image to
Compute Engine. The image can be added using the Google Cloud CLI or the
Compute Engine API.

### gcloud


Add the custom image to Compute Engine:

```
gcloud compute images create [IMAGE_NAME] \
    --source-disk [SOURCE_DISK] \
    --source-disk-zone [ZONE] \
    --platform-key-file= \
    --key-exchange-key-file= \
    --signature-database-file=, \
    --forbidden-database-file= \
    --guest-os-features="UEFI_COMPATIBLE[,WINDOWS]"
```

where:

- `[IMAGE_NAME]` is the name for the new image.
- `[SOURCE_DISK]` is the disk from which you want to create the new image.
- `[ZONE]` is the zone where the disk is located.

The `WINDOWS` option for `guest-os-features` is only required when using a Windows
image. For more information on creating an image, see the
[`gcloud create` reference](https://docs.cloud.google.com/sdk/gcloud/reference/compute/images/create).

### REST


Follow the instructions to
[create an image from a persistent disk](https://docs.cloud.google.com/compute/docs/images/create-delete-deprecate-private-images#bundle_image)
but specify the `initial_state_config` in the request body.

    ...
    "sourceDisk": "/zones/[ZONE]/disks/[SOURCE_DISK]",

    "initial_state_config": {
        "pk": {
            "content": [KEY],
            "fileType": [BIN,X509]
        },
        "keks": [
            {
                "content": [KEY],
                "fileType": [BIN,X509]
            },
            ...
        ],
        "dbxs": [
            {
                "content": [KEY],
                "fileType": [BIN,X509]
            },
            ...
        ],
        "dbs": [
            {
                "content": [KEY],
                "fileType": [BIN,X509]
            },
            ...
        ]
    }

## Default certificates

Note that `pk`, `keks`, `dbxs` and `dbs` are optional fields. If you provide an
initial state configuration, some or all of these fields may be unset. When a
new instance is created from the image, Google Cloud provides a default
value for `PK`, `KEK`, `db`, and `dbx` unless a custom value was set on any
unset field. If you provide no initial state configuration (that is, the
configuration is missing, not just empty), the image will have the initial state
configuration of the source image.

These fields' default values are:

- `PK`: The certificate associated with the default private key created by Google.
- `KEK`: The default Microsoft KEK certificates.

  - `MicCorKEKCA2011_2011-06-24.crt`: Download from [Microsoft](https://go.microsoft.com/fwlink/?LinkId=321185)
    or [GitHub](https://github.com/microsoft/secureboot_objects/blob/main/PreSignedObjects/KEK/Certificates/MicCorKEKCA2011_2011-06-24.der).

    SHA-1: `31590bfd89c9d74ed087dfac66334b3931254b30`
  - `microsoft corporation kek 2k ca 2023.der`: Download from [Microsoft](https://go.microsoft.com/fwlink/p/?linkid=2239775)
    or [GitHub](https://github.com/microsoft/secureboot_objects/raw/refs/heads/main/PreSignedObjects/KEK/Certificates/microsoft%20corporation%20kek%202k%20ca%202023.der).

    SHA-1: `459ab6fb5e284d272d5e3e6abc8ed663829d632b`
- `dbx`: The default Microsoft DBX revocation list. Download from Unified
  Extensible Firmware Interface Forum: [UEFI revocation list
  file](https://www.uefi.org/revocationlistfile)

- `db`: The following four certificates:

  - `MicWinProPCA2011_2011-10-19.der`: Download from [Microsoft](https://go.microsoft.com/fwlink/p/?linkid=321192)
    or [GitHub](https://github.com/microsoft/secureboot_objects/raw/refs/heads/main/PreSignedObjects/DB/Certificates/MicWinProPCA2011_2011-10-19.der).

    SHA-1: `580a6f4cc4e4b669b9ebdc1b2b3e087b80d0678d`
  - `MicCorUEFCA2011_2011-06-27.der`: Download from [Microsoft](https://go.microsoft.com/fwlink/p/?linkid=321194)
    or [GitHub](https://github.com/microsoft/secureboot_objects/raw/refs/heads/main/PreSignedObjects/DB/Certificates/MicCorUEFCA2011_2011-06-27.der).

    SHA-1: `46def63b5ce61cf8ba0de2e6639c1019d0ed14f3`
  - `microsoft uefi ca 2023.der`: Download from [Microsoft](https://go.microsoft.com/fwlink/?linkid=2239872)
    or [GitHub](https://github.com/microsoft/secureboot_objects/raw/refs/heads/main/PreSignedObjects/DB/Certificates/microsoft%20uefi%20ca%202023.der).

    SHA-1: `b5eeb4a6706048073f0ed296e7f580a790b59eaa`
  - `windows uefi ca 2023.der`: Download from [Microsoft](https://go.microsoft.com/fwlink/?LinkId=2239776)
    or [GitHub](https://github.com/microsoft/secureboot_objects/raw/refs/heads/main/PreSignedObjects/DB/Certificates/windows%20uefi%20ca%202023.der).

    SHA-1: `45a0fa32604773c82433c3b7d59e7466b3ac0c67`

Be careful, since adding your own certificates will overwrite the default ones
rather than merging them with the ones you provide.