open

Documentation

Index

• Variables
• type CborCdiCert
  • func (o *CborCdiCert) GetEntry() *Entry
  • func (o *CborCdiCert) UnmarshalCBOR(data []byte) error
• type CborCdiCertClaims
• type CborUdsCert
  • func (o *CborUdsCert) UnmarshalCBOR(data []byte) error
• type CborUdsCertClaims
• type Config
• type Entry
  • func ExtractChainFromCbor(data []byte, roots []*CborUdsCert, verify bool) ([]*Entry, error)
  • func ExtractChainFromX509(data any, roots any, verify bool) ([]*Entry, error)
  • func (o *Entry) GetConfigDetails() (*Config, error)
• type Mode
  • func (o Mode) IsValid() bool
• type X509CdiCert
  • func (o *X509CdiCert) GetCdiID() []byte
  • func (o *X509CdiCert) GetEntry() *Entry
  • func (o *X509CdiCert) GetUdsID() []byte
  • func (o *X509CdiCert) PopulateFromX509Cert(x509Cert *x509.Certificate) error
  • func (o *X509CdiCert) Unmarshal(data []byte) error
• type X509CdiExt

Variables

var X509CdiExtOid = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 11129, 2, 1, 24}

X509CdiExtOid encodes the Open-DICE custom x509 extension OID

Types

type CborCdiCert

type CborCdiCert struct {
	CborCdiCertClaims
	// Raw bytes of the certificate
	Raw []byte
	// SubjectPublicKey is the cose.Key parsed from subjectPublicKey field.
	SubjectPublicKey *cose.Key
	// Cose is the parsed COSE_Sign1 structure form the certificate.
	Cose *cose.UntaggedSign1Message
}

CborCdiCert rersents a CBOR CDI certificate.

func (*CborCdiCert) GetEntry

func (o *CborCdiCert) GetEntry() *Entry

GetEntry extracts an Entry from the cert.

func (*CborCdiCert) UnmarshalCBOR

func (o *CborCdiCert) UnmarshalCBOR(data []byte) error

UnmarshalCBOR decodes an untagged COSE_Sign1 structure into an CborCdiCert.

type CborCdiCertClaims

type CborCdiCertClaims struct {
	// Standard CWT fields. See:
	//	https://www.rfc-editor.org/rfc/rfc8392
	Issuer         string `cbor:"1,keyasint" json:"iss"`
	Subject        string `cbor:"2,keyasint" json:"sub"`
	ExpirationTime int    `cbor:"4,keyasint,omitempty" json:"exp,omitempty"`
	NotBefore      int    `cbor:"5,keyasint,omitempty" json:"nbf,omitempty"`
	IssuedAt       int    `cbor:"6,keyasint,omitempty" json:"iat,omitempty"`

	// Additional, OpenDICE-defined fields. See:
	//	https://pigweed.googlesource.com/open-dice/+/HEAD/docs/specification.md#profile-design-certificate-details-cbor-cdi-certificates-additional-fields
	CodeHash                []byte  `cbor:"-4670545,keyasint" json:"codeHash"`
	CodeDescriptor          []byte  `cbor:"-4670546,keyasint,omitempty" json:"codeDescriptor,omitempty"`
	ConfigurationHash       []byte  `cbor:"-4670547,keyasint,omitempty" json:"configurationHash,omitempty"`
	ConfigurationDescriptor []byte  `cbor:"-4670548,keyasint,omitempty" json:"configurationDescriptor,omitempty"`
	AuthorityHash           []byte  `cbor:"-4670549,keyasint" json:"authorityHash"`
	AuthorityDescriptor     []byte  `cbor:"-4670550,keyasint,omitempty" json:"authorityDescriptor,omitempty"`
	Mode                    [1]byte `cbor:"-4670551,keyasint" json:"mode"`

	RawSubjectPublicKey []byte `cbor:"-4670552,keyasint" json:"subjectPublicKey"`
	KeyUsage            []byte `cbor:"-4670553,keyasint" json:"keyUsage"`
}

CborCdiCertClaims represents the claims extracted from a CBOR CDI certificate.

type CborUdsCert

type CborUdsCert struct {
	CborUdsCertClaims

	// SubjectPublicKey is the decoded COSE_Key containing UDS_Public
	SubjectPublicKey *cose.Key
}

CborUdsCert represents an Open DICE UDS certificate.

func (*CborUdsCert) UnmarshalCBOR

func (o *CborUdsCert) UnmarshalCBOR(data []byte) error

UnmarshalCBOR decodes a CBOR UDS certificate.

type CborUdsCertClaims

type CborUdsCertClaims struct {

	// Issuer identifies the principal that issued the certificate. The
	// value is implementation-dependant.
	Issuer string `cbor:"1,keyasint" json:"iss"`
	// Subject identifies the principal that is the subject of the
	// certificate. This must set to the UDS_ID.
	Subject string `cbor:"2,keyasint" json:"sub"`

	// RawSubjectPublicKey is the bstr-encoded COSE_Key containing UDS_Public
	RawSubjectPublicKey []byte `cbor:"-4670552,keyasint" json:"subjectPublicKey"`
	// KeyUsage bits are set according to X.509 key usage. See:
	// https://www.rfc-editor.org/rfc/rfc8392#section-3.1.2
	KeyUsage []byte `cbor:"-4670553,keyasint" json:"keyUsage"`
}

CborCdiCertClaims represents the claims extracted from a CBOR UDS certificate.

type Config

type Config struct {
	// EnabledVerifiedBootAuthorities is indicates which verified boot
	// authorities have been enabled (empty if VerifiedBootEnabled is
	// false).
	EnabledVerifiedBootAuthorities []int
	// Version encodes target software version information.
	Version uint16
	// ImplementationSpecific may be used by an implementation for any
	// other security-relevant configuration.
	ImplementationSpecific [32]byte
	// VerifiedBootEnabled indicates whether a verified boot feature is enabled.
	VerifiedBootEnabled bool
	// DebugPortsEnabled is a bit map indicating which debug ports and
	// features have been enabled.
	DebugPortsEnabled byte
	// BootSource indicates where the target software was loaded from.
	BootSource byte
}

Config represents the configurationDescriptor decoded according to the convention specified in the Open DICE profile. See: https://pigweed.googlesource.com/open-dice/+/refs/heads/main/docs/specification.md#configuration-input-value-details-optional

type Entry

type Entry struct {
	// UdsID is an identifier derived from the UDS (or, in case of multiple
	// layers, previous layer's CDI) public key.
	UdsID []byte `json:"UDS_ID"`

	// CdiID  is an identifier derived from the (this layer's) CDI public
	// key.
	CdiID []byte `json:"CDI_ID"`

	// CodeHash is the exact 64-byte code input value used to compute CDI values.
	CodeHash []byte `json:"codeHash"`
	// CodeDescriptor contains additional information about CodeHash.
	CodeDescriptor []byte `json:"codeDescriptor,omitempty"`
	// ConfigurationHash is the exact 64-byte configuration input value
	// used to compute CDI values.
	ConfigurationHash []byte `json:"configurationHash,omitempty"`
	// ConfigurationDescriptor contains the original configuration data, if
	// ConfigurationHash is present. Otherwise, it contains the exact
	// 64-byte configuration input data used to compute CDI values.
	ConfigurationDescriptor []byte `json:"configurationDescriptor"`
	// AuthorityHash is the exact 64-byte authority input value used to
	// compute CDI values.
	AuthorityHash []byte `json:"authorityHash"`
	// AuthorityDescriptor contains additional information about the
	// authority input value.
	AuthorityDescriptor []byte `json:"authorityDescriptor,omitempty"`
	// Mode is the mode input value.
	Mode Mode `json:"mode"`
}

Entry represents Open DICE-relevant claims extracted from a certificate (either CBOR or X.509).

func ExtractChainFromCbor

func ExtractChainFromCbor(
	data []byte,
	roots []*CborUdsCert,
	verify bool,
) ([]*Entry, error)

ExtractChainFromCbor extracts Open DICE claim entries from a concatenated chain of CBOR CDI certificates. If verify is true, the signatures on the certificates are verified, and chained back to the provided UDS certificate.

func ExtractChainFromX509

func ExtractChainFromX509(
	data any,
	roots any,
	verify bool,
) ([]*Entry, error)

ExtractChainFromX509 processes a chain of x509 certificates, extracting the Open DICE data from each, retruning a slice of *Entry, where the order matches the order of x509 certs in the input. If verify is true, each certificate in the chain is also verified by chaining it back to the root. The certs in the input are assumed to be in order, starting with DICE Layer 0. See: https://trustedcomputinggroup.org/wp-content/uploads/DICE-Layering-Architecture-r19_pub.pdf Input certificates and roots must be either []byte containing concatenated DER-encoded certs, or []*x509.Certificate (the types of othe two parameters do not need to match).

func (*Entry) GetConfigDetails

func (o *Entry) GetConfigDetails() (*Config, error)

GetConfigDetails parses the Entry's ConfigurationDescriptor into an Config entry.

type Mode

type Mode uint8

Mode represents the value of the Mode field inside the Open DICE custom extension. See: https://pigweed.googlesource.com/open-dice/+/refs/heads/master/docs/specification.md#Mode-Value-Details

const (
	// OdmNotConfigured indicates that at least one security mechanism has
	// not been configured. This mode also acts as a catch-all for
	// configurations which do not fit the other modes. Invalid mode values
	// -- values not defined here -- should be treated like this mode.
	OdmNotConfigured Mode = iota
	// OdmNormal indicates the device is operating normally under secure
	// configuration. This may mean, for example: Verified boot is enabled,
	// verified boot authorities used for development or debug have been
	// disabled, debug ports or other debug facilities have been disabled,
	// and the device booted software from the normal primary source, for
	// example, eMMC, not USB, network, or removable storage.
	OdmNormal
	// OdmDebug indicates at least one criteria for Normal mode is not met
	// and the device is not in a secure state.
	OdmDebug
	// OdmRecovery indicates a recovery or maintenance mode of some kind.
	// This may mean software is being loaded from an alternate source, or
	// the device is configured to trigger recovery logic instead of a
	// normal boot flow.
	OdmRecovery

	OdmInvalid // must be last
)

func (Mode) IsValid

func (o Mode) IsValid() bool

IsValid returns a boolean indicating whether the the mode value is valid.

type X509CdiCert

type X509CdiCert struct {
	x509.Certificate
	X509CdiExt
}

X509CdiCert represents the decoded X.509 CID certificate.

func (*X509CdiCert) GetCdiID

func (o *X509CdiCert) GetCdiID() []byte

GetCdiID returns the cert's CDI_ID.

func (*X509CdiCert) GetEntry

func (o *X509CdiCert) GetEntry() *Entry

GetEntry returns an Entry popluated from the X509CdiCert.

func (*X509CdiCert) GetUdsID

func (o *X509CdiCert) GetUdsID() []byte

GetUdsID returns the cert's UDS_ID.

func (*X509CdiCert) PopulateFromX509Cert

func (o *X509CdiCert) PopulateFromX509Cert(x509Cert *x509.Certificate) error

PopulateFromX509Cert populatess the X509CdiCert from the provided x509.Certificate (which must contain the custom CDI extension).

func (*X509CdiCert) Unmarshal

func (o *X509CdiCert) Unmarshal(data []byte) error

Unmarshal decodes the der-encoded X.509 data into the X509CdiCert.

type X509CdiExt

type X509CdiExt struct {
	CodeHash                []byte          `asn1:"tag:0,explicit"`
	CodeDescriptor          []byte          `asn1:"tag:1,explicit,optional"`
	ConfigurationHash       []byte          `asn1:"tag:2,explicit,optional"`
	ConfigurationDescriptor []byte          `asn1:"tag:3,explicit"`
	AuthorityHash           []byte          `asn1:"tag:4,explicit,optional"`
	AuthorityDescriptor     []byte          `asn1:"tag:5,explicit,optional"`
	Mode                    asn1.Enumerated `asn1:"tag:6,explicit"`
}

X509CdiExt is the custom X.509 cert extension for CDI. See: https://pigweed.googlesource.com/open-dice/+/refs/heads/master/docs/specification.md#custom-extension-format