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 CreateAttestationServerTLSConfig() (*tls.Config, error)
• func CreateAzureAttestationToken(data []byte, url string) (string, error)
• func GetProductSealKey() (key, keyInfo []byte, err error)
• func GetRemoteReport(reportData []byte) ([]byte, error)
• func GetSealKey(keyInfo []byte) ([]byte, error)
• func GetUniqueSealKey() (key, keyInfo []byte, err error)
• func VerifyRemoteReport(reportBytes []byte) (attestation.Report, error)

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 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 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 64 byte hash value of your data as reportData if your data exceeds this limit.

func GetSealKey

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

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

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 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.