pcs

package
v0.2300.10 Latest Latest
Warning

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

Go to latest
Published: Mar 4, 2024 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source
const (
	CertificationDataPPIDCleartext        = 1
	CertificationDataPPIDEncryptedRSA2048 = 2
	CertificationDataPPIDEncryptedRSA3072 = 3
	CertificationDataPCKLeafCertificate   = 4
	CertificationDataPCKCertificateChain  = 5
	CertificationDataPlatformManifest     = 7
)
View Source
const (
	// TCBKindPlatform is the platform TCB kind (e.g. the CPU/microcode/config).
	TCBKindPlatform = 0
	// TCBKindEnclave is the enclave TCB kind (e.g. the QE).
	TCBKindEnclave = 1
)
View Source
const (

	// DefaultMinTCBEvaluationDataNumber is the default minimum TCB evaluation data number.
	DefaultMinTCBEvaluationDataNumber = 12 // As of 2022-08-01.
)
View Source
const TimestampFormat = "2006-01-02T15:04:05.999999999Z"

TimestampFormat is the format of the TCB timestamp, suitable for use with time.Parse.

Workaround for https://github.com/golang/go/issues/21990

Variables

View Source
var (
	// PCK_SGX_Extensions is the ASN1 Object Identifier for the SGX Extensions X509 extension.
	PCK_SGX_Extensions = asn1.ObjectIdentifier{1, 2, 840, 113741, 1, 13, 1} // nolint: revive

	// PCK_SGX_Extensions_FMSPC is the ASN1 Object Identifier for the FMSPC SGX Extension.
	PCK_SGX_Extensions_FMSPC = asn1.ObjectIdentifier{1, 2, 840, 113741, 1, 13, 1, 4} // nolint: revive

	// PCK_SGX_Extensions_TCB is the ASN1 Object Identifier for the TCB SGX Extension.
	PCK_SGX_Extensions_TCB = asn1.ObjectIdentifier{1, 2, 840, 113741, 1, 13, 1, 2} // nolint: revive
)
View Source
var IntelTrustRoots = func() *x509.CertPool {
	pool := x509.NewCertPool()
	if raw := []byte(pcsTrustRootCert); !pool.AppendCertsFromPEM(raw) {

		_, _, err := CertFromPEM(raw)
		panic("sgx/pcs: invalid Intel trust root cert: " + err.Error())
	}
	return pool
}()

IntelTrustRoots are Intel's PCS signing root certificates.

View Source
var QEVendorID_Intel = []byte{0x93, 0x9a, 0x72, 0x33, 0xf7, 0x9c, 0x4c, 0xa9, 0x94, 0x0a, 0x0d, 0xb3, 0x95, 0x7f, 0x06, 0x07} // nolint: revive

QEVendorID_Intel is the Quoting Enclave vendor ID for Intel (939A7233F79C4CA9940A0DB3957F0607).

Functions

func BuildMrSignerBlacklist

func BuildMrSignerBlacklist(allowTestKeys bool)

BuildMrSignerBlacklist builds the MRSIGNER blacklist.

func CertFromPEM

func CertFromPEM(raw []byte) (*x509.Certificate, []byte, error)

func SetAllowDebugEnclaves

func SetAllowDebugEnclaves()

SetAllowDebugEnclaves will enable running and communicating with enclaves with debug flag enabled in report body for the remainder of the process' lifetime.

func UnsetAllowDebugEnclaves

func UnsetAllowDebugEnclaves()

UnsetAllowDebugEnclaves will disable running and communicating with enclaves with debug flag enabled in report body for the remainder of the process' lifetime.

Types

type AttestationKeyType

type AttestationKeyType uint16

AttestationKeyType is the attestation key type.

const (
	// AttestationKeyECDSA_P256 is the ECDSA-P256 attestation key type.
	AttestationKeyECDSA_P256 AttestationKeyType = 2 // nolint: revive
)

func (AttestationKeyType) String

func (kt AttestationKeyType) String() string

String returns a string representation of the attestation key type.

type CertificationData

type CertificationData interface {
	// CertificationDataType returns the certification data type.
	CertificationDataType() CertificationDataType
}

CertificationData is the data required to verify the QE Report signature.

type CertificationDataType

type CertificationDataType uint16

CertificationDataType is the type of data required to verify the QE Report signature in the QuoteSignature data structure.

func (CertificationDataType) String

func (ct CertificationDataType) String() string

type CertificationData_PCKCertificateChain

type CertificationData_PCKCertificateChain struct {
	CertificateChain []*x509.Certificate
}

CertificationData_PCKCertificateChain is the PCK certificate chain certification data.

