server

package
v0.4.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 29, 2024 License: Apache-2.0, BSD-3-Clause Imports: 38 Imported by: 11

Documentation

Overview

Package server contains functions to be ran on a server (no TPM needed), as oppose to a client (with TPM).

Index

Examples

Constants

View Source 
const (
	NoAction                   uint32 = 0x00000003
	Separator                  uint32 = 0x00000004
	SCRTMVersion               uint32 = 0x00000008
	IPL                        uint32 = 0x0000000D
	NonhostInfo                uint32 = 0x00000011
	EFIBootServicesApplication uint32 = 0x80000003
	EFIAction                  uint32 = 0x80000007
)

Expected TCG Event Log Event Types.

Taken from TCG PC Client Platform Firmware Profile Specification, Table 14 Events.

View Source 
const (
	// Measured when Boot Manager attempts to execute code from a Boot Option.
	CallingEFIApplication      string = "Calling EFI Application from Boot Option"
	ExitBootServicesInvocation string = "Exit Boot Services Invocation"
)

Constant events used with type "EV_EFI_ACTION". Taken from TCG PC Client Platform Firmware Profile Specification, Table 17 EV_EFI_ACTION Strings.

Variables

View Source 
var (
	// GCENonHostInfoSignature identifies the GCE Non-Host info event, which
	// indicates if memory encryption is enabled. This event is 32-bytes consisting
	// of the below signature (16 bytes), followed by a byte indicating whether
	// it is confidential, followed by 15 reserved bytes.
	GCENonHostInfoSignature = []byte("GCE NonHostInfo\x00")
	// GceVirtualFirmwarePrefix is the little-endian UCS-2 encoded string
	// "GCE Virtual Firmware v" without a null terminator. All GCE firmware
	// versions are UCS-2 encoded, start with this prefix, contain the firmware
	// version encoded as an integer, and end with a null terminator.
	GceVirtualFirmwarePrefix = []byte{0x47, 0x00, 0x43, 0x00,
		0x45, 0x00, 0x20, 0x00, 0x56, 0x00, 0x69, 0x00, 0x72, 0x00,
		0x74, 0x00, 0x75, 0x00, 0x61, 0x00, 0x6c, 0x00, 0x20, 0x00,
		0x46, 0x00, 0x69, 0x00, 0x72, 0x00, 0x6d, 0x00, 0x77, 0x00,
		0x61, 0x00, 0x72, 0x00, 0x65, 0x00, 0x20, 0x00, 0x76, 0x00}
)
View Source 
var (
	//go:embed secure-boot/GcePk.crt
	GceDefaultPKCert []byte
	//go:embed secure-boot/MicCorKEKCA2011_2011-06-24.crt
	MicrosoftKEKCA2011Cert []byte
	//go:embed secure-boot/MicWinProPCA2011_2011-10-19.crt
	WindowsProductionPCA2011Cert []byte
	//go:embed secure-boot/MicCorUEFCA2011_2011-06-27.crt
	MicrosoftUEFICA2011Cert []byte
)

Standard Secure Boot certificates (DER encoded)

View Source 
var (
	//go:embed secure-boot/canonical-boothole.crt
	RevokedCanonicalBootholeCert []byte
	//go:embed secure-boot/debian-boothole.crt
	RevokedDebianBootholeCert []byte
	//go:embed secure-boot/cisco-boothole.crt
	RevokedCiscoCert []byte
)

Revoked Signing certificates (DER encoded)

View Source 
var (
	GceEKRoots         []*x509.Certificate
	GceEKIntermediates []*x509.Certificate
)

Certificates corresponding to the known CA certs for GCE.

Functions

func ConvertGCEFirmwareVersionToSCRTMVersion added in v0.3.0 

func ConvertGCEFirmwareVersionToSCRTMVersion(version uint32) []byte

ConvertGCEFirmwareVersionToSCRTMVersion creates the corresponding SCRTM version string from a numerical GCE firmware version. The returned string is UCS2 encoded with a null terminator. A version of 0 corresponds to an empty string (representing old GCE VMs that just used an empty string).

func ConvertSCRTMVersionToGCEFirmwareVersion added in v0.3.0 

func ConvertSCRTMVersionToGCEFirmwareVersion(version []byte) (uint32, error)

ConvertSCRTMVersionToGCEFirmwareVersion attempts to parse the Firmware Version of a GCE VM from the bytes of the version string of the SCRTM. This data should come from a valid and verified EV_S_CRTM_VERSION event.

func CreateEKPublicAreaFromKey 

func CreateEKPublicAreaFromKey(k crypto.PublicKey) (tpm2.Public, error)

CreateEKPublicAreaFromKey creates a public area from a go interface PublicKey. Supports RSA and ECC keys.

func CreateImportBlob 

