attest

package
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Dec 4, 2019 License: Apache-2.0 Imports: 29 Imported by: 44

Documentation

Overview

Package attest abstracts TPM attestation operations.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	HashSHA1   = HashAlg(tpm2.AlgSHA1)
	HashSHA256 = HashAlg(tpm2.AlgSHA256)
)

Valid hash algorithms.

View Source 
var (

	// ErrTPMNotAvailable is returned in response to OpenTPM() when
	// either no TPM is available, or a TPM of the requested version
	// is not available (if TPMVersion was set in the provided config).
	ErrTPMNotAvailable = errors.New("TPM device not available")
	// ErrTPM12NotImplemented is returned in response to methods which
	// need to interact with the TPM1.2 device in ways that have not
	// yet been implemented.
	ErrTPM12NotImplemented = errors.New("TPM 1.2 support not yet implemented")
)

Functions

func ParseEKCertificate 

func ParseEKCertificate(ekCert []byte) (*x509.Certificate, error)

ParseEKCertificate parses a raw DER encoded EK certificate blob.

Types

type AK added in v0.1.2 

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

AK represents a key which can be used for attestation.

Example 
package main

import (
	"log"

	"github.com/google/go-attestation/attest"
)

func main() {
	tpm, err := attest.OpenTPM(nil)
	if err != nil {
		log.Fatalf("Failed to open the TPM: %v", err)
	}
	defer tpm.Close()

	// Create a new AK.
	ak, err := tpm.NewAK(nil)
	if err != nil {
		log.Fatalf("Failed to create AK: %v", err)
	}
	// Save a re-loadable representation to blob.
	blob, err := ak.Marshal()
	if err != nil {
		log.Fatalf("Failed to marshal AK: %v", err)
	}
	// Close our handle to the AK.
	if err := ak.Close(tpm); err != nil {
		log.Fatalf("Failed to close AK: %v", err)
	}

	// Re-load the created AK from the blob.
	ak, err = tpm.LoadAK(blob)
	if err != nil {
		log.Fatalf("Failed to load AK: %v", err)
	}
	if err := ak.Close(tpm); err != nil {
		log.Fatalf("Failed to close AK: %v", err)
	}
}

Output:
Example (CredentialActivation) 
package main

import (
	"crypto/subtle"
	"log"

	"github.com/google/go-attestation/attest"
)

func main() {
	tpm, err := attest.OpenTPM(nil)
	if err != nil {
		log.Fatalf("Failed to open TPM: %v", err)
	}
	defer tpm.Close()

	// Create a new AK.
	ak, err := tpm.NewAK(nil)
	if err != nil {
		log.Fatalf("Failed to create AK: %v", err)
	}
	defer ak.Close(tpm)

	// Read the EK.
	ek, err := tpm.EKs()
	if err != nil {
		log.Fatalf("Failed to enumerate EKs: %v", err)
	}

	// Read parameters necessary to generate a challenge.
	ap := ak.AttestationParameters()

	// Generate a credential activation challenge (usually done on the server).
	activation := attest.ActivationParameters{
		TPMVersion: tpm.Version(),
		EK:         ek[0].Public,
		AK:         ap,
	}
	secret, challenge, err := activation.Generate()
	if err != nil {
		log.Fatalf("Failed to generate activation challenge: %v", err)
	}

	// Challenge the AK & EK properties to recieve the decrypted secret.
	decrypted, err := ak.ActivateCredential(tpm, *challenge)
	if err != nil {
		log.Fatalf("Failed to activate credential: %v", err)
	}

	// Check that the AK completed the challenge (usually done on the server).
	if subtle.ConstantTimeCompare(secret, decrypted) == 0 {
		log.Fatal("Activation response did not match secret")
	}
}

Output:

func (*AK) ActivateCredential added in v0.1.2 

func (k *AK) ActivateCredential(tpm *TPM, in EncryptedCredential) (secret []byte, err error)

ActivateCredential decrypts the secret using the key to prove that the AK was generated on the same TPM as the EK.

This operation is synonymous with TPM2_ActivateCredential.

func (*AK) AttestationParameters added in v0.1.2 

func (k *AK) AttestationParameters() AttestationParameters

AttestationParameters returns information about the AK, typically used to generate a credential activation challenge.

func (*AK) Close added in v0.1.2 

func (k *AK) Close(t *TPM) error

Close unloads the AK from the system.

func (*AK) Marshal added in v0.1.2 

func (k *AK) Marshal() ([]byte, error)

Marshal encodes the AK in a format that can be reloaded with tpm.LoadAK(). This method exists to allow consumers to store the key persistently and load it as a later time. Users SHOULD NOT attempt to interpret or extract values from this blob.

func (*AK) Quote added in v0.1.2 

func (k *AK) Quote(tpm *TPM, nonce []byte, alg HashAlg) (*Quote, error)

