tpm2tools

package
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Dec 11, 2020 License: Apache-2.0, BSD-3-Clause Imports: 15 Imported by: 0

Documentation

Overview

Package tpm2tools 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 (
	DefaultAIKECCHandle = tpmutil.Handle(0x81008F00)
	DefaultAIKRSAHandle = 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 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 AIKTemplateECC added in v0.2.0 

func AIKTemplateECC() tpm2.Public

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

func AIKTemplateRSA 

func AIKTemplateRSA() tpm2.Public

AIKTemplateRSA returns a potential Attestation Identity Key (AIK) 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 ComputePCRSessionAuth added in v0.1.2 

func ComputePCRSessionAuth(pcrs *tpmpb.Pcrs) []byte

ComputePCRSessionAuth calculates the authorization value for the given PCRs.

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 added in v0.1.2 

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 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 HasSamePCRSelection added in v0.1.2 

func HasSamePCRSelection(pcrs *tpmpb.Pcrs, pcrSel tpm2.PCRSelection) bool

HasSamePCRSelection checks the given tpmpb.Pcrs has the same PCRSelection as the given tpm2.PCRSelection (including the hash algorithm).

func PCRSelection added in v0.1.2 

func PCRSelection(pcrs *tpmpb.Pcrs) tpm2.PCRSelection

PCRSelection returns the corresponding tpm2.PCRSelection for a tpmpb.Pcrs

func ReadPCRs added in v0.1.2 

func ReadPCRs(rw io.ReadWriter, sel tpm2.PCRSelection) (*tpmpb.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 CertifyCurrent added in v0.1.2 

type CertifyCurrent struct{ tpm2.PCRSelection }

CertifyCurrent certifies that a selection of current PCRs have the same value when sealing. Hash Algorithm in the selection should be CertifyHashAlgTpm.

func (CertifyCurrent) CertifyPCRs added in v0.1.2 

func (p CertifyCurrent) CertifyPCRs(rw io.ReadWriter, pcrs *tpmpb.Pcrs) error

CertifyPCRs from CurrentPCRs will read PCR values from TPM and compare the digest.

type CertifyExpected added in v0.1.2 

type CertifyExpected struct{ Pcrs *tpmpb.Pcrs }

CertifyExpected certifies that the TPM had a specific set of PCR values when sealing. Hash Algorithm in the PCR proto should be CertifyHashAlgTpm.

func (CertifyExpected) CertifyPCRs added in v0.1.2 

func (p CertifyExpected) CertifyPCRs(_ io.ReadWriter, pcrs *tpmpb.Pcrs) error

CertifyPCRs will compare the digest with given expected PCRs values.

type CertifyOpt added in v0.1.2 

type CertifyOpt interface {
	CertifyPCRs(rw io.ReadWriter, certified *tpmpb.Pcrs) error
}

CertifyOpt determines if the given PCR value can pass certification in Unseal().

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.

func AttestationIdentityKeyECC added in v0.2.0 

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

AttestationIdentityKeyECC generates and loads a key from AIKTemplateECC

func AttestationIdentityKeyRSA added in v0.1.2 

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

AttestationIdentityKeyRSA generates and loads a key from AIKTemplateRSA

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

func EndorsementKeyRSA 

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

EndorsementKeyRSA generates and loads a key from DefaultEKTemplateRSA.

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) 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 added in v0.1.2 

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 *tpmpb.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 added in v0.2.0 

func (k *Key) ImportSigningKey(blob *tpmpb.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.

func (*Key) PublicKey 

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

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

func (*Key) Reseal 

func (k *Key) Reseal(in *tpmpb.SealedBytes, cOpt CertifyOpt, sOpt SealOpt) (*tpmpb.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, sOpt SealOpt) (*tpmpb.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, a non-nil SealOpt can be provided. In this case, the sensitive data can only be unsealed if the PCRs are in the specified state. During the sealing process, certification data will be created allowing Unseal() to validate the state of the TPM during the sealing process.

func (*Key) SignData added in v0.2.1 

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 *tpmpb.SealedBytes, cOpt CertifyOpt) ([]byte, error)

Unseal attempts to reverse the process of Seal(), using the PCRs, public, and private data in proto.SealedBytes. Optionally, a CertifyOpt can be passed, to verify the state of the TPM when the data was sealed. A nil value can be passed to skip certification.

type SealCurrent added in v0.1.2 

type SealCurrent struct{ tpm2.PCRSelection }

SealCurrent seals data to the current specified PCR selection.

func (SealCurrent) PCRsForSealing added in v0.1.2 

func (p SealCurrent) PCRsForSealing(rw io.ReadWriter) (*tpmpb.Pcrs, error)

PCRsForSealing read from TPM and return the selected PCRs.

type SealOpt added in v0.1.2 

type SealOpt interface {
	PCRsForSealing(rw io.ReadWriter) (*tpmpb.Pcrs, error)
}

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

type SealTarget added in v0.1.2 

type SealTarget struct{ Pcrs *tpmpb.Pcrs }

SealTarget predicatively seals data to the given specified PCR values.

func (SealTarget) PCRsForSealing added in v0.1.2 

func (p SealTarget) PCRsForSealing(_ io.ReadWriter) (*tpmpb.Pcrs, error)

PCRsForSealing return the target PCRs.

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.