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 OpenNOPTPM() (io.ReadWriteCloser, error)
- func OpenVTPM() (io.ReadWriteCloser, error)
- type AttestationDocument
- type GetInstanceInfo
- type GetTPMAttestationKey
- type GetTPMTrustedAttestationPublicKey
- type Issuer
- type TPMOpenFunc
- type ValidateCVM
- type Validator
Constants ¶
This section is empty.
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 ¶
GetSHA256QuoteIndex performs safety checks and returns the index for SHA256 PCR quotes.
func GetSelectedMeasurements ¶ added in v2.3.0
func GetSelectedMeasurements(open TPMOpenFunc, selection tpm2.PCRSelection) (measurements.M, error)
GetSelectedMeasurements returns a map of Measurments for the PCRs in selection.
func OpenNOPTPM ¶
func OpenNOPTPM() (io.ReadWriteCloser, error)
OpenNOPTPM returns a NOP io.ReadWriteCloser that can be used as a TPM.
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 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 attestation.Logger, ) *Issuer
NewIssuer returns a new Issuer.
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 attestation.Logger, ) *Validator
NewValidator returns a new Validator.
Source Files