Quote returns a quote over the platform state, signed by the AK.

This is a low-level API. Consumers seeking to attest the state of the platform should use tpm.AttestPlatform() instead.

type AKConfig added in v0.1.2 

type AKConfig struct {
}

AKConfig encapsulates parameters for minting keys. This type is defined now (despite being empty) for future interface compatibility.

type AKPublic added in v0.1.2 

type AKPublic struct {
	// Public is the public part of the AK. This can either be an *rsa.PublicKey or
	// and *ecdsa.PublicKey.
	Public crypto.PublicKey
	// Hash is the hashing algorithm the AK will use when signing quotes.
	Hash crypto.Hash
}

AKPublic holds structured information about an AK's public key.

func ParseAKPublic added in v0.1.2 

func ParseAKPublic(version TPMVersion, public []byte) (*AKPublic, error)

ParseAKPublic parses the Public blob from the AttestationParameters, returning the public key and signing parameters for the key.

func (*AKPublic) Verify added in v0.1.2 

func (a *AKPublic) Verify(quote Quote, pcrs []PCR, nonce []byte) error

Verify is used to prove authenticity of the PCR measurements. It ensures that the quote was signed by the AK, and that its contents matches the PCR and nonce combination.

The nonce is used to prevent replays of Quote and PCRs and is signed by the quote. Some TPMs don't support nonces longer than 20 bytes, and if the nonce is used to tie additional data to the quote, the additional data should be hashed to construct the nonce.

type ActivationParameters 

type ActivationParameters struct {
	// TPMVersion holds the version of the TPM, either 1.2 or 2.0.
	TPMVersion TPMVersion

	// EK, the endorsement key, describes an asymmetric key who's
	// private key is permenantly bound to the TPM.
	//
	// Activation will verify that the provided EK is held on the same
	// TPM as the AK. However, it is the callers responsibility to
	// ensure the EK they provide corresponds to the the device which
	// they are trying to associate the AK with.
	EK crypto.PublicKey

	// AK, the Attestation Key, describes the properties of
	// an asymmetric key (managed by the TPM) which signs attestation
	// structures.
	// The values from this structure can be obtained by calling
	// Parameters() on an attest.AK.
	AK AttestationParameters

	// Rand is a source of randomness to generate a seed and secret for the
	// challenge.
	//
	// If nil, this defaults to crypto.Rand.
	Rand io.Reader
}

ActivationParameters encapsulates the inputs for activating an AK.

func (*ActivationParameters) Generate 

func (p *ActivationParameters) Generate() (secret []byte, ec *EncryptedCredential, err error)

Generate returns a credential activation challenge, which can be provided to the TPM to verify the AK parameters given are authentic & the AK is present on the same TPM as the EK.

The caller is expected to verify the secret returned from the TPM as as result of calling ActivateCredential() matches the secret returned here. The caller should use subtle.ConstantTimeCompare to avoid potential timing attack vectors.

type AttestationParameters 

type AttestationParameters struct {
	// Public represents the AK's canonical encoding. This blob includes the
	// public key, as well as signing parameters such as the hash algorithm
	// used to generate quotes.
	//
	// Use ParseAKPublic to access the key's data.
	Public []byte

	// UseTCSDActivationFormat is set when tcsd (trousers daemon) is operating
	// as an intermediary between this library and the TPM. A value of true
	// indicates that activation challenges should use the TCSD-specific format.
	UseTCSDActivationFormat bool

	// CreateData represents the properties of a TPM 2.0 key. It is encoded
	// as a TPMS_CREATION_DATA structure.
	CreateData []byte
	// CreateAttestation represents an assertion as to the details of the key.
	// It is encoded as a TPMS_ATTEST structure.
	CreateAttestation []byte
	// CreateSignature represents a signature of the CreateAttestation structure.
	// It is encoded as a TPMT_SIGNATURE structure.
	CreateSignature []byte
}

AttestationParameters describes information about a key which is necessary for verifying its properties remotely.

type EK 

type EK struct {
	// Public key of the EK.
	Public crypto.PublicKey

	// Certificate is the EK certificate for TPMs that provide it.
	Certificate *x509.Certificate

	// For Intel TPMs, Intel hosts certificates at a public URL derived from the
	// Public key. Clients or servers can perform an HTTP GET to this URL, and
	// use ParseEKCertificate on the response body.
	CertificateURL string
}

EK is a burned-in endorcement key bound to a TPM. This optionally contains a certificate that can chain to the TPM manufacturer.

type EncryptedCredential 

type EncryptedCredential struct {
	Credential []byte
	Secret     []byte
}

EncryptedCredential represents encrypted parameters which must be activated against a key.

type Event 

type Event struct {

	// PCR index of the event.
	Index int
	// Type of the event.
	Type EventType

	// Data of the event. For certain kinds of events, this must match the event
	// digest to be valid.
	Data []byte
	// Digest is the verified digest of the event data. While an event can have
	// multiple for different hash values, this is the one that was matched to the
	// PCR value.
	Digest []byte
	// contains filtered or unexported fields
}

Event is a single event from a TCG event log. This reports descrete items such as BIOs measurements or EFI states.

type EventLog 

type EventLog struct {
	// Algs holds the set of algorithms that the event log uses.
	Algs []HashAlg
	// contains filtered or unexported fields
}

EventLog is a parsed measurement log. This contains unverified data representing boot events that must be replayed against PCR values to determine authenticity.

func ParseEventLog 

func ParseEventLog(measurementLog []byte) (*EventLog, error)

ParseEventLog parses an unverified measurement log.

func (*EventLog) Verify 

func (e *EventLog) Verify(pcrs []PCR) ([]Event, error)

Verify replays the event log against a TPM's PCR values, returning the events which could be matched to a provided PCR value. An error is returned if the replayed digest for events with a given PCR index do not match any provided value for that PCR index.

type EventType 

type EventType uint32

EventType indicates what kind of data an event is reporting.

type HashAlg 

type HashAlg uint8

HashAlg identifies a hashing Algorithm.

func (HashAlg) String added in v0.1.2 

func (a HashAlg) String() string

String returns a human-friendly representation of the hash algorithm.

type OpenConfig 

type OpenConfig struct {
	// TPMVersion indicates which TPM version the library should
	// attempt to use. If the specified version is not available,
	// ErrTPMNotAvailable is returned. Defaults to TPMVersionAgnostic.
	TPMVersion TPMVersion
}

OpenConfig encapsulates settings passed to OpenTPM().

type PCR 

type PCR struct {
	Index     int
	Digest    []byte
	DigestAlg crypto.Hash
}

PCR encapsulates the value of a PCR at a point in time.

type PlatformAttestConfig added in v0.1.2 

type PlatformAttestConfig struct {
	// If non-nil, the raw event log will be read from EventLog
	// instead of being obtained from the running system.
	EventLog []byte
}

PlatformAttestConfig configures how attestations are generated through tpm.AttestPlatform().

type PlatformParameters added in v0.1.2 

type PlatformParameters struct {
	// The version of the TPM which generated this attestation.
	TPMVersion TPMVersion
	// The public blob of the AK which endorsed the platform state. This can
	// be decoded to verify the adjacent quotes using ParseAKPublic().
	Public []byte
	// The set of quotes which endorse the state of the PCRs.
	Quotes []Quote
	// The set of expected PCR values, which are used in replaying the event log
	// to verify digests were not tampered with.
	PCRs []PCR
	// The raw event log provided by the platform. This can be processed with
	// ParseEventLog().
	EventLog []byte
}

PlatformParameters encapsulates the set of information necessary to attest the booted state of the machine the TPM is attached to.

The digests contained in the event log can be considered authentic if:

  • The AK public corresponds to the known AK for that platform.
  • All quotes are verified with AKPublic.Verify(), and return no errors.
  • The event log parsed successfully using ParseEventLog(), and a call to EventLog.Verify() with the full set of PCRs returned no error.

type Quote 

type Quote struct {
	Version   TPMVersion
	Quote     []byte
	Signature []byte
}

Quote encapsulates the results of a Quote operation against the TPM, using an attestation key.

type ReplayError added in v0.1.2 

type ReplayError struct {
	Events []Event
	// contains filtered or unexported fields
}

ReplayError describes the parsed events that failed to verify against a particular PCR.

func (ReplayError) Error added in v0.1.2 

func (e ReplayError) Error() string

Error returns a human-friendly description of replay failures.

type TCGVendorID 

type TCGVendorID uint32

TCGVendorID represents a unique TCG manufacturer code. The canonical reference used is located at: https://trustedcomputinggroup.org/wp-content/uploads/TCG-TPM-Vendor-ID-Registry-Version-1.01-Revision-1.00.pdf

func (TCGVendorID) String 

func (id TCGVendorID) String() string

type TPM added in v0.1.2 

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

TPM interfaces with a TPM device on the system.

func OpenTPM added in v0.1.2 

func OpenTPM(config *OpenConfig) (*TPM, error)

OpenTPM initializes access to the TPM based on the config provided.

func (*TPM) AttestPlatform added in v0.1.2 

func (t *TPM) AttestPlatform(ak *AK, nonce []byte, config *PlatformAttestConfig) (*PlatformParameters, error)

AttestPlatform computes the set of information necessary to attest the state of the platform. For TPM 2.0 devices, AttestPlatform will attempt to read both SHA1 & SHA256 PCR banks and quote both of them, so bugs in platform firmware which break replay for one PCR bank can be mitigated using the other. The provided config, if not nil, can be used to configure aspects of the platform attestation.

Example 
package main

import (
	"log"

	"github.com/google/go-attestation/attest"
)

func main() {
	tpm, err := attest.OpenTPM(nil)
	if err != nil {
		log.Fatalf("Failed to open TPM: %v", err)
	}
	defer tpm.Close()

	// Create a new AK.
	ak, err := tpm.NewAK(nil)
	if err != nil {
		log.Fatalf("Failed to create AK: %v", err)
	}
	defer ak.Close(tpm)

	// The nonce would typically be provided by the server.
	nonce := []byte{1, 2, 3, 4, 5, 6, 7, 8}

	// Perform an attestation against the state of the plaform. Usually, you
	// would pass a nil config, and the event log would be read from the
	// platform. To ensure this example runs on platforms without event logs,
	// we pass a fake EventLog value.
	att, err := tpm.AttestPlatform(ak, nonce, &attest.PlatformAttestConfig{
		EventLog: []byte{0},
	})
	if err != nil {
		log.Fatalf("Failed to attest the platform state: %v", err)
	}

	// Construct an AKPublic struct from the parameters of the key. This
	// will be used to  verify the quote signatures.
	pub, err := attest.ParseAKPublic(tpm.Version(), ak.AttestationParameters().Public)
	if err != nil {
		log.Fatalf("Failed to parse AK public: %v", err)
	}

	for i, q := range att.Quotes {
		if err := pub.Verify(q, att.PCRs, nonce); err != nil {
			log.Fatalf("quote[%d] verification failed: %v", i, err)
		}
	}
}

Output:

func (*TPM) Close added in v0.1.2 

func (t *TPM) Close() error

Close shuts down the connection to the TPM.

func (*TPM) EKs added in v0.1.2 

func (t *TPM) EKs() ([]EK, error)

EKs returns the endorsement keys burned-in to the platform.

func (*TPM) Info added in v0.1.2 

func (t *TPM) Info() (*TPMInfo, error)

Info returns information about the TPM.

func (*TPM) LoadAK added in v0.1.2 

func (t *TPM) LoadAK(opaqueBlob []byte) (*AK, error)

LoadAK loads a previously-created ak into the TPM for use. A key loaded via this function needs to be closed with .Close(). Only blobs generated by calling AK.Serialize() are valid parameters to this function.

func (*TPM) MeasurementLog added in v0.1.2 

func (t *TPM) MeasurementLog() ([]byte, error)

MeasurementLog returns the present value of the System Measurement Log.

This is a low-level API. Consumers seeking to attest the state of the platform should use tpm.AttestPlatform() instead.

func (*TPM) NewAK added in v0.1.2 

func (t *TPM) NewAK(opts *AKConfig) (*AK, error)

NewAK creates an attestation key.

func (*TPM) PCRs added in v0.1.2 

func (t *TPM) PCRs(alg HashAlg) ([]PCR, error)

PCRs returns the present value of Platform Configuration Registers with the given digest algorithm.

This is a low-level API. Consumers seeking to attest the state of the platform should use tpm.AttestPlatform() instead.

func (*TPM) Version added in v0.1.2 

func (t *TPM) Version() TPMVersion

Version returns the version of the TPM.

type TPMInfo 

type TPMInfo struct {
	Version      TPMVersion
	Interface    TPMInterface
	VendorInfo   string
	Manufacturer TCGVendorID

	// FirmwareVersionMajor and FirmwareVersionMinor describe
	// the firmware version of the TPM, but are only available
	// for TPM 2.0 devices.
	FirmwareVersionMajor int
	FirmwareVersionMinor int
}

TPMInfo contains information about the version & interface of an open TPM.

func AvailableTPMs 

func AvailableTPMs(config *OpenConfig) ([]TPMInfo, error)

AvailableTPMs returns information about available TPMs matching the given config, without opening the devices.

type TPMInterface 

type TPMInterface uint8

TPMInterface indicates how the client communicates with the TPM. 

const (
	TPMInterfaceDirect TPMInterface = iota
	TPMInterfaceKernelManaged
	TPMInterfaceDaemonManaged
)

TPM interfaces

type TPMVersion 

type TPMVersion uint8

TPMVersion is used to configure a preference in which TPM to use, if multiple are available. 

const (
	TPMVersionAgnostic TPMVersion = iota
	TPMVersion12
	TPMVersion20
)

TPM versions

Source Files

View all Source files

Directories

Path Synopsis
Binary attest-tool performs attestation operations on the local system.
 Binary attest-tool performs attestation operations on the local system.
internal
Package internal contains marshalling structures for attest-tool and tests.
 Package internal contains marshalling structures for attest-tool and tests.
internal/eventlog
Package eventlog implements experimental logic for parsing the TCG event log format.
 Package eventlog implements experimental logic for parsing the TCG event log format.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.