client

package
v0.0.0-...-8b56602 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2022 License: Apache-2.0, BSD-3-Clause Imports: 19 Imported by: 0

Documentation

Overview

Package client contains some high-level TPM 2.0 functions.

Index

Constants

View Source 
const (
	EKReservedHandle     = tpmutil.Handle(0x81010001)
	EKECCReservedHandle  = tpmutil.Handle(0x81010002)
	SRKReservedHandle    = tpmutil.Handle(0x81000001)
	SRKECCReservedHandle = tpmutil.Handle(0x81000002)
)

Reserved Handles from "TCG TPM v2.0 Provisioning Guidance" - v1r1 - Table 2

View Source 
const (
	// RSA 2048 EK Cert.
	EKCertNVIndexRSA uint32 = 0x01c00002
	// ECC P256 EK Cert.
	EKCertNVIndexECC uint32 = 0x01c0000a
)

From "TCG EK Credential Profile", v2.3r2 Section 2.2.1.4

View Source 
const (
	DefaultAKECCHandle = tpmutil.Handle(0x81008F00)
	DefaultAKRSAHandle = tpmutil.Handle(0x81008F01)
)

Picked available handles from TPM 2.0 Handles and Localities 2.3.1 - Table 11 go-tpm-tools will use handles in the range from 0x81008F00 to 0x81008FFF

View Source 
const (
	// RSA 2048 AK.
	GceAKCertNVIndexRSA     uint32 = 0x01c10000
	GceAKTemplateNVIndexRSA uint32 = 0x01c10001
	// ECC P256 AK.
	GceAKCertNVIndexECC     uint32 = 0x01c10002
	GceAKTemplateNVIndexECC uint32 = 0x01c10003
)

GCE Attestation Key NV Indices

View Source 
const (
	SessionHashAlg    = crypto.SHA256
	SessionHashAlgTpm = tpm2.AlgSHA256
)

We hard-code SHA256 as the policy session hash algorithms. Note that this differs from the PCR hash algorithm (which selects the bank of PCRs to use) and the Public area Name algorithm. We also chose this for compatibility with github.com/google/go-tpm/tpm2, as it hardcodes the nameAlg as SHA256 in several places. Two constants are used to avoid repeated conversions.

View Source 
const CertifyHashAlgTpm = tpm2.AlgSHA256

CertifyHashAlgTpm is the hard-coded algorithm used in certify PCRs.

View Source 
const NumPCRs = 24

NumPCRs is set to the spec minimum of 24, as that's all go-tpm supports.

Variables

This section is empty.

Functions

func AKTemplateECC 

func AKTemplateECC() tpm2.Public

AKTemplateECC returns a potential Attestation Key (AK) template. This is very similar to DefaultEKTemplateECC, except that this will be a signing key instead of an encrypting key.

func AKTemplateRSA 

func AKTemplateRSA() tpm2.Public

AKTemplateRSA returns a potential Attestation Key (AK) template. This is very similar to DefaultEKTemplateRSA, except that this will be a signing key instead of an encrypting key.

func CheckedClose 

func CheckedClose(tb testing.TB, rwc io.ReadWriteCloser)

CheckedClose closes the simulator and asserts that there were no leaked handles.

func DefaultEKTemplateECC 

func DefaultEKTemplateECC() tpm2.Public

DefaultEKTemplateECC returns the default Endorsement Key (EK) template as specified in Credential_Profile_EK_V2.0, section 2.1.5.2 - authPolicy. https://trustedcomputinggroup.org/wp-content/uploads/Credential_Profile_EK_V2.0_R14_published.pdf

func DefaultEKTemplateRSA 

func DefaultEKTemplateRSA() tpm2.Public

DefaultEKTemplateRSA returns the default Endorsement Key (EK) template as specified in Credential_Profile_EK_V2.0, section 2.1.5.1 - authPolicy. https://trustedcomputinggroup.org/wp-content/uploads/Credential_Profile_EK_V2.0_R14_published.pdf

func FullPcrSel 

func FullPcrSel(hash tpm2.Algorithm) tpm2.PCRSelection

FullPcrSel will return a full PCR selection based on the total PCR number of the TPM with the given hash algo.

func GetEventLog 

func GetEventLog(rw io.ReadWriter) ([]byte, error)

GetEventLog grabs the crypto-agile TCG event log for the system. The TPM can override this implementation by implementing EventLogGetter.

func Handles 

func Handles(rw io.ReadWriter, handleType tpm2.HandleType) ([]tpmutil.Handle, error)

Handles returns a slice of tpmutil.Handle objects of all handles within the TPM rw of type handleType.

func ReadAllPCRs 

func ReadAllPCRs(rw io.ReadWriter) ([]*pb.PCRs, error)

ReadAllPCRs fetches all the PCR values from all implemented PCR banks.

func ReadPCRs 

func ReadPCRs(rw io.ReadWriter, sel tpm2.PCRSelection) (*pb.PCRs, error)

ReadPCRs fetches all the PCR values specified in sel, making multiple calls to the TPM if necessary.

func SRKTemplateECC 

func SRKTemplateECC() tpm2.Public

SRKTemplateECC returns a standard Storage Root Key (SRK) template. This is based upon the advice in the TCG's TPM v2.0 Provisioning Guidance.

func SRKTemplateRSA 

func SRKTemplateRSA() tpm2.Public

SRKTemplateRSA returns a standard Storage Root Key (SRK) template. This is based upon the advice in the TCG's TPM v2.0 Provisioning Guidance.

Types

type EventLogGetter 

type EventLogGetter interface {
	EventLog() ([]byte, error)
}

EventLogGetter allows a TPM (io.ReadWriter) to specify a particular implementation for GetEventLog(). This is useful for testing and necessary for Windows Event Log support (which requires a handle to the TPM).

type Key 

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

Key wraps an active asymmetric TPM2 key. This can either be a signing key or an encryption key. Users of Key should be sure to call Close() when the Key is no longer needed, so that the underlying TPM handle can be freed. Concurrent accesses on Key are not safe, with the exception of the Sign method called on the crypto.Signer returned by Key.GetSigner.

func AttestationKeyECC 

func AttestationKeyECC(rw io.ReadWriter) (*Key, error)

AttestationKeyECC generates and loads a key from AKTemplateECC in the Owner hierarchy.

func AttestationKeyRSA 

func AttestationKeyRSA(rw io.ReadWriter) (*Key, error)

AttestationKeyRSA generates and loads a key from AKTemplateRSA in the Owner hierarchy.

func EndorsementKeyECC 

func EndorsementKeyECC(rw io.ReadWriter) (*Key, error)

EndorsementKeyECC generates and loads a key from DefaultEKTemplateECC.

func EndorsementKeyFromNvIndex 

func EndorsementKeyFromNvIndex(rw io.ReadWriter, idx uint32) (*Key, error)

EndorsementKeyFromNvIndex generates and loads an endorsement key using the template stored at the provided nvdata index. This is useful for TPMs which have a preinstalled AK template.

func EndorsementKeyRSA 

func EndorsementKeyRSA(rw io.ReadWriter) (*Key, error)

EndorsementKeyRSA generates and loads a key from DefaultEKTemplateRSA.

func GceAttestationKeyECC 

func GceAttestationKeyECC(rw io.ReadWriter) (*Key, error)

GceAttestationKeyECC generates and loads the GCE ECC AK. Note that this function will only work on a GCE VM. Unlike AttestationKeyECC, this key uses the Endorsement Hierarchy and its template loaded from GceAKTemplateNVIndexECC.

func GceAttestationKeyRSA 

func GceAttestationKeyRSA(rw io.ReadWriter) (*Key, error)

GceAttestationKeyRSA generates and loads the GCE RSA AK. Note that this function will only work on a GCE VM. Unlike AttestationKeyRSA, this key uses the Endorsement Hierarchy and its template loaded from GceAKTemplateNVIndexRSA.

func KeyFromNvIndex 

func KeyFromNvIndex(rw io.ReadWriter, parent tpmutil.Handle, idx uint32) (*Key, error)

KeyFromNvIndex generates and loads a key under the provided parent (possibly a hierarchy root tpm2.Handle{Owner|Endorsement|Platform|Null}) using the template stored at the provided nvdata index.

func NewCachedKey 

func NewCachedKey(rw io.ReadWriter, parent tpmutil.Handle, template tpm2.Public, cachedHandle tpmutil.Handle) (k *Key, err error)

NewCachedKey is almost identical to NewKey, except that it initially tries to see if the a key matching the provided template is at cachedHandle. If so, that key is returned. If not, the key is created as in NewKey, and that key is persisted to the cachedHandle, overwriting any existing key there.

func NewKey 

func NewKey(rw io.ReadWriter, parent tpmutil.Handle, template tpm2.Public) (k *Key, err error)

NewKey generates a key from the template and loads that key into the TPM under the specified parent. NewKey can call many different TPM commands:

  • If parent is tpm2.Handle{Owner|Endorsement|Platform|Null} a primary key is created in the specified hierarchy (using CreatePrimary).
  • If parent is a valid key handle, a normal key object is created under that parent (using Create and Load). NOTE: Not yet supported.

This function also assumes that the desired key:

  • Does not have its usage locked to specific PCR values
  • Usable with empty authorization sessions (i.e. doesn't need a password)

func StorageRootKeyECC 

func StorageRootKeyECC(rw io.ReadWriter) (*Key, error)

StorageRootKeyECC generates and loads a key from SRKTemplateECC.

func StorageRootKeyRSA 

func StorageRootKeyRSA(rw io.ReadWriter) (*Key, error)

StorageRootKeyRSA generates and loads a key from SRKTemplateRSA.

func (*Key) Cert 

func (k *Key) Cert() *x509.Certificate

Cert returns the parsed certificate (or nil) for the given key.

func (*Key) CertDERBytes 

func (k *Key) CertDERBytes() []byte

CertDERBytes provides the ASN.1 DER content of the key's certificate. If the key does not have a certficate, returns nil.

func (*Key) Close 

func (k *Key) Close()

Close should be called when the key is no longer needed. This is important to do as most TPMs can only have a small number of key simultaneously loaded.

func (*Key) GetSigner 

func (k *Key) GetSigner() (crypto.Signer, error)

GetSigner returns a crypto.Signer wrapping the loaded TPM Key. Concurrent use of one or more Signers is thread safe, but it is not safe to access the TPM from other sources while using a Signer. The returned Signer lasts the lifetime of the Key, and will no longer work once the Key has been closed.

func (*Key) Handle 

func (k *Key) Handle() tpmutil.Handle

Handle allows this key to be used directly with other go-tpm commands.

func (*Key) Import 

func (k *Key) Import(blob *pb.ImportBlob) ([]byte, error)

Import decrypts the secret contained in an encoded import request. The key used must be an encryption key (signing keys cannot be used). The req parameter should come from server.CreateImportBlob.

func (*Key) ImportSigningKey 

func (k *Key) ImportSigningKey(blob *pb.ImportBlob) (key *Key, err error)

ImportSigningKey returns the signing key contained in an encoded import request. The parent key must be an encryption key (signing keys cannot be used). The req parameter should come from server.CreateSigningKeyImportBlob.

func (*Key) Name 

func (k *Key) Name() tpm2.Name

Name is hash of this key's public area. Only the Digest field will ever be populated. It is useful for various TPM commands related to authorization. This is equivalent to k.PublicArea.Name(), except that is cannot fail.

func (*Key) PublicArea 

func (k *Key) PublicArea() tpm2.Public

PublicArea exposes the key's entire public area. This is useful for determining additional properties of the underlying TPM key.

func (*Key) PublicKey 

func (k *Key) PublicKey() crypto.PublicKey

PublicKey provides a go interface to the loaded key's public area.

func (*Key) Quote 

func (k *Key) Quote(selpcr tpm2.PCRSelection, extraData []byte) (*pb.Quote, error)

Quote will tell TPM to compute a hash of a set of given PCR selection, together with some extra data (typically a nonce), sign it with the given signing key, and return the signature and the attestation data. This function will return an error if the key is not a restricted signing key.

func (*Key) Reseal 

func (k *Key) Reseal(in *pb.SealedBytes, uOpts UnsealOpts, sOpts SealOpts) (*pb.SealedBytes, error)

Reseal is a shortcut to call Unseal() followed by Seal(). CertifyOpt(nillable) will be used in Unseal(), and SealOpt(nillable) will be used in Seal()

func (*Key) Seal 

func (k *Key) Seal(sensitive []byte, opts SealOpts) (*pb.SealedBytes, error)

Seal seals the sensitive byte buffer to a key. This key must be an SRK (we currently do not support sealing to EKs). Optionally, the SealOpts struct can be modified to provide sealed-to PCRs. In this case, the sensitive data can only be unsealed if the seal-time PCRs are in the SealOpts-specified state. There must not be overlap in PCRs between SealOpts' Current and Target. During the sealing process, certification data will be created allowing Unseal() to validate the state of the TPM during the sealing process.

func (*Key) SetCert 

func (k *Key) SetCert(cert *x509.Certificate) error

SetCert assigns the provided certificate to the key after verifying it matches the key.

func (*Key) SignData 

func (k *Key) SignData(data []byte) ([]byte, error)

SignData signs a data buffer with a TPM loaded key. Unlike GetSigner, this method works with restricted and unrestricted keys. If this method is called on a restriced key, the TPM itself will hash the provided data, failing the signing operation if the data begins with TPM_GENERATED_VALUE.

func (*Key) Unseal 

func (k *Key) Unseal(in *pb.SealedBytes, opts UnsealOpts) ([]byte, error)

Unseal attempts to reverse the process of Seal(), using the PCRs, public, and private data in proto.SealedBytes. Optionally, the UnsealOpts parameter can be used to verify the state of the TPM when the data was sealed. The zero-value UnsealOpts can be passed to skip certification.

type SealOpts 

type SealOpts struct {
	// Current seals data to the current specified PCR selection.
	Current tpm2.PCRSelection
	// Target predictively seals data to the given specified PCR values.
	Target *pb.PCRs
}

SealOpts specifies the PCR values that should be used for Seal().

type UnsealOpts 

type UnsealOpts struct {
	// CertifyCurrent certifies that a selection of current PCRs have the same
	// value when sealing.
	CertifyCurrent tpm2.PCRSelection
	// CertifyExpected certifies that the TPM had a specific set of PCR values when sealing.
	CertifyExpected *pb.PCRs
}

UnsealOpts specifies the options that should be used for Unseal(). Currently, it specifies the PCRs that need to pass certification in order to successfully unseal. CertifyHashAlgTpm is the hard-coded algorithm that must be used with UnsealOpts.

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.