func CreateImportBlob(ekPub crypto.PublicKey, sensitive []byte, pcrs *pb.PCRs) (*pb.ImportBlob, error)

CreateImportBlob uses the provided public EK to encrypt the sensitive data. The returned ImportBlob can then be decrypted and imported using the client Key.Import() method. A non-nil pcrs parameter adds a requirement that the TPM must have specific PCR values for Import() to succeed.

func CreateSigningKeyImportBlob added in v0.2.0 

func CreateSigningKeyImportBlob(ekPub crypto.PublicKey, signingKey crypto.PrivateKey, pcrs *pb.PCRs) (*pb.ImportBlob, error)

CreateSigningKeyImportBlob uses the provided public EK to encrypt the signing key into import blob format. The returned import blob can be used to import the signing key into the TPM associated with the provided EK without exposing the private area to the TPM's OS using the client Key.ImportSigningKey() method. A non-nil pcrs parameter adds a requirement that the TPM must have specific PCR values to use the signing key.

func EvaluatePolicy added in v0.3.0 

func EvaluatePolicy(state *pb.MachineState, policy *pb.Policy) error

EvaluatePolicy succeeds if the provided MachineState complies with the provided policy. If the state does not pass the policy, the returned error will describe in what way the state failed. See the Policy documentation for more information about the specifics of different policies.

func GCEInstanceURL added in v0.3.0 

func GCEInstanceURL(i *pb.GCEInstanceInfo) string

GCEInstanceURL returns a Google API URL to the specified instance. This URL can then be used with GCE instance APIs.

func GetGCEInstanceInfo added in v0.3.10 

func GetGCEInstanceInfo(cert *x509.Certificate) (*pb.GCEInstanceInfo, error)

GetGCEInstanceInfo takes a GCE-issued x509 EK/AK certificate and tries to extract its GCE instance information. It returns an error if the cert is nil or malformed, but it does not return an error if the cert does not contain the GCE Instance OID.

func ParseGCENonHostInfo added in v0.3.0 

func ParseGCENonHostInfo(nonHostInfo []byte) (pb.GCEConfidentialTechnology, error)

ParseGCENonHostInfo attempts to parse the Confidential VM technology used by a GCE VM from the GCE Non-Host info event. This data should come from a valid and verified EV_NONHOST_INFO event.

func SevSnpDefaultValidateOpts added in v0.3.11 

func SevSnpDefaultValidateOpts(tpmNonce []byte) *validate.Options

SevSnpDefaultValidateOpts returns a default validation policy for SEV-SNP attestation reports on GCE.

func SevSnpDefaultValidateOptsForTest added in v0.3.11 

func SevSnpDefaultValidateOptsForTest(tpmNonce []byte) *validate.Options

SevSnpDefaultValidateOptsForTest is a non-production policy only meant for testing. It is more permissive in the kinds of reports it validates, including whether the host is allowed to forcibly decrypt data (for debugging purposes).

func TdxDefaultValidateOpts added in v0.4.3 

func TdxDefaultValidateOpts(tdxNonce []byte) *validate.Options

TdxDefaultValidateOpts returns a default validation policy for TDX attestation quote on GCE.

func VerifyAttestation added in v0.3.0 

func VerifyAttestation(attestation *pb.Attestation, opts VerifyOpts) (*pb.MachineState, error)

VerifyAttestation performs the following checks on an Attestation:

  • the AK used to generate the attestation is trusted (based on VerifyOpts)
  • the provided signature is generated by the trusted AK public key
  • the signature signs the provided quote data
  • the quote data starts with TPM_GENERATED_VALUE
  • the quote data is a valid TPMS_QUOTE_INFO
  • the quote data was taken over the provided PCRs
  • the provided PCR values match the quote data internal digest
  • the provided opts.Nonce matches that in the quote data
  • the provided eventlog matches the provided PCR values

After this, the eventlog is parsed and the corresponding MachineState is returned. This design prevents unverified MachineStates from being used.

Example 
// On client machine, generate the TPM quote.
// TODO: use real TPM.
simulator, err := simulator.Get()
if err != nil {
	log.Fatalf("failed to initialize simulator: %v", err)
}
defer simulator.Close()

ak, err := client.AttestationKeyRSA(simulator)
if err != nil {
	log.Fatalf("failed to generate AK: %v", err)
}
defer ak.Close()

nonce := []byte("super secret nonce")
attestation, err := ak.Attest(client.AttestOpts{Nonce: nonce})
if err != nil {
	log.Fatalf("failed to attest: %v", err)
}

// TODO: send Attestation proto to verifier

// verify the attesation proto
opts := VerifyOpts{
	Nonce:      nonce,
	TrustedAKs: []crypto.PublicKey{ak.PublicKey()},
	AllowSHA1:  true,
}
state, err := VerifyAttestation(attestation, opts)
if err != nil {
	log.Fatalf("failed to verify: %v", err)
}