func (*CertificationData_PCKCertificateChain) CertificationDataType

CertificationDataType returns the certification data type.

func (*CertificationData_PCKCertificateChain) UnmarshalBinary

func (cd *CertificationData_PCKCertificateChain) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes CertificationData_PCKCertificateChain from a byte array.

type CertificationData_PPID

type CertificationData_PPID struct {
	PPID   [384]byte
	CPUSVN [16]byte
	PCESVN uint16
	PCEID  uint16
	// contains filtered or unexported fields
}

CertificationData_PPID is the PPID certification data.

func (*CertificationData_PPID) CertificationDataType

func (cd *CertificationData_PPID) CertificationDataType() CertificationDataType

CertificationDataType returns the certification data type.

func (*CertificationData_PPID) UnmarshalBinary

func (cd *CertificationData_PPID) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes CertificationData_PPID from a byte array.

type Client

type Client interface {
	// GetTCBBundle retrieves the signed TCB artifacts needed to verify a quote.
	GetTCBBundle(ctx context.Context, fmspc []byte, update UpdateType) (*TCBBundle, error)

	// GetPCKCertificateChain retrieves the PCK certificate chain for the given platform data or PPID.
	//
	// If platform data is provided, it is used instead of the encrypted PPID for certificate retrieval.
	GetPCKCertificateChain(ctx context.Context, platformData []byte, encPpid [384]byte, cpusvn [16]byte, pcesvn uint16, pceid uint16) ([]*x509.Certificate, error)
}

Client is an Intel SGX PCS client interface.

func NewHTTPClient

func NewHTTPClient(cfg *HTTPClientConfig) (Client, error)

NewHTTPClient returns a new PCS HTTP endpoint.

type EnclaveTCBLevel

type EnclaveTCBLevel struct {
	TCB struct {
		ISVSVN uint16 `json:"isvsvn"`
	} `json:"tcb"`
	Date        string    `json:"tcbDate"`
	Status      TCBStatus `json:"tcbStatus"`
	AdvisoryIDs []string  `json:"advisoryIDs"`
}

EnclaveTCBLevel is the enclave TCB level.

type HTTPClientConfig

type HTTPClientConfig struct {
	// SubscriptionKey is the Intel PCS API key used for client authentication (needed for PCK
	// certificate retrieval).
	SubscriptionKey string
}

HTTPClientConfig is the Intel SGX PCS client configuration.

type PCKInfo

type PCKInfo struct {
	PublicKey  *ecdsa.PublicKey
	FMSPC      []byte
	TCBCompSVN [16]int32
	PCESVN     uint16
	CPUSVN     [16]byte
}

PCKInfo contains information extracted from the PCK certificate.

type QEIdentity

type QEIdentity struct {
	ID                      string            `json:"id"`
	Version                 int               `json:"version"`
	IssueDate               string            `json:"issueDate"`
	NextUpdate              string            `json:"nextUpdate"`
	TCBEvaluationDataNumber uint32            `json:"tcbEvaluationDataNumber"`
	MiscSelect              string            `json:"miscselect"`
	MiscSelectMask          string            `json:"miscselectMask"`
	Attributes              string            `json:"attributes"`
	AttributesMask          string            `json:"attributesMask"`
	MRSIGNER                string            `json:"mrsigner"`
	ISVProdID               uint16            `json:"isvprodid"`
	TCBLevels               []EnclaveTCBLevel `json:"tcbLevels"`
	AdvisoryIDs             []int             `json:"advisoryIDs,omitempty"`
}

QEIdentity is the Quoting Enclave identity.

type Quote

type Quote struct {
	Header    QuoteHeader
	ISVReport ReportBody
	Signature QuoteSignature
}

Quote is an enclave quote.

func (*Quote) UnmarshalBinary

func (q *Quote) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes a Quote from a byte array.

func (*Quote) Verify

func (q *Quote) Verify(policy *QuotePolicy, ts time.Time, tcb *TCBBundle) (*sgx.VerifiedQuote, error)

Verify verifies the quote.

In case of successful verification it returns the TCB level.

type QuoteBundle

type QuoteBundle struct {
	// Quote is the raw attestation quote.
	Quote []byte `json:"quote"`

	// TCB is the TCB bundle required to verify an attestation quote.
	TCB TCBBundle `json:"tcb"`
}

QuoteBundle is an attestation quote together with the TCB bundle required for its verification.

func (*QuoteBundle) Verify

func (bnd *QuoteBundle) Verify(policy *QuotePolicy, ts time.Time) (*sgx.VerifiedQuote, error)

Verify verifies the quote bundle.

