tcg

package
v0.0.2 Latest Latest
Warning

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

 Go to latest Published: Jan 6, 2025 License: Apache-2.0 Imports: 13 Imported by: 4

Documentation

Overview

Package tcg exposes utilities and constants that correspond to TCG specs including TPM 2.0 and the PC Client Platform Firmware Profile.

Index

Constants

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.

View Source 
const (
	UNKNOWN digestVerified = iota
	VERIFIED
	UNVERIFIED
)

Verified statuses.

Variables

View Source 
var ErrSigMissingGUID = errors.New("signature data was missing owner GUID")

ErrSigMissingGUID is returned if an EFI_SIGNATURE_DATA structure was parsed successfully, however was missing the SignatureOwner GUID. This case is handled specially as a workaround for a bug relating to authority events.

View Source 
var EventTypeNames = map[EventType]string{
	PrebootCert: "Preboot Cert",
	PostCode:    "POST Code",

	NoAction:             "No Action",
	Separator:            "Separator",
	Action:               "Action",
	EventTag:             "Event Tag",
	SCRTMContents:        "S-CRTM Contents",
	SCRTMVersion:         "S-CRTM Version",
	CPUMicrocode:         "CPU Microcode",
	PlatformConfigFlags:  "Platform Config Flags",
	TableOfDevices:       "Table of Devices",
	CompactHash:          "Compact Hash",
	Ipl:                  "IPL",
	IplPartitionData:     "IPL Partition Data",
	NonhostCode:          "Non-Host Code",
	NonhostConfig:        "Non-HostConfig",
	NonhostInfo:          "Non-Host Info",
	OmitBootDeviceEvents: "Omit Boot Device Events",

	EFIEventBase:               "EFI Event Base",
	EFIVariableDriverConfig:    "EFI Variable Driver Config",
	EFIVariableBoot:            "EFI Variable Boot",
	EFIBootServicesApplication: "EFI Boot Services Application",
	EFIBootServicesDriver:      "EFI Boot Services Driver",
	EFIRuntimeServicesDriver:   "EFI Runtime Services Driver",
	EFIGPTEvent:                "EFI GPT Event",
	EFIAction:                  "EFI Action",
	EFIPlatformFirmwareBlob:    "EFI Platform Firmware Blob",
	EFIHandoffTables:           "EFI Handoff Tables",
	EFIPlatformFirmwareBlob2:   "EFI Platform Firmware Blob 2",
	EFIHandoffTables2:          "EFI Handoff Tables 2",
	EFIVariableBoot2:           "EFI Variable Boot2",
	EFIHCRTMEvent:              "EFI H-CRTM Event",
	EFIVariableAuthority:       "EFI Variable Authority",
	// contains filtered or unexported fields
}

EventTypeNames maps an EventType to its name.

View Source 
var EventlogWorkarounds = []elWorkaround{
	{
		// contains filtered or unexported fields
	},
	{
		// contains filtered or unexported fields
	},
	{
		// contains filtered or unexported fields
	},
}

EventlogWorkarounds fix known event log issues/bugs.

Functions

func AppendEvents 

func AppendEvents(base []byte, additional ...[]byte) ([]byte, error)

AppendEvents takes a series of TPM 2.0 event logs and combines them into a single sequence of events with a single header.

Additional logs must not use a digest algorithm which was not present in the original log.

func ConvertToPbEvents 

func ConvertToPbEvents(hash crypto.Hash, events []Event) []*pb.Event

ConvertToPbEvents returns the state.proto Events from the GenericEvents.

Types

type EFIDevicePathElement 

type EFIDevicePathElement struct {
	Type    EFIDeviceType
	Subtype uint8
	Data    []byte
}

EFIDevicePathElement describes an EFI_DEVICE_PATH.

type EFIDeviceType 

type EFIDeviceType uint8

EFIDeviceType describes the type of a device specified by a device path. 

const (
	HardwareDevice  EFIDeviceType = 0x01
	ACPIDevice      EFIDeviceType = 0x02
	MessagingDevice EFIDeviceType = 0x03
	MediaDevice     EFIDeviceType = 0x04
	BBSDevice       EFIDeviceType = 0x05

	EndDeviceArrayMarker EFIDeviceType = 0x7f
)

"Device Path Protocol" type values.

Section 9.3.2 of the UEFI specification, accessible at: https://uefi.org/sites/default/files/resources/UEFI%20Spec%202_6.pdf

type EFIImageLoad 

type EFIImageLoad struct {
	Header      EFIImageLoadHeader
	DevPathData []byte
}

EFIImageLoad describes an EFI_IMAGE_LOAD_EVENT structure.

func ParseEFIImageLoad 

func ParseEFIImageLoad(r io.Reader) (ret EFIImageLoad, err error)

ParseEFIImageLoad parses an EFI_IMAGE_LOAD_EVENT structure.

https://trustedcomputinggroup.org/wp-content/uploads/TCG_EFI_Platform_1_22_Final_-v15.pdf#page=17

func (*EFIImageLoad) DevicePath 

func (h *EFIImageLoad) DevicePath() ([]EFIDevicePathElement, error)

DevicePath returns the device path of an EFI_IMAGE_LOAD_EVENT.

type EFIImageLoadHeader 

type EFIImageLoadHeader struct {
	LoadAddr      uint64
	Length        uint64
	LinkAddr      uint64
	DevicePathLen uint64
}

EFIImageLoadHeader is the header of an EFI_IMAGE_LOAD_EVENT structure.

type EFISignatureData 

type EFISignatureData struct {
	SignatureOwner efiGUID
	SignatureData  []byte // []int8
}

EFISignatureData represents the EFI_SIGNATURE_DATA type. See section "31.4.1 Signature Database" in the specification for more information.

type Event 

type Event struct {

	// Index of the PCR that this event was replayed against.
	Index int
	// Untrusted type of the event. This value is not verified by event log replays
	// and can be tampered with. It should NOT be used without additional context,
	// and unrecognized event types should result in errors.
	Type EventType

	// Data of the event. For certain kinds of events, this must match the event
	// digest to be valid.
	Data []byte
	// Digest is the verified digest of the event data. While an event can have
	// multiple for different hash values, this is the one that was matched to the
	// PCR value.
	Digest []byte
	// contains filtered or unexported fields
}

Event is a single event from a TCG event log. This reports descrete items such as BIOS measurements or EFI states.

There are many pitfalls for using event log events correctly to determine the state of a machine[1]. In general it's much safer to only rely on the raw PCR values and use the event log for debugging.

[1] https://github.com/google/go-attestation/blob/master/docs/event-log-disclosure.md

func ParseAndReplay 

func ParseAndReplay(rawEventLog []byte, mrs []register.MR, parseOpts ParseOpts) ([]Event, error)

ParseAndReplay takes a raw TCG measurement log, parses it, and replays it against the given measurement registers.

func (Event) DigestVerified 

func (e Event) DigestVerified() bool

DigestVerified returns whether the event's data matches its digest. This must not be used before calling EventLog.Verify.

func (Event) MRIndex 

func (e Event) MRIndex() uint32

MRIndex is the event measurement register index.

func (Event) Num 

func (e Event) Num() uint32

Num is the event number.

func (Event) RawData 

func (e Event) RawData() []byte

RawData gives the event data.

func (Event) ReplayedDigest 

func (e Event) ReplayedDigest() []byte

ReplayedDigest gives the event's digest

func (Event) UntrustedType 

func (e Event) UntrustedType() EventType

UntrustedType gives the unmeasured event type.

type EventLog 

type EventLog struct {
	// Algs holds the set of algorithms that the event log uses.
	Algs []register.HashAlg
	// contains filtered or unexported fields
}

EventLog is a parsed measurement log. This contains unverified data representing boot events that must be replayed against PCR values to determine authenticity.

func ParseEventLog 

func ParseEventLog(measurementLog []byte, parseOpts ParseOpts) (*EventLog, error)

ParseEventLog parses an unverified measurement log.

func (*EventLog) Events 

func (e *EventLog) Events(hash register.HashAlg) []Event

Events returns events that have not been replayed against the PCR values and are therefore unverified. The returned events contain the digest that matches the provided hash algorithm, or are empty if that event didn't contain a digest for that hash.

This method is insecure and should only be used for debugging.

func (*EventLog) Verify 

func (e *EventLog) Verify(mrs []register.MR) ([]Event, error)

Verify replays the event log against a TPM's PCR values, returning the events which could be matched to a provided PCR value.

PCRs provide no security guarantees unless they're attested to have been generated by a TPM. Verify does not perform these checks.

An error is returned if the replayed digest for events with a given PCR index do not match any provided value for that PCR index.

type EventType 

type EventType uint32

EventType describes the type of event signalled in the event log. https://trustedcomputinggroup.org/wp-content/uploads/TCG_PCClientSpecPlat_TPM_2p0_1p04_pub.pdf#page=103 

const (
	PrebootCert EventType = 0x00000000
	PostCode    EventType = 0x00000001

	NoAction             EventType = 0x00000003
	Separator            EventType = 0x00000004
	Action               EventType = 0x00000005
	EventTag             EventType = 0x00000006
	SCRTMContents        EventType = 0x00000007
	SCRTMVersion         EventType = 0x00000008
	CPUMicrocode         EventType = 0x00000009
	PlatformConfigFlags  EventType = 0x0000000A
	TableOfDevices       EventType = 0x0000000B
	CompactHash          EventType = 0x0000000C
	Ipl                  EventType = 0x0000000D
	IplPartitionData     EventType = 0x0000000E
	NonhostCode          EventType = 0x0000000F
	NonhostConfig        EventType = 0x00000010
	NonhostInfo          EventType = 0x00000011
	OmitBootDeviceEvents EventType = 0x00000012
)

