tpm

package
v1.10.0 Latest Latest
Warning

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

 Go to latest Published: Jun 23, 2025 License: BSD-3-Clause Imports: 26 Imported by: 1

README

Intel® Trust Authority TPM Adapter for Go

· 10/23/2024 ·

This version of the TPM (Trusted Platform Module) adapter provides a set of APIs for interacting with TPMs. The adapter can be used to read and write NV indexes, read PCRs, and get quotes. In this release the adapter supports Microsoft Azure* confidential virtual machines with Intel® Trust Domain Extensions (Intel® TDX) and vTPM 2.0.

The TPM adapter is used to get evidence from the vTPM. The evidence is endorsed by the Azure-provided attestation key (AK), which is contained in the Intel TDX quote's runtime data. The Azure CVM with Intel TDX adapter (go-aztdx) is used to get evidence from the Intel TDX trust domain TEE. The evidence from the vTPM and the Intel TDX is combined and sent to Intel Trust Authority for composite attestation. If attestation is successful, Intel Trust Authority issues a JWT (JSON Web Token) that can be used to verify the integrity of the vTPM and the Intel TDX trust domain.

For detailed documentation of the TPM adapter, see the TPM API Reference in the Intel Trust Authority documentation.

Prerequisites

  • Go 1.23 or newer

Usage

You'll need to import the following packages into your project to attest an Azure confidential VM with Intel TDX and vTPM:

import(
	"github.com/intel/trustauthority-client/aztdx"
	"github.com/intel/trustauthority-client/go-connector"
	"github.com/intel/trustauthority-client/tpm"
)

Code of Conduct and Contributing

See the CONTRIBUTING file for information on how to contribute to this project. The project follows the Code of Conduct.

License

This library is distributed under the BSD-style license found in the LICENSE file.



* Other names and brands may be claimed as the property of others.

Documentation

Overview

The go-tpm package provides an application level interface to an underlying TPM or vTPM device. It is not intended to be a comprehesive TPM 2.0 interface and provides a higher level abstraction needed by the Trust Authority client.

It exposes a number of TPM functions for getting quotes, reading public keys, and reading/writing NV ram. These are primarily used by the trustauthority-cli. It also provides an implementation of the connector.CompositeEvidenceAdapter interface which is also used by the trustauthority-cli.

Index

Constants

View Source 
const (
	DefaultEkNvIndex = 0x01c00002
	DefaultEkHandle  = 0x81000800
	DefaultAkHandle  = 0x81000801

	DefaultImaPath          = "/sys/kernel/security/ima/ascii_runtime_measurements"
	DefaultUefiEventLogPath = "/sys/kernel/security/tpm0/binary_bios_measurements"
)

Variables

View Source 
var (
	ErrHandleOutOfRange      = errors.New("handle out of range")
	ErrInvalidHandle         = errors.New("invalid handle")
	ErrExistingHandle        = errors.New("the handle already exists")
	ErrHandleDoesNotExist    = errors.New("the handle does not exist")
	ErrHandleError           = errors.New("failed to access handle")
	ErrorNvIndexDoesNotExist = errors.New("nv index does not exist")
	ErrNvReleaseFailed       = errors.New("failed to release/delete nv index")
	ErrNvDefineSpaceFailed   = errors.New("failed to define/create nv index")
	ErrNvWriteFailed         = errors.New("failed to write data to nv ram")
	ErrNvInvalidSize         = errors.New("invalid data size for nv ram")
	ErrSymlinksNotAllowed    = errors.New("symlinks are not allowed")
	ErrPathTraversal         = errors.New("path traversal detected")
	ErrQuoteFailure          = errors.New("failed to get quote")
	ErrTpmOpenFailure        = errors.New("failed to create tpm device")
	ErrPCRsFailure           = errors.New("failed to read pcrs")
	ErrFailedToReadIMALogs   = errors.New("failed to read ima log")
	ErrFailedToReadUEFILogs  = errors.New("failed to read uefi log")
	ErrReadAkFileFailure     = errors.New("failed to read ak certificate from file")
	ErrReadAkNvramInvalidHex = errors.New("invalid ak hex value")
	ErrReadAkNvramFailure    = errors.New("failed to read ak certificate from nvram")
	ErrIssuerCAHttpError     = errors.New("failed download issuer CA certificate")
	ErrIssuerCAStatusError   = errors.New("failed download issuer CA certificate")
	ErrInvalidCertificate    = errors.New("invalid certificate")
	ErrInvalidPemType        = errors.New("invalid pem type, expected CERTIFICATE")
)

Functions

func AesDecrypt added in v1.8.0 

func AesDecrypt(cipherText, key []byte) ([]byte, error)

AesDecrypt uses GCM to decrypt the cipherText using the key. The caller is responsible for zeroing out the key after use.

Types

type GetFunc added in v1.10.0 

type GetFunc func(url string) (*http.Response, error)

type PcrSelection 

type PcrSelection struct {
	Hash crypto.Hash
	Pcrs []int
}

PcrSelection is a struct that contains the hash algorithm and the list of PCRs that will be included in quotes/pcr data.

type TpmAdapterFactory added in v1.9.0 

type TpmAdapterFactory interface {
	New(opts ...TpmAdapterOptions) (connector.CompositeEvidenceAdapter, error)
}

func NewTpmAdapterFactory added in v1.9.0 

func NewTpmAdapterFactory(tpmFactory TpmFactory) TpmAdapterFactory

type TpmAdapterOptions 

type TpmAdapterOptions func(*tpmAdapter) error

TpmAdapterOptions for creating an evidence adapter using the host's TPM.

func WithAkCertificateUri added in v1.8.0 

func WithAkCertificateUri(uriString string) TpmAdapterOptions

WithAkCertificateUri specifies the full path to an AK certificate file in PEM format that will be used by ITA to verify the TPM quotes.

func WithAkHandle 

func WithAkHandle(akHandle int) TpmAdapterOptions

WithAkHandle specifies the ak handle to use during quote generation. By default, it uses

func WithDeviceType 

func WithDeviceType(deviceType TpmDeviceType) TpmAdapterOptions

WithDeviceType specifies the type of TPM device to use. By default, the Linux device is used (/dev/tpmrm0).

func WithImaLogs 

func WithImaLogs(enabled bool) TpmAdapterOptions

WithImaLogs controls the inclusion of IMA logs into TPM evidence. When enabled, logs from "/sys/kernel/security/ima/ascii_runtime_measurements" will be included in evidence.

func WithOwnerAuth 

func WithOwnerAuth(ownerAuth string) TpmAdapterOptions

WithOwnerAuth specifies the owner password used to communicate with the TPM. By default, the empty string is used.

func WithPcrSelections 

func WithPcrSelections(selections string) TpmAdapterOptions

WithPcrSelections configures which PCRs to include during TPM quote generation.

func WithUefiEventLogs 

func WithUefiEventLogs(enabled bool) TpmAdapterOptions

WithUefiEventLogs controls the inclusion of UEFI event logs into TPM evidence. When enabled, logs from "/sys/kernel/security/tpm0/binary_bios_measurements" will be included in evidence.

type TpmDeviceType 

type TpmDeviceType int
const (
	TpmDeviceUnknown TpmDeviceType = iota
	TpmDeviceLinux
	TpmDeviceMSSIM
)

func ParseTpmDeviceType 

func ParseTpmDeviceType(s string) (TpmDeviceType, error)

func (TpmDeviceType) String 

func (t TpmDeviceType) String() string

type TpmFactory 

type TpmFactory interface {
	New(deviceType TpmDeviceType, ownerAuth string) (TrustedPlatformModule, error)
}

TpmFactory is an interface for creating TrustedPlatformModule instances.

func NewTpmFactory 

func NewTpmFactory() TpmFactory

Default TPM factory that creates a TrustedPlatformModule implementation suitable for use with a physical/linux device or TPM simulator.

type TrustedPlatformModule 

type TrustedPlatformModule interface {
	// CreateEK persists a new Endorsement Key in the endorsement hierarchy at the specified
	// handle. It fails if the handle is not within range of persistent handles or, if the
	// handle already exists (it should be deleted using tpm2-evictcontrol -c {handle}).
	//
	// The EK is used to perform decryption when interacting ITA during AK provisioning.
	CreateEK(ekHandle int) error

	// CreateAK persists an AK in the owner hierarchy at the specified handle ('akHandle').
	// It requires the handle of the EK ('ekHandle').  It fails if akHandle is not within
	// the range of a persistent handle, if 'akHandle' already exists, or if the EK at
	// 'ekHandle' does not exist.
	//
	// The AK is used to sign quotes during remote attestation and is rooted through the
	// EK to the endorsement hierachy (root of trust).
	CreateAK(akHandle int, ekHandle int) error

	// CreateAkFromTemplate creates and persists an AK handle at 'akHandle'.  It uses the
	// template bytes (TPMT_PUBLIC) to create the AK.  It fails if akHandle is not within
	// the range of a persistent handle, if 'akHandle' already exists, or if the template
	// bytes cannot be unmarshalled.
	CreateAkFromTemplate(akHandle int, akTemplate []byte) error

	// ActivateCredential decrypts a credential blob using the secret and the AK at 'akHandle'.
	ActivateCredential(ekHandle int, akHandle int, credentialBlob []byte, secret []byte) ([]byte, error)

	// NVRead reads the bytes from the specified nv index/handle.  It returns an
	// error if the handle is not within the range of valid nv ram or if the index
	// does not exist.
	NVRead(nvHandle int) ([]byte, error)

	// NVWRite writes bytes to the specified nv handle/index.  It returns an
	// error if the handle is not within the range of valid nv ram or if the index
	// does not exist.
	NVWrite(nvHandle int, data []byte) error

	// NVExists checks if the specified nv handle/index exists. It returns false if
	// the handle is not within the range of valid nv ram or if the index does not exist.
	NVExists(nvHandle int) bool

	// NVDefine creates a new nv index with the specified handle and size.  It returns
	// an error if the handle is not within the range of valid nv indexes.
	NVDefine(nvHandle int, len int) error

	// NVDelete deletes the specified nv handle/index.  It returns an error if the
	// handle is not within the range of valid nv ram or if the index does not exist.
	NVDelete(nvHandle int) error

	// ReadPublic returns the public key, TPMT Public bytes and qualified name bytes from the
	// public handle argument.  It returns an error if  the handle is not persistent
	// or does not exist.
	ReadPublic(handle int) (crypto.PublicKey, []byte, []byte, error)

	// GetEKCertificate is a utility function that reads NV ram at the specified
	// index and parses its contents into an x509 certificate
	GetEKCertificate(nvIndex int) (*x509.Certificate, error)

	// GetQuote returns a TPM quote for the given nonce using the specified AK handle.  Rturns
	// an error if the akHandle is invalid or does not exist.    If 'selection'
	// is not provided, then all sha256 banks will be included in the quote.
	GetQuote(akHandle int, nonce []byte, selection ...PcrSelection) ([]byte, []byte, error)

	// GetPcrs returns the "flattened", concatenated, contiguous PCR measurements
	// for SHA-256 banks 0-23 (in index order).  This is similar to the pcr values
	// returned in tpm2_quote when '-F values' options are provided.  If 'selection'
	// is not provided, then all sha256 banks are included in the results.
	GetPcrs(selection ...PcrSelection) ([]byte, error)

	// HandleExists is a utility function that returns true if the handle exists in the TPM.
	HandleExists(handle int) bool

	// Close closes the TPM.
	Close()
}

Source Files

View all Source files

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.