Documentation ¶
Overview ¶
Package tpm2tools contains some high-level TPM 2.0 functions.
Index ¶
- Constants
- func AIKTemplateECC() tpm2.Public
- func AIKTemplateRSA() tpm2.Public
- func CheckedClose(tb testing.TB, rwc io.ReadWriteCloser)
- func ComputePCRSessionAuth(pcrs *tpmpb.Pcrs) []byte
- func DefaultEKTemplateECC() tpm2.Public
- func DefaultEKTemplateRSA() tpm2.Public
- func FullPcrSel(hash tpm2.Algorithm) tpm2.PCRSelection
- func Handles(rw io.ReadWriter, handleType tpm2.HandleType) ([]tpmutil.Handle, error)
- func HasSamePCRSelection(pcrs *tpmpb.Pcrs, pcrSel tpm2.PCRSelection) bool
- func PCRSelection(pcrs *tpmpb.Pcrs) tpm2.PCRSelection
- func ReadPCRs(rw io.ReadWriter, sel tpm2.PCRSelection) (*tpmpb.Pcrs, error)
- func SRKTemplateECC() tpm2.Public
- func SRKTemplateRSA() tpm2.Public
- type CertifyCurrent
- type CertifyExpected
- type CertifyOpt
- type Key
- func AttestationIdentityKeyECC(rw io.ReadWriter) (*Key, error)
- func AttestationIdentityKeyRSA(rw io.ReadWriter) (*Key, error)
- func EndorsementKeyECC(rw io.ReadWriter) (*Key, error)
- func EndorsementKeyFromNvIndex(rw io.ReadWriter, idx uint32) (*Key, error)
- func EndorsementKeyRSA(rw io.ReadWriter) (*Key, error)
- func KeyFromNvIndex(rw io.ReadWriter, parent tpmutil.Handle, idx uint32) (*Key, error)
- func NewCachedKey(rw io.ReadWriter, parent tpmutil.Handle, template tpm2.Public, ...) (k *Key, err error)
- func NewKey(rw io.ReadWriter, parent tpmutil.Handle, template tpm2.Public) (k *Key, err error)
- func StorageRootKeyECC(rw io.ReadWriter) (*Key, error)
- func StorageRootKeyRSA(rw io.ReadWriter) (*Key, error)
- func (k *Key) Close()
- func (k *Key) GetSigner() (crypto.Signer, error)
- func (k *Key) Handle() tpmutil.Handle
- func (k *Key) Import(blob *tpmpb.ImportBlob) ([]byte, error)
- func (k *Key) ImportSigningKey(blob *tpmpb.ImportBlob) (key *Key, err error)
- func (k *Key) Name() tpm2.Name
- func (k *Key) PublicKey() crypto.PublicKey
- func (k *Key) Reseal(in *tpmpb.SealedBytes, cOpt CertifyOpt, sOpt SealOpt) (*tpmpb.SealedBytes, error)
- func (k *Key) Seal(sensitive []byte, sOpt SealOpt) (*tpmpb.SealedBytes, error)
- func (k *Key) SignData(data []byte) ([]byte, error)
- func (k *Key) Unseal(in *tpmpb.SealedBytes, cOpt CertifyOpt) ([]byte, error)
- type SealCurrent
- type SealOpt
- type SealTarget
Constants ¶
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
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
const CertifyHashAlgTpm = tpm2.AlgSHA256
CertifyHashAlgTpm is the hard-coded algorithm used in certify PCRs.
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
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 ¶
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
ComputePCRSessionAuth calculates the authorization value for the given PCRs.
func DefaultEKTemplateECC ¶
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 ¶
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 ¶
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 ¶
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
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 ¶
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 ¶
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
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) 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 ¶
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) 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 ¶
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
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
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.