enclave

Documentation

Overview

Package enclave provides functionality for Go enclaves like remote attestation and sealing.

Using remote reports

Remote reports are generated by an enclave platform to attest the integrity and confidentiality of an enclaved app instance. A remote report also attests that an app was indeed established on a secure enclave platform. It is targeted to a remote third party which is not running on an (or not on the same) enclave platform.

A remote report can contain 64 bytes of additional data, e.g., data that was created by the enclaved application or data the enclaved app received. This data (or its hash) can be included as reportData.

GetRemoteReport creates a remote report which includes additional reportData. The following code can be run by an enclaved app:

// Create a report that includes the hash of an enclave generated certificate cert.
hash := sha256.Sum256(cert)
report, err := enclave.GetRemoteReport(hash[:])
if err != nil {
	return err
}

VerifyRemoteReport can be used by a third party to verify the previously generated remote report. While VerifyRemoteReport verifies the report's integrity and signature, the third party must additionally verify the content of the remote report:

report, err := enclave.VerifyRemoteReport(report)
if err != nil {
	return err
}
if report.SecurityVersion < 2 {
	return errors.New("invalid security version")
}
if binary.LittleEndian.Uint16(report.ProductID) != 1234 {
	return errors.New("invalid product")
}
if !bytes.Equal(report.SignerID, signer) {
	return errors.New("invalid signer")
}
if report.Debug {
	return errors.New("debug enclave not allowed")
}

// certBytes and report were sent over insecure channel
hash := sha256.Sum256(certBytes)
if !bytes.Equal(report.Data[:len(hash)], hash[:]) {
	return errors.New("report data does not match the certificate's hash")
}
// we ensured the cert was generated by the enclave

Index

• func CreateAttestationCertificate(template, parent *x509.Certificate, pub, priv interface{}) ([]byte, error)
• func CreateAttestationClientTLSConfig(verifyReport func(attestation.Report) error, opts ...AttestOption) *tls.Config
• func CreateAttestationServerTLSConfig() (*tls.Config, error)
• func CreateAzureAttestationToken(data []byte, url string) (string, error)
• func GetLocalReport(reportData []byte, targetReport []byte) ([]byte, error)
• func GetProductSealKey() (key, keyInfo []byte, err error)
• func GetRemoteReport(reportData []byte) ([]byte, error)
• func GetSealKey(keyInfo []byte) ([]byte, error)
• func GetSealKeyID() ([]byte, error)
• func GetSelfReport() (attestation.Report, error)
• func GetUniqueSealKey() (key, keyInfo []byte, err error)
• func VerifyLocalReport(reportBytes []byte) (attestation.Report, error)
• func VerifyRemoteReport(reportBytes []byte) (attestation.Report, error)
• type AttestOption
  • func WithIgnoreTCBStatus() AttestOption

Examples

• CreateAttestationServerTLSConfig

Functions

func CreateAttestationCertificate

func CreateAttestationCertificate(template, parent *x509.Certificate, pub, priv interface{}) ([]byte, error)

CreateAttestationCertificate creates an X.509 certificate with an embedded report from the underlying enclave.

func CreateAttestationClientTLSConfig

func CreateAttestationClientTLSConfig(verifyReport func(attestation.Report) error, opts ...AttestOption) *tls.Config

CreateAttestationClientTLSConfig creates a tls.Config object that verifies a certificate with embedded report.

verifyReport is called after the certificate has been verified against the report data. The caller must verify either the UniqueID or the tuple (SignerID, ProductID, SecurityVersion, Debug) in the callback.

func CreateAttestationServerTLSConfig

func CreateAttestationServerTLSConfig() (*tls.Config, error)

CreateAttestationServerTLSConfig creates a tls.Config object with a self-signed certificate and an embedded report.

Example

// Create a TLS config with a self-signed certificate and an embedded report.
tlsConfig, err := CreateAttestationServerTLSConfig()
if err != nil {
	log.Fatal(err)
}

// Create HTTPS server.
http.HandleFunc("/test", func(w http.ResponseWriter, r *http.Request) {
	_, _ = w.Write([]byte("this is a test handler"))
})
server := http.Server{Addr: "0.0.0.0:8080", TLSConfig: tlsConfig}
log.Fatal(server.ListenAndServeTLS("", ""))

func CreateAzureAttestationToken

func CreateAzureAttestationToken(data []byte, url string) (string, error)

CreateAzureAttestationToken creates a Microsoft Azure Attestation token by creating a remote report and sending it to an Attestation Provider, who is reachable under url. A JSON Web Token in compact serialization is returned.

func GetLocalReport

func GetLocalReport(reportData []byte, targetReport []byte) ([]byte, error)

GetLocalReport gets a report signed by the enclave platform for use in local attestation.

The report shall contain the data given by the reportData parameter. The report can only hold a maximum of 64 byte reportData. Use a hash value of your data as reportData if your data exceeds this limit.

If reportData is less than 64 bytes, it will be padded with zero bytes.

The report can only be verified by the enclave identified by targetReport. So you must first get a report from the target enclave. This report is allowed to be empty, i.e., obtained by `GetLocalReport(nil, nil)`.

func GetProductSealKey

func GetProductSealKey() (key, keyInfo []byte, err error)

GetProductSealKey gets a key derived from the signer and product id of the enclave.

keyInfo can be used to retrieve the same key later, on a newer CPU security version.

func GetRemoteReport

func GetRemoteReport(reportData []byte) ([]byte, error)

GetRemoteReport gets a report signed by the enclave platform for use in remote attestation.

The report shall contain the data given by the reportData parameter. The report can only hold a maximum of 64 byte reportData. Use a hash value of your data as reportData if your data exceeds this limit.

If reportData is less than 64 bytes, it will be padded with zero bytes.

func GetSealKey

func GetSealKey(keyInfo []byte) ([]byte, error)

GetSealKey gets a key from the enclave platform using existing key information.

func GetSealKeyID

func GetSealKeyID() ([]byte, error)

GetSealKeyID gets a unique ID derived from the CPU's root seal key. The ID also depends on the ProductID and Debug flag of the enclave.

func GetSelfReport

func GetSelfReport() (attestation.Report, error)

GetSelfReport returns a report of this enclave. The report can't be used for attestation, but to get values like the SignerID of this enclave.

func GetUniqueSealKey

func GetUniqueSealKey() (key, keyInfo []byte, err error)

GetUniqueSealKey gets a key derived from a measurement of the enclave.

keyInfo can be used to retrieve the same key later, on a newer CPU security version.

This key will change if the UniqueID of the enclave changes. If you want the key to be the same across enclave versions, use GetProductSealKey.

func VerifyLocalReport

func VerifyLocalReport(reportBytes []byte) (attestation.Report, error)

VerifyLocalReport verifies the integrity of the local report and its signature.

This function verifies that the report signature is valid. It verifies that it is correctly signed by the enclave platform.

The caller must verify the returned report's content.

func VerifyRemoteReport

func VerifyRemoteReport(reportBytes []byte) (attestation.Report, error)

VerifyRemoteReport verifies the integrity of the remote report and its signature.

This function verifies that the report signature is valid. It verifies that the signing authority is rooted to a trusted authority such as the enclave platform manufacturer.

The caller must verify the returned report's content.

Types

type AttestOption

type AttestOption struct {
	// contains filtered or unexported fields
}

AttestOption configures an attestation function.

func WithIgnoreTCBStatus

func WithIgnoreTCBStatus() AttestOption

WithIgnoreTCBStatus ignores an invalid TCB level.

Callers must verify the TCBStatus field in the report themselves.