cel

Documentation

Overview

Package cel contains some basic operations of Canonical Eventlog. Based on Canonical EventLog Spec (Draft) Version: TCG_IWG_CEL_v1_r0p37.

Index

• Constants
• func FormatEnvVar(name string, value string) (string, error)
• func ParseEnvVar(envvar string) (string, string, error)
• func VerifyDigests(c Content, digestMap map[crypto.Hash][]byte) error
• type CEL
  • func DecodeToCEL(buf *bytes.Buffer) (CEL, error)
  • func (c *CEL) AppendEvent(tpm io.ReadWriteCloser, pcr int, hashAlgos []crypto.Hash, event Content) error
  • func (c *CEL) AppendEventPCR(tpm io.ReadWriteCloser, pcr int, hashAlgos []crypto.Hash, event Content) error
  • func (c *CEL) AppendEventRTMR(client configfsi.Client, rtmrIndex int, event Content) error
  • func (c *CEL) EncodeCEL(buf *bytes.Buffer) error
  • func (c *CEL) Replay(regs register.MRBank) error
• type Content
• type CosTlv
  • func (c CosTlv) GenerateDigest(hashAlgo crypto.Hash) ([]byte, error)
  • func (c CosTlv) GetTLV() (TLV, error)
• type CosType
• type Record
  • func DecodeToCELR(buf *bytes.Buffer) (r Record, err error)
  • func (r *Record) EncodeCELR(buf *bytes.Buffer) error
• type TLV
  • func UnmarshalFirstTLV(buf *bytes.Buffer) (tlv TLV, err error)
  • func (t TLV) IsCosTlv() bool
  • func (t TLV) MarshalBinary() (data []byte, err error)
  • func (t TLV) ParseToCosTlv() (CosTlv, error)
  • func (t *TLV) UnmarshalBinary(data []byte) error

Constants

const (

	// PCRTypeValue indicates a PCR event index
	PCRTypeValue uint8 = 1

	// CCMRTypeValue indicates a RTMR event index
	CCMRTypeValue uint8 = 108 // not in the CEL spec

)

const (
	// CosEventType indicates the CELR event is a COS content
	// TODO: the value needs to be reserved in the CEL spec
	CosEventType uint8 = 80
	// CosEventPCR is the PCR which should be used for CosEventType events.
	CosEventPCR = 13
	// CosRTMR is the RTMR to be extended for COS events
	// According to https://uefi.org/specs/UEFI/2.10/38_Confidential_Computing.html
	// CCELMRIndex      TDX Register
	// 0                   MRTD
	// 1                   RTMR[0]
	// 2                   RTMR[1]
	// 3                   RTMR[2]
	// So:
	// 4                   RTMR[3]
	CosRTMR = 3
	// CosCCELMRIndex is the CCMR index to use in eventlog for COS events.
	CosCCELMRIndex = 4
)

Functions

func FormatEnvVar

func FormatEnvVar(name string, value string) (string, error)

FormatEnvVar takes in an environment variable name and its value, run some checks. Concats the name and value by '=' and returns it if valid; returns an error if the name or value is invalid.

func ParseEnvVar

func ParseEnvVar(envvar string) (string, string, error)

ParseEnvVar takes in environment variable as a string (foo=bar), parses it and returns its name and value, or an error if it fails the validation check.

func VerifyDigests

func VerifyDigests(c Content, digestMap map[crypto.Hash][]byte) error

VerifyDigests checks the digest generated by the given record's content to make sure they are equal to the digests in the digestMap.

Types

type CEL

type CEL struct {
	Records []Record
}

CEL represents a Canonical Eventlog, which contains a list of Records.

func DecodeToCEL

func DecodeToCEL(buf *bytes.Buffer) (CEL, error)

DecodeToCEL will read the buf for CEL, will return err if the buffer is not complete.

func (*CEL) AppendEvent

func (c *CEL) AppendEvent(tpm io.ReadWriteCloser, pcr int, hashAlgos []crypto.Hash, event Content) error

AppendEvent appends a new PCR record to the CEL. This function is a wrapper of AppendEventPCR, for backward compatibility.

func (*CEL) AppendEventPCR

func (c *CEL) AppendEventPCR(tpm io.ReadWriteCloser, pcr int, hashAlgos []crypto.Hash, event Content) error

AppendEventPCR appends a new PCR record to the CEL.

func (*CEL) AppendEventRTMR

func (c *CEL) AppendEventRTMR(client configfsi.Client, rtmrIndex int, event Content) error

AppendEventRTMR appends a new RTMR record to the CEL. rtmrIndex indicates the RTMR to extend. The index showing up in the record will be rtmrIndex + 1.

func (*CEL) EncodeCEL

func (c *CEL) EncodeCEL(buf *bytes.Buffer) error

EncodeCEL encodes the CEL to bytes according to the CEL spec and write them to the bytes buffer.

func (*CEL) Replay

func (c *CEL) Replay(regs register.MRBank) error

Replay takes the digests from a Canonical Event Log and carries out the extend sequence for each register (PCR, RTMR) in the log. It then compares the final digests against a bank of register values to see if they match. make sure CEL has only one indexType event

type Content

type Content interface {
	GenerateDigest(crypto.Hash) ([]byte, error)
	GetTLV() (TLV, error)
}

Content is a interface for the content in CELR.

type CosTlv

type CosTlv struct {
	EventType    CosType
	EventContent []byte
}

CosTlv is a specific event type created for the COS (Google Container-Optimized OS), used as a CEL content.

func (CosTlv) GenerateDigest

func (c CosTlv) GenerateDigest(hashAlgo crypto.Hash) ([]byte, error)

GenerateDigest generates the digest for the given COS TLV. The whole TLV struct will be marshaled to bytes and feed into the hash algo.

func (CosTlv) GetTLV

func (c CosTlv) GetTLV() (TLV, error)

GetTLV returns the TLV representation of the COS TLV.

type CosType

type CosType uint8

CosType represent a COS content type in a CEL record content.

const (
	ImageRefType CosType = iota
	ImageDigestType
	RestartPolicyType
	ImageIDType
	ArgType
	EnvVarType
	OverrideArgType
	OverrideEnvType
	// EventContent is empty on success, or contains an error message on failure.
	LaunchSeparatorType
	MemoryMonitorType
)

Type for COS nested events

type Record

type Record struct {
	RecNum uint64
	// Generic Measurement Register index number, register type
	// is determined by IndexType
	Index     uint8
	IndexType uint8
	Digests   map[crypto.Hash][]byte
	Content   TLV
}

Record represents a Canonical Eventlog Record.

func DecodeToCELR

func DecodeToCELR(buf *bytes.Buffer) (r Record, err error)

DecodeToCELR will read the buf for the next CELR, will return err if failed to unmarshal a correct CELR TLV from the buffer.

func (*Record) EncodeCELR

func (r *Record) EncodeCELR(buf *bytes.Buffer) error

EncodeCELR encodes the CELR to bytes according to the CEL spec and write them to the bytes byffer.

type TLV

type TLV struct {
	Type  uint8
	Value []byte
}

TLV definition according to CEL spec TCG_IWG_CEL_v1_r0p37, page 16. Length is implicitly defined by len(Value), using uint32 big-endian when encoding.

func UnmarshalFirstTLV

func UnmarshalFirstTLV(buf *bytes.Buffer) (tlv TLV, err error)

UnmarshalFirstTLV reads and parse the first TLV from the bytes buffer. The function will return io.EOF if the buf ends unexpectedly or cannot fill the TLV.

func (TLV) IsCosTlv

func (t TLV) IsCosTlv() bool

IsCosTlv check whether a TLV is a COS TLV by its Type value.

func (TLV) MarshalBinary

func (t TLV) MarshalBinary() (data []byte, err error)

MarshalBinary marshals a TLV to a byte slice.

func (TLV) ParseToCosTlv

func (t TLV) ParseToCosTlv() (CosTlv, error)

ParseToCosTlv constructs a CosTlv from a TLV. It will check for the correct COS event type, and unmarshal the nested event.

func (*TLV) UnmarshalBinary

func (t *TLV) UnmarshalBinary(data []byte) error

UnmarshalBinary unmarshal a byte slice to a TLV.