BIOS Events (TCG PC Client Specific Implementation Specification for Conventional BIOS 1.21) 

const (
	EFIEventBase               EventType = 0x80000000
	EFIVariableDriverConfig    EventType = 0x80000001
	EFIVariableBoot            EventType = 0x80000002
	EFIBootServicesApplication EventType = 0x80000003
	EFIBootServicesDriver      EventType = 0x80000004
	EFIRuntimeServicesDriver   EventType = 0x80000005
	EFIGPTEvent                EventType = 0x80000006
	EFIAction                  EventType = 0x80000007
	EFIPlatformFirmwareBlob    EventType = 0x80000008
	EFIHandoffTables           EventType = 0x80000009
	EFIPlatformFirmwareBlob2   EventType = 0x8000000A
	EFIHandoffTables2          EventType = 0x8000000B
	EFIVariableBoot2           EventType = 0x8000000C
	EFIHCRTMEvent              EventType = 0x80000010
	EFIVariableAuthority       EventType = 0x800000E0
)

EFI Events (TCG EFI Platform Specification Version 1.22)

func UntrustedParseEventType 

func UntrustedParseEventType(et uint32) (EventType, error)

UntrustedParseEventType returns the event type indicated by the provided value.

func (EventType) KnownName 

func (e EventType) KnownName() (string, bool)

KnownName returns an event type's readable name if it exists.

func (EventType) String 

func (e EventType) String() string

String returns an event type's readable name or the hex-formatted string.

func (EventType) TCGString 

func (e EventType) TCGString() string

TCGString returns an event type's string as it appears in the TCG spec.

type ParseOpts 

type ParseOpts struct {
	AllowPadding bool
}

ParseOpts gives options for parsing the event log.

type ReplayError 

type ReplayError struct {
	Events []Event
	// InvalidMRs reports the set of MRs where the event log replay failed.
	InvalidMRs []int
}

ReplayError describes the parsed events that failed to verify against a particular PCR.

func (ReplayError) Error 

func (e ReplayError) Error() string

Error returns a human-friendly description of replay failures.

type TaggedEventData 

type TaggedEventData struct {
	ID   uint32
	Data []byte
}

TaggedEventData represents the TCG_PCClientTaggedEventStruct structure, as defined by 11.3.2.1 in the "TCG PC Client Specific Implementation Specification for Conventional BIOS", version 1.21.

func ParseTaggedEventData 

func ParseTaggedEventData(d []byte) (*TaggedEventData, error)

ParseTaggedEventData parses a TCG_PCClientTaggedEventStruct structure.

type UEFIVariableAuthority 

type UEFIVariableAuthority struct {
	Certs []x509.Certificate
}

UEFIVariableAuthority describes the contents of a UEFI variable authority event.

func ParseUEFIVariableAuthority 

func ParseUEFIVariableAuthority(v UEFIVariableData) (UEFIVariableAuthority, error)

ParseUEFIVariableAuthority parses the data section of an event structured as a UEFI variable authority.

https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_final.pdf#page=1789

type UEFIVariableData 

type UEFIVariableData struct {
	Header       UEFIVariableDataHeader
	UnicodeName  []uint16
	VariableData []byte // []int8
}

UEFIVariableData represents the UEFI_VARIABLE_DATA structure.

func ParseUEFIVariableData 

func ParseUEFIVariableData(r io.Reader) (ret UEFIVariableData, err error)

ParseUEFIVariableData parses the data section of an event structured as a UEFI variable.

https://trustedcomputinggroup.org/wp-content/uploads/TCG_PCClient_Specific_Platform_Profile_for_TPM_2p0_1p04_PUBLIC.pdf#page=100

func (*UEFIVariableData) SignatureData 

func (v *UEFIVariableData) SignatureData() (certs []x509.Certificate, hashes [][]byte, err error)

SignatureData parses a UEFI variable for signature data.

func (*UEFIVariableData) VarName 

func (v *UEFIVariableData) VarName() string

VarName returns the UEFI variable name.

type UEFIVariableDataHeader 

type UEFIVariableDataHeader struct {
	VariableName       efiGUID
	UnicodeNameLength  uint64 // uintN
	VariableDataLength uint64 // uintN
}

UEFIVariableDataHeader represents the leading fixed-size fields within UEFI_VARIABLE_DATA.

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.