README
¶
gce-tcb-verifier
This project provides tools for creating and verifying launch endorsements for binaries included in Google Compute Engine Confidential Virtual Machines at launch.
Of particular note in these libraries is the derivation of Open Virtual Machine Firmware (OVMF) binaries to their expected SEV-SNP measurement.
Terms
A "launch endorsement" is a signed "golden measurement". Each trusted execution environment technology has its own process for measuring the initial state of a virtual machine. The final result is called the "measurement", and is included in the technology's remote attestation report.
The launch endorsement is provided as a binary-serialized VMLaunchEndorsement
message from proto/endorsement.proto.
Transparency
The OVMF SHA-384 digest in a golden measurement binds the launch endorsement to a specific build of the firmware. Google publishes its production virtual firmware binaries for transparency. Verifying parties may download the 2MiB image to inspect and reproduce the golden measurement from.
The root certificate(s) for code signatures are available at
https://pki.goog/cloud_integrity/GCE-cc-tcb-root_1.crt
The _1 naming convention is to allow for root rotation if required, with an
increase to _2, etc. Such an event will come with advance notice.
We recommend to fetch this certificate yourself to establish trust through the HTTPS certificate, as it links itself to Google.
Inspecting endorsements
The VMLaunchEndorsement serialized binary that asserts authenticity of a
firmware binary needs some help to be more human-digestible. The
gcbtcbendorsement CLI tool provides commands
for extracting information from an endorsement binary.
Verifying endorsements
The verify library includes the protocol buffer deserialization and signature
verification logic that the simple format requires. Since the endorsement
document is provided from the host certificate cache and needs to be compared
against an attestation report's measurement, the verify library composes with
go-sev-guest's verification options to fully validate a GCE attestation report
via verify.SNPValidateFunc.
The gcetcbendorsement CLI tool provides commands that expose this behavior in
a binary.
Non-production endorsement
Whereas genuine firmware binaries are signed by access-restricted Cloud KMS
keys, the cmd/nonprod tool provides a locally-managed offline
certificate authority and code-signing mechanism. The default certificates
contain Google metadata, but a keys.ManagerInterface implementation can
provide its own certificate template. The endorse command will use keys in
--key_dir and their certificates in --bucket_root to sign a firmware
provided from --uefi.
Initial keys may be bootstrapped with the bootstrap command, and signing keys
can be rotated with the rotate command.
AMD SEV-SNP
AMD SEV-SNP documents its measurement methodology in its SEV-SNP ABI
specification for SNP_LAUNCH_UPDATE. Google does not populate and authenticate
an IDBLOCK as a method of tying expected values to an attestation report since
it is not extensible. The data that would go in an IDBLOCK are provided in a
VMSevSnp message.
Links
Disclaimers
This is not an officially supported Google product.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd defines a testable CLI-like interface in order for the true CLI binary to be simple.
|
Package cmd defines a testable CLI-like interface in order for the true CLI binary to be simple. |
|
nonprod
The nonprod command provides a non-production CLI tool for endorsing an input UEFI binary and managing the keys to do so.
|
The nonprod command provides a non-production CLI tool for endorsing an input UEFI binary and managing the keys to do so. |
|
output
Package output provides operations for command implementations to write information of various kinds.
|
Package output provides operations for command implementations to write information of various kinds. |
|
Package endorse defines functions for producing and signing golden measurements of a UEFI.
|
Package endorse defines functions for producing and signing golden measurements of a UEFI. |
|
Package eventlog provides functions for reading PC Client event logs and various EventData they can carry.
|
Package eventlog provides functions for reading PC Client event logs and various EventData they can carry. |
|
Package extract provides endorsement extraction logic to access cached information available from either an attestation report or an event logger.
|
Package extract provides endorsement extraction logic to access cached information available from either an attestation report or an event logger. |
|
eventlog
Package eventlog provides utilities for interpreting Canonical Event Log events.
|
Package eventlog provides utilities for interpreting Canonical Event Log events. |
|
extractsev
Package extractsev provides utilities for extracting SEV-SNP endorsements.
|
Package extractsev provides utilities for extracting SEV-SNP endorsements. |
|
extracttdx
Package extracttdx contains the implementation of the endorsement location derivation from MRTD.
|
Package extracttdx contains the implementation of the endorsement location derivation from MRTD. |
|
gcetcbendorsement
module
|
|
|
Package keys provides context and management types for key signing and certificates.
|
Package keys provides context and management types for key signing and certificates. |
|
gcpkms
Package gcpkms implements keys.ManagerInterface with a Google Cloud Platform Key Management Service (GCP KMS) client.
|
Package gcpkms implements keys.ManagerInterface with a Google Cloud Platform Key Management Service (GCP KMS) client. |
|
Package ovmf includes tools for parsing OVMF binaries for measurement-specific values.
|
Package ovmf includes tools for parsing OVMF binaries for measurement-specific values. |
|
abi
Package abi defines binary interface conversion functions for the OVMF binary format.
|
Package abi defines binary interface conversion functions for the OVMF binary format. |
|
Package proto contains protocol buffers that are exchanged between the client and server, as well as convenience configuration definitions for tools.
|
Package proto contains protocol buffers that are exchanged between the client and server, as well as convenience configuration definitions for tools. |
|
Package rotate ensures rotated signing keys for CC TCB endorsement have certificates in GCS.
|
Package rotate ensures rotated signing keys for CC TCB endorsement have certificates in GCS. |
|
Package sev implements launch measurement reconstruction given a few inputs such as firmware.
|
Package sev implements launch measurement reconstruction given a few inputs such as firmware. |
|
sign
|
|
|
gcsca
Package gcsca implements the sign.CertificateAuthority interface with GCS backing.
|
Package gcsca implements the sign.CertificateAuthority interface with GCS backing. |
|
memca
Package memca provides the CertificateAuthority interface entirely in memory without persistence.
|
Package memca provides the CertificateAuthority interface entirely in memory without persistence. |
|
nonprod
Package nonprod provides an in-memory signer and CA for endorsement using generated or provided keys.
|
Package nonprod provides an in-memory signer and CA for endorsement using generated or provided keys. |
|
ops
Package ops defines operations for signing and interacting with certificate authorities given the interfaces defined in sign/types.
|
Package ops defines operations for signing and interacting with certificate authorities given the interfaces defined in sign/types. |
|
transform
Package transform provides decoding utilities for certificate formats.
|
Package transform provides decoding utilities for certificate formats. |
|
types
Package types defines the interfaces we use to interact with signing and certificates.
|
Package types defines the interfaces we use to interact with signing and certificates. |
|
storage
|
|
|
local
Package local provides a StorageClient interface implementation for local disk file management.
|
Package local provides a StorageClient interface implementation for local disk file management. |
|
ops
Package ops provides an interface and common operations on a StorageClient.
|
Package ops provides an interface and common operations on a StorageClient. |
|
storagei
Package storagei provides a storage interface type that can be used for file management.
|
Package storagei provides a storage interface type that can be used for file management. |
|
Package tdx implements launch measurement reconstruction given a few inputs such as firmware.
|
Package tdx implements launch measurement reconstruction given a few inputs such as firmware. |
|
testing
|
|
|
devkeys
Package devkeys provides test-only pregenerated and signed root and signer keys.
|
Package devkeys provides test-only pregenerated and signed root and signer keys. |
|
fakeovmf
Package fakeovmf generates test OVMF binary data to test OVMF binary parsing.
|
Package fakeovmf generates test OVMF binary data to test OVMF binary parsing. |
|
match
Package match provides utilities for tests to check if results match expectations.
|
Package match provides utilities for tests to check if results match expectations. |
|
nonprod
Package nonprod implements local signing and file operations for signing and submitting endorsements to disk.
|
Package nonprod implements local signing and file operations for signing and submitting endorsements to disk. |
|
nonprod/certs
Package certs provides certificate templating logic for nonprod key management.
|
Package certs provides certificate templating logic for nonprod key management. |
|
nonprod/gcetcb
The gcetcb.test command provides test-only GCE TCB management operations, like UEFI endorsement.
|
The gcetcb.test command provides test-only GCE TCB management operations, like UEFI endorsement. |
|
nonprod/localca
Package localca is a local storage CommandComponent instantiation of gcsca.
|
Package localca is a local storage CommandComponent instantiation of gcsca. |
|
nonprod/localkm
Package localkm provides a keys.ManagerInterface implementation that persists keys to disk.
|
Package localkm provides a keys.ManagerInterface implementation that persists keys to disk. |
|
nonprod/localnonvcs
Package localnonvcs implements the endorse.VersionControl interface without operating with an actual version-control system.
|
Package localnonvcs implements the endorse.VersionControl interface without operating with an actual version-control system. |
|
nonprod/memkm
Package memkm provides an in-memory keys.ManagerInterface implementation.
|
Package memkm provides an in-memory keys.ManagerInterface implementation. |
|
storage
Package storage provides a mock rotate.StorageClient implementation
|
Package storage provides a mock rotate.StorageClient implementation |
|
testca
Package testca defines test cases for any implementation of styp.CertificateAuthority.
|
Package testca defines test cases for any implementation of styp.CertificateAuthority. |
|
testkm
Package testkm provides reusable test cases for in-memory and local file key managers, since they both use the same underlying signer.
|
Package testkm provides reusable test cases for in-memory and local file key managers, since they both use the same underlying signer. |
|
testkms
Package testkms implements a mock type for KeyManagementServiceClientInterface for KMS-based signing code to be tested positively and negatively.
|
Package testkms implements a mock type for KeyManagementServiceClientInterface for KMS-based signing code to be tested positively and negatively. |
|
testsign
Package testsign implements both a mock and fake type for testing the endorsement signing code paths.
|
Package testsign implements both a mock and fake type for testing the endorsement signing code paths. |
|
Package timeproto provides functions for translating timestamps between Golang and Protobuf.
|
Package timeproto provides functions for translating timestamps between Golang and Protobuf. |
|
Package verify provides functions to check an endorsement against a UEFI binary.
|
Package verify provides functions to check an endorsement against a UEFI binary. |
|
verifytest
Package verifytest provides testonly data for verifying UEFI endorsements.
|
Package verifytest provides testonly data for verifying UEFI endorsements. |