fmt.Println(state)

Output:

func VerifyGceTechnology added in v0.3.10 

func VerifyGceTechnology(attestation *pb.Attestation, tech pb.GCEConfidentialTechnology, opts *VerifyOpts) error

VerifyGceTechnology checks the GCE-specific GceNonHost event's Trusted Execution Technology (TEE) claim using attestation reports if the technology supports them, and only then validates that a particular technology has proven that it is in use.

func VerifySevSnpAttestation added in v0.3.10 

func VerifySevSnpAttestation(attestation *spb.Attestation, opts *VerifySnpOpts) error

VerifySevSnpAttestation checks that the SEV-SNP attestation report matches expectations for the product.

func VerifyTdxAttestation added in v0.4.1 

func VerifyTdxAttestation(tdxAttestationQuote any, opts *VerifyTdxOpts) error

VerifyTdxAttestation checks that the TDX attestation quote is valid. The TEE-specific attestation quote is extracted from the Attestation protobuf. At a granular level, this quote is fetched via go-tdx-guest's GetQuote client API. Supported quote formats - QuoteV4.

Types

type Bootloader added in v0.3.9 

type Bootloader int

Bootloader refers to the second-stage bootloader that loads and transfers execution to the OS kernel. 

const (
	// UnsupportedLoader refers to a second-stage bootloader that is of an
	// unsupported type. VerifyAttestation will not parse the PCClient Event Log
	// for bootloader events.
	UnsupportedLoader Bootloader = iota
	// GRUB (https://www.gnu.org/software/grub/).
	GRUB
)

type GroupedError added in v0.3.2 

type GroupedError struct {
	// The prefix string returned by `Error()`, followed by the grouped errors.
	Prefix string
	Errors []error
}

GroupedError collects related errors and exposes them as a single error. Users can inspect the `Errors` field for details on the suberrors.

func (*GroupedError) Error added in v0.3.2 

func (gErr *GroupedError) Error() string

type VerifyOpts added in v0.3.0 

type VerifyOpts struct {
	// The nonce used when calling client.Attest
	Nonce []byte
	// Trusted public keys that can be used to directly verify the key used for
	// attestation. This option should be used if you already know the AK, as
	// it provides the highest level of assurance.
	TrustedAKs []crypto.PublicKey
	// Allow using SHA-1 PCRs to verify attestations. This defaults to false
	// because SHA-1 is a weak hash algorithm with known collision attacks.
	// However, setting this to true may be necessary if the client only
	// supports the legacy event log format. This is the case on older Linux
	// distributions (such as Debian 10). Note that this will NOT allow
	// SHA-1 signatures to be used, just SHA-1 PCRs.
	AllowSHA1 bool
	// A collection of trusted root CAs that are used to sign AK certificates.
	// The TrustedAKs are used first, followed by TrustRootCerts and
	// IntermediateCerts.
	// Adding a specific TPM manufacturer's root and intermediate CAs means all
	// TPMs signed by that CA will be trusted.
	TrustedRootCerts  []*x509.Certificate
	IntermediateCerts []*x509.Certificate
	// Which bootloader the instance uses. Pick UNSUPPORTED to skip this
	// parsing or for unsupported bootloaders (e.g., systemd).
	Loader Bootloader
	// TEEOpts allows customizing the functionality of VerifyTEEAttestation.
	// Its type can be *VerifySnpOpts if the TEEAttestation is a SevSnpAttestation
	// or can be *VerifyTdxOpts if the TEEAttestation is a TdxAttestation
	// If nil, uses Nonce for ReportData and the TEE's verification library's
	// embedded root certs for its roots of trust.
	TEEOpts interface{}
}

VerifyOpts allows for customizing the functionality of VerifyAttestation.

type VerifySnpOpts added in v0.3.10 

type VerifySnpOpts struct {
	Validation   *validate.Options
	Verification *sv.Options
}

VerifySnpOpts allows for customizing the functionality of VerifyAttestation's SEV-SNP verification.

func SevSnpDefaultOptions added in v0.3.11 

func SevSnpDefaultOptions(tpmNonce []byte) *VerifySnpOpts

SevSnpDefaultOptions returns a default validation policy and verification options for SEV-SNP attestation reports on GCE.

type VerifyTdxOpts added in v0.4.1 

type VerifyTdxOpts struct {
	Validation   *validate.Options
	Verification *tv.Options
}

VerifyTdxOpts allows for customizing the functionality of VerifyAttestation's TDX verification.

func TdxDefaultOptions added in v0.4.1 

func TdxDefaultOptions(tdxNonce []byte) *VerifyTdxOpts

TdxDefaultOptions returns a default validation policy and verification options for TDX attestation quote on GCE.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.