Repository files navigation

Go-Attestation abstracts remote attestation operations across a variety of platformsand TPMs, enabling remote validation of machine identity and state. This projectattempts to provide high level primitives for both client and server logic.

Talks on this project:

• "Making Device Identity Trustworthy" - Open Source Summit Europe - October 2019 - (Slides)
• "Using TPMs to Cryptographically Verify Devices at Scale" - Open Source Summit North America - September 2019 - (Video 39min)
• "Making Remote Attestation Useful on Linux" - Linux Security Summit - September 2019 - (Video 26min)

Go-Attestation is has reached initial maturity. It supports the initial designgoals and is actively used at Google. It is still under development, and APIchanges may occur at any time. One caveat is that support for Windows is stillrelatively immature compared to support for Linux.

Please note that this is not an official Google product.

TPM 1.2 support is best effort, meaning we will accept fixes for TPM 1.2, buttesting is not covered by CI.

The go-attestation package is installable using go get:go get github.com/google/go-attestation/attest

TPMs can be used to identify a device remotely and provision unique per-devicehardware-bound keys.

TPMs are provisioned with a set of Endorsement Keys (EKs) by the manufacturer.These optionally include a certificate signed by the manufacturer and act as aTPM's identity. For privacy reasons the EK can't be used to sign or encrypt datadirectly, and is instead used to attest to the presence of a signing key, anAttestation Key (AK), on the same TPM. (Newer versions of the spec may allow theEK to sign directly.)

During attestation, a TPM generates an AK and proves to a certificate authoritythat the AK is on the same TPM as a EK. If the certificate authority trusts theEK, it can transitively trust the AK, for example by issuing a certificate forthe AK.

To perform attestation, the client generates an AK and sends the EK and AKparameters to the server:

// Client generates an AK and sends it to the serverconfig:=&attest.OpenConfig{}tpm,err:=attest.OpenTPM(config)iferr!=nil {// handle error}eks,err:=tpm.EKs()iferr!=nil {// handle error}ek:=eks[0]akConfig:=&attest.AKConfig{}ak,err:=tpm.NewAK(akConfig)iferr!=nil {// handle error}attestParams:=ak.AttestationParameters()akBytes,err:=ak.Marshal()iferr!=nil {// handle error}iferr:=os.WriteFile("encrypted_aik.json",akBytes,0600);err!=nil {// handle error}// send TPM version, EK, and attestParams to the server

The server uses the EK and AK parameters to generate a challenge encrypted tothe EK, returning the challenge to the client. During this phase, the serverdetermines if it trusts the EK, either by chaining its certificate to a knownmanufacturer and/or querying an inventory system.

// Server validates EK and/or EK certificateparams:= attest.ActivationParameters{TPMVersion:tpmVersion,EK:ek.Public,AK:attestParams,}secret,encryptedCredentials,err:=params.Generate()iferr!=nil {// handle error}// return encrypted credentials to client

The client proves possession of the AK by decrypting the challenge andreturning the same secret to the server.

// Client decrypts the credentialakBytes,err:=os.ReadFile("encrypted_aik.json")iferr!=nil {// handle error}ak,err:=tpm.LoadAK(akBytes)iferr!=nil {// handle error}secret,err:=ak.ActivateCredential(tpm,encryptedCredentials)iferr!=nil {// handle error}// return secret to server

At this point, the server records the AK and EK association and allows the clientto use its AK as a credential (e.g. by issuing it a client certificate).