In case of successful verification it returns the verified quote.

type QuoteHeader

type QuoteHeader struct {
	Version    uint16
	TEEType    uint32
	QESVN      uint16
	PCESVN     uint16
	QEVendorID [16]byte
	UserData   [20]byte
	// contains filtered or unexported fields
}

QuoteHeader is a quote header.

func (*QuoteHeader) UnmarshalBinary

func (qh *QuoteHeader) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes QuoteHeader from a byte array.

type QuotePolicy

type QuotePolicy struct {
	// Disabled specifies whether PCS quotes are disabled and will always be rejected.
	Disabled bool `json:"disabled,omitempty"`

	// TCBValidityPeriod is the validity (in days) of the TCB collateral.
	TCBValidityPeriod uint16 `json:"tcb_validity_period"`

	// MinTCBEvaluationDataNumber is the minimum TCB evaluation data number that is considered to be
	// valid. TCB bundles containing smaller values will be invalid.
	MinTCBEvaluationDataNumber uint32 `json:"min_tcb_evaluation_data_number"`

	// FMSPCBlacklist is a list of hexadecimal encoded FMSPCs specifying which processor
	// packages and platform instances are blocked.
	FMSPCBlacklist []string `json:"fmspc_blacklist,omitempty"`
}

QuotePolicy is the quote validity policy.

type QuoteSignature

type QuoteSignature interface {
	// AttestationKeyType returns the type of the attestation key used in this quote signature.
	AttestationKeyType() AttestationKeyType

	// Verify verifies the quote signature of the header and ISV report.
	Verify(
		header *QuoteHeader,
		isvReport *ReportBody,
		ts time.Time,
		tcb *TCBBundle,
		policy *QuotePolicy,
	) error
}

QuoteSignature is a quote signature.

type QuoteSignatureECDSA_P256

type QuoteSignatureECDSA_P256 struct {
	Signature            SignatureECDSA_P256
	AttestationPublicKey [64]byte
	QEReport             ReportBody
	QESignature          SignatureECDSA_P256
	AuthenticationData   []byte
	CertificationData    CertificationData
}

QuoteSignatureECDSA_P256 is an ECDSA-P256 quote signature.

func (*QuoteSignatureECDSA_P256) AttestationKeyType

func (qs *QuoteSignatureECDSA_P256) AttestationKeyType() AttestationKeyType

AttestationKeyType returns the type of the attestation key used in this quote signature.

func (*QuoteSignatureECDSA_P256) UnmarshalBinary

func (qs *QuoteSignatureECDSA_P256) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes QuoteSignatureECDSA_P256 from a byte array.

func (*QuoteSignatureECDSA_P256) Verify

func (qs *QuoteSignatureECDSA_P256) Verify(
	header *QuoteHeader,
	isvReport *ReportBody,
	ts time.Time,
	tcb *TCBBundle,
	policy *QuotePolicy,
) error

Verify verifies the quote signature.

func (*QuoteSignatureECDSA_P256) VerifyPCK

func (qs *QuoteSignatureECDSA_P256) VerifyPCK(ts time.Time) (*PCKInfo, error)

VerifyPCK verifies the PCK certificate and returns the extracted information.

type ReportBody

type ReportBody struct {
	CPUSVN     [16]byte
	MiscSelect uint32
	Attributes sgx.Attributes
	MRENCLAVE  sgx.MrEnclave
	MRSIGNER   sgx.MrSigner
	ISVProdID  uint16
	ISVSVN     uint16
	ReportData [64]byte
	// contains filtered or unexported fields
}

ReportBody is an enclave report body.

func (*ReportBody) MarshalBinary

func (r *ReportBody) MarshalBinary() ([]byte, error)

MarshalBinary encodes ReportBody into byte array.

func (*ReportBody) UnmarshalBinary

func (r *ReportBody) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes ReportBody from a byte array.

type SGXExtension

type SGXExtension struct {
	Id    asn1.ObjectIdentifier // nolint: revive
	Value asn1.RawValue
}

SGXExtension is an ASN1 SGX extension.

type SignatureECDSA_P256

type SignatureECDSA_P256 [64]byte // nolint: revive

SignatureECDSA_P256 is an ECDSA-P256 signature in the form r || s.

func (*SignatureECDSA_P256) UnmarshalHex

func (ec *SignatureECDSA_P256) UnmarshalHex(data string) error

UnmarshalHex decodes the signature from a hex-encoded string.

func (*SignatureECDSA_P256) Verify

func (ec *SignatureECDSA_P256) Verify(pk *ecdsa.PublicKey, hash []byte) bool

Verify verifies the signature of hash using the passed public key.

type SignedQEIdentity

type SignedQEIdentity struct {
	EnclaveIdentity json.RawMessage `cbor:"enclave_identity" json:"enclaveIdentity"`
	Signature       string          `cbor:"signature" json:"signature"`
}

SignedQEIdentity is the signed Quoting Enclave identity.

type SignedTCBInfo

type SignedTCBInfo struct {
	TCBInfo   json.RawMessage `cbor:"tcb_info" json:"tcbInfo"`
	Signature string          `cbor:"signature" json:"signature"`
}

SignedTCBInfo is the signed TCB info structure.

type TCBBundle

type TCBBundle struct {
	TCBInfo      SignedTCBInfo    `json:"tcb_info"`
	QEIdentity   SignedQEIdentity `json:"qe_id"`
	Certificates []byte           `json:"certs"`
}

TCBBundle contains all the required components to verify a quote's TCB.

func (*TCBBundle) Verify added in v0.2300.0

func (bnd *TCBBundle) Verify(
	ts time.Time,
	policy *QuotePolicy,
	fmspc []byte,
	tcbCompSvn [16]int32,
	pcesvn uint16,
	qe *ReportBody,
) error

Verify verifies the TCB info and the QE identity corresponding to the passed SVN information.

type TCBComponent added in v0.2300.0

type TCBComponent struct {
	SVN      int32  `json:"svn"`
	Category string `json:"category,omitempty"`
	Type     string `json:"type,omitempty"`
}

TCBComponent is a TCB component.

type TCBInfo

type TCBInfo struct {
	ID                      string     `json:"id"`
	Version                 int        `json:"version"`
	IssueDate               string     `json:"issueDate"`
	NextUpdate              string     `json:"nextUpdate"`
	FMSPC                   string     `json:"fmspc"`
	PCEID                   string     `json:"pceId"`
	TCBType                 int        `json:"tcbType"`
	TCBEvaluationDataNumber uint32     `json:"tcbEvaluationDataNumber"`
	TDXModule               TDXModule  `json:"tdxModule,omitempty"`
	TCBLevels               []TCBLevel `json:"tcbLevels"`
}

TCBInfo is the TCB info body.

type TCBKind

type TCBKind uint8

TCBKind is the kind of the TCB.

func (TCBKind) String

func (tk TCBKind) String() string

String returns a string representation of the TCB kind.

type TCBLevel

type TCBLevel struct {
	TCB struct {
		PCESVN        uint16           `json:"pcesvn"`
		SGXComponents [16]TCBComponent `json:"sgxtcbcomponents"`
		TDXComponents [16]TCBComponent `json:"tdxtcbcomponents,omitempty"`
	} `json:"tcb"`
	Date        string    `json:"tcbDate"`
	Status      TCBStatus `json:"tcbStatus"`
	AdvisoryIDs []string  `json:"advisoryIDs,omitempty"`
}

TCBLevel is a platform TCB level.

type TCBOutOfDateError

type TCBOutOfDateError struct {
	Kind        TCBKind
	Status      TCBStatus
	AdvisoryIDs []string
}

TCBOutOfDateError is an error saying that the TCB of the platform or enclave is out of date.

func (*TCBOutOfDateError) Error

func (tle *TCBOutOfDateError) Error() string

Error returns the error message.

type TCBStatus

type TCBStatus int

TCBStatus is the TCB status.

const (
	StatusUpToDate TCBStatus
	StatusSWHardeningNeeded
	StatusConfigurationNeeded
	StatusConfigurationAndSWHardeningNeeded
	StatusOutOfDate
	StatusOutOfDateConfigurationNeeded
	StatusRevoked
)

func (*TCBStatus) MarshalText

func (s *TCBStatus) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface.

func (TCBStatus) String

func (s TCBStatus) String() string

String returns the string representation of the TCB status.

func (*TCBStatus) UnmarshalText

func (s *TCBStatus) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface.

type TDXModule added in v0.2300.0

type TDXModule struct {
	MRSIGNER       string  `json:"mrsigner"`
	Attributes     [8]byte `json:"attributes"`
	AttributesMask [8]byte `json:"attributesMask"`
}

TDXModule is a representation of the properties of Intel’s TDX SEAM module.

type UpdateType added in v0.2300.10

type UpdateType string

UpdateType is the type of update to TCB info.

const (
	// UpdateStandard indicates standard access to updated TCB Info provided as part of a TCB
	// recovery event.
	UpdateStandard UpdateType = "standard"
	// UpdateEarly indicates an early access to updated TCB Info provided as part of a TCB recovery
	// event.
	UpdateEarly UpdateType = "early"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL