vtpm

Documentation

Overview

Virtual Trusted Platform Module (vTPM)

This package provides functions to interact with a vTPM. It also implements the low level TPM attestation and verification logic of Constellation's TPM attestation workflow.

Code that directly interacts with the TPM goes here.

vTPM components

For attestation we make use of multiple vTPM features:

• Endorsement Key

  Asymmetric key used to establish trust in other keys issued by the TPM or used directly for attestation. The private part never leaves the TPM, while the public part, referred to as Endorsement Public Key (EPK), is available to remote parties. The TPM can issue new keys, signed by its endorsement key, which can then be verified by a remote party using the EPK.

• Endorsement Public Key Certificate (EPKC)

  A Certificate signed by the TPM manufacturer verifying the authenticity of the EPK. The public key of the Certificate is the EPK.

• Event Log

  A log of events over the boot process.

• Platform Control Register (PCR)

  Registers holding measurements of software and configuration data. PCR values are not directly written, but updated: a new value is the digest of the old value concatenated with the to be added data. Contents of the PCRs can be signed for attestation. Providing proof to a remote party about software running on the system.

Attestation flow

1. The VM boots and writes its measured software state to the PCRs.

2. The PCRs are hashed and signed by the EPK.

3. An attestation statement is created, containing the EPK, the original PCR values, the hashed PCRs, the signature, and the event log.

4. A remote party establishes trust in the TPMs EPK by verifying its EPKC with the TPM manufactures CA certificate chain.

5. The remote party verifies the signature was created by the TPM, and the hash matches the PCRs.

6. The remote party reads the event log and verifies measuring the event log results in the given PCR values

7. The software state is now verified, the only thing left to do is to decide if the state is good or not. This is done by comparing the given PCR values to a set of expected PCR values.

Index

• Variables
• func GetSHA256QuoteIndex(quotes []*tpmProto.Quote) (int, error)
• func GetSelectedMeasurements(open TPMOpenFunc, selection tpm2.PCRSelection) (measurements.M, error)
• func IsNodeBootstrapped(openTPM TPMOpenFunc) (bool, error)
• func MarkNodeAsBootstrapped(openTPM TPMOpenFunc, clusterID []byte) error
• func OpenNOPTPM() (io.ReadWriteCloser, error)
• func OpenVTPM() (io.ReadWriteCloser, error)
• type AttestationDocument
• type AttestationLogger
• type GetInstanceInfo
• type GetTPMAttestationKey
• type GetTPMTrustedAttestationPublicKey
• type Issuer
  • func NewIssuer(openTPM TPMOpenFunc, getAttestationKey GetTPMAttestationKey, ...) *Issuer
  • func (i *Issuer) Issue(ctx context.Context, userData []byte, nonce []byte) (res []byte, err error)
• type TPMOpenFunc
• type ValidateCVM
• type Validator
  • func NewValidator(expected measurements.M, getTrustedKey GetTPMTrustedAttestationPublicKey, ...) *Validator
  • func (v *Validator) Validate(ctx context.Context, attDocRaw []byte, nonce []byte) (userData []byte, err error)

Variables

var (
	// AzurePCRSelection are the PCR values verified for Azure Constellations.
	// PCR[0] is excluded due to changing rarely, but unpredictably.
	// PCR[6] is excluded due to being different for any 2 VMs. See: https://trustedcomputinggroup.org/wp-content/uploads/TCG_PCClient_PFP_r1p05_v23_pub.pdf#%5B%7B%22num%22%3A157%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C33%2C400%2C0%5D
	// PCR[10] is excluded since its value is derived from a digest of PCR[0-7]. See: https://sourceforge.net/p/linux-ima/wiki/Home/#ima-measurement-list
	AzurePCRSelection = tpm2.PCRSelection{
		Hash: tpm2.AlgSHA256,
		PCRs: []int{1, 2, 3, 4, 5, 7, 8, 9, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23},
	}

	// GCPPCRSelection are the PCR values verified for GCP Constellations.
	// On GCP firmware and other host controlled systems are static. This results in the same PCRs for any 2 VMs using the same image.
	GCPPCRSelection = tpmClient.FullPcrSel(tpm2.AlgSHA256)

	// AWSPCRSelection are the PCR values verified for AWS based Constellations.
	// PCR[1] is excluded. See: https://trustedcomputinggroup.org/wp-content/uploads/TCG_PCClient_PFP_r1p05_v23_pub.pdf#%5B%7B%22num%22:157,%22gen%22:0%7D,%7B%22name%22:%22XYZ%22%7D,33,400,0%5D
	// PCR[10] is excluded since its value is derived from a digest of PCR[0-7]. See: https://sourceforge.net/p/linux-ima/wiki/Home/#ima-measurement-list
	AWSPCRSelection = tpm2.PCRSelection{
		Hash: tpm2.AlgSHA256,
		PCRs: []int{0, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23},
	}

	// QEMUPCRSelection are the PCR values verified for QEMU based Constellations.
	// PCR[1] is excluded. See: https://trustedcomputinggroup.org/wp-content/uploads/TCG_PCClient_PFP_r1p05_v23_pub.pdf#%5B%7B%22num%22:157,%22gen%22:0%7D,%7B%22name%22:%22XYZ%22%7D,33,400,0%5D
	// PCR[10] is excluded since its value is derived from a digest of PCR[0-7]. See: https://sourceforge.net/p/linux-ima/wiki/Home/#ima-measurement-list
	QEMUPCRSelection = tpm2.PCRSelection{
		Hash: tpm2.AlgSHA256,
		PCRs: []int{0, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23},
	}
)

Functions

func GetSHA256QuoteIndex

func GetSHA256QuoteIndex(quotes []*tpmProto.Quote) (int, error)

GetSHA256QuoteIndex performs safety checks and returns the index for SHA256 PCR quotes.

func GetSelectedMeasurements

func GetSelectedMeasurements(open TPMOpenFunc, selection tpm2.PCRSelection) (measurements.M, error)

GetSelectedMeasurements returns a map of Measurments for the PCRs in selection.

func IsNodeBootstrapped

func IsNodeBootstrapped(openTPM TPMOpenFunc) (bool, error)

IsNodeBootstrapped checks if a node is already bootstrapped by reading PCRs.

func MarkNodeAsBootstrapped

func MarkNodeAsBootstrapped(openTPM TPMOpenFunc, clusterID []byte) error

MarkNodeAsBootstrapped marks a node as initialized by extending PCRs.

func OpenNOPTPM

func OpenNOPTPM() (io.ReadWriteCloser, error)

OpenNOPTPM returns a NOP io.ReadWriteCloser that can be used as a TPM.

func OpenVTPM

func OpenVTPM() (io.ReadWriteCloser, error)

OpenVTPM opens the vTPM at `TPMPath`.

Types

type AttestationDocument

type AttestationDocument struct {
	// Attestation contains the TPM event log, PCR values and quotes, and public key of the key used to sign the attestation.
	Attestation *attest.Attestation
	// InstanceInfo is used to verify the provided public key.
	InstanceInfo []byte
	// arbitrary data, quoted by the TPM.
	UserData []byte
}

AttestationDocument contains the TPM attestation with signed user data.

type AttestationLogger

type AttestationLogger interface {
	Infof(format string, args ...any)
	Warnf(format string, args ...any)
}

AttestationLogger is a logger used to print warnings and infos during attestation validation.

type GetInstanceInfo

type GetInstanceInfo func(ctx context.Context, tpm io.ReadWriteCloser, extraData []byte) ([]byte, error)

GetInstanceInfo returns VM metdata.

type GetTPMAttestationKey

type GetTPMAttestationKey func(tpm io.ReadWriter) (*tpmClient.Key, error)

GetTPMAttestationKey loads a TPM key to perform attestation.

type GetTPMTrustedAttestationPublicKey

type GetTPMTrustedAttestationPublicKey func(context.Context, AttestationDocument, []byte) (crypto.PublicKey, error)

GetTPMTrustedAttestationPublicKey verifies and returns the attestation public key.

type Issuer

type Issuer struct {
	// contains filtered or unexported fields
}

Issuer handles issuing of TPM based attestation documents.

func NewIssuer

func NewIssuer(
	openTPM TPMOpenFunc, getAttestationKey GetTPMAttestationKey,
	getInstanceInfo GetInstanceInfo, log AttestationLogger,
) *Issuer

NewIssuer returns a new Issuer.

func (*Issuer) Issue

func (i *Issuer) Issue(ctx context.Context, userData []byte, nonce []byte) (res []byte, err error)

Issue generates an attestation document using a TPM.

type TPMOpenFunc

type TPMOpenFunc func() (io.ReadWriteCloser, error)

TPMOpenFunc opens a TPM device.

type ValidateCVM

type ValidateCVM func(attestation AttestationDocument, state *attest.MachineState) error

ValidateCVM validates confidential computing capabilities of the instance issuing the attestation.

type Validator

type Validator struct {
	// contains filtered or unexported fields
}

Validator handles validation of TPM based attestation.

func NewValidator

func NewValidator(expected measurements.M, getTrustedKey GetTPMTrustedAttestationPublicKey,
	validateCVM ValidateCVM, log AttestationLogger,
) *Validator

NewValidator returns a new Validator.

func (*Validator) Validate

func (v *Validator) Validate(ctx context.Context, attDocRaw []byte, nonce []byte) (userData []byte, err error)

Validate a TPM based attestation.