tpm2

package
Version: v0.3.2 Latest Latest
Warning

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

Go to latest
Published: Dec 12, 2020 License: Apache-2.0 Imports: 18 Imported by: 87

README

TPM 2.0 client library

Tests

This library contains unit tests in github.com/google/go-tpm/tpm2, which just tests that various encoding and error checking functions work correctly. It also contains more comprehensive integration tests in github.com/google/go-tpm/tpm2/test, which run actual commands on a TPM.

By default, these integration tests are run against the go-tpm-tools simulator, which is baesed on the Microsoft Reference TPM2 code. To run both the unit and integration tests, run (in this directory)

go test . ./test

These integration tests can also be run against a real TPM device. This is slightly more complex as the tests often need to be built as a normal user and then executed as root. For example,

# Build the test binary without running it
go test -c github.com/google/go-tpm/tpm2/test
# Execute the test binary as root
sudo ./test.test --tpm-path=/dev/tpmrm0

On Linux, The --tpm-path causes the integration tests to be run against a real TPM located at that path (usually /dev/tpmrm0 or /dev/tpm0). On Windows, the story is similar, execept that the --use-tbs flag is used instead.

Tip: if your TPM host is remote and you don't want to install Go on it, this same two-step process can be used. The test binary can be copied to a remote host and run without extra installation (as the test binary has very few runtime dependancies).

Documentation

Overview

Package tpm2 supports direct communication with a TPM 2.0 device under Linux.

Index

Constants

View Source
const (
	HandleOwner tpmutil.Handle = 0x40000001 + iota
	HandleRevoke
	HandleTransport
	HandleOperator
	HandleAdmin
	HandleEK
	HandleNull
	HandleUnassigned
	HandlePasswordSession
	HandleLockout
	HandleEndorsement
	HandlePlatform
)

Reserved Handles.

View Source
const (
	TagNull           tpmutil.Tag = 0x8000
	TagNoSessions     tpmutil.Tag = 0x8001
	TagSessions       tpmutil.Tag = 0x8002
	TagAttestCertify  tpmutil.Tag = 0x8017
	TagAttestQuote    tpmutil.Tag = 0x8018
	TagAttestCreation tpmutil.Tag = 0x801a
	TagHashCheck      tpmutil.Tag = 0x8024
)

TPM Structure Tags. Tags are used to disambiguate structures, similar to Alg values: tag value defines what kind of data lives in a nested field.

View Source
const (
	CurveNISTP192 = EllipticCurve(iota + 1)
	CurveNISTP224
	CurveNISTP256
	CurveNISTP384
	CurveNISTP521

	CurveBNP256 = EllipticCurve(iota + 10)
	CurveBNP638

	CurveSM2P256 = EllipticCurve(0x0020)
)

ECC curves supported by TPM 2.0 spec.

View Source
const (
	CmdNVUndefineSpaceSpecial     tpmutil.Command = 0x0000011F
	CmdEvictControl               tpmutil.Command = 0x00000120
	CmdUndefineSpace              tpmutil.Command = 0x00000122
	CmdClear                      tpmutil.Command = 0x00000126
	CmdHierarchyChangeAuth        tpmutil.Command = 0x00000129
	CmdDefineSpace                tpmutil.Command = 0x0000012A
	CmdCreatePrimary              tpmutil.Command = 0x00000131
	CmdIncrementNVCounter         tpmutil.Command = 0x00000134
	CmdWriteNV                    tpmutil.Command = 0x00000137
	CmdWriteLockNV                tpmutil.Command = 0x00000138
	CmdDictionaryAttackLockReset  tpmutil.Command = 0x00000139
	CmdDictionaryAttackParameters tpmutil.Command = 0x0000013A
	CmdPCREvent                   tpmutil.Command = 0x0000013C
	CmdSequenceComplete           tpmutil.Command = 0x0000013E
	CmdStartup                    tpmutil.Command = 0x00000144
	CmdShutdown                   tpmutil.Command = 0x00000145
	CmdActivateCredential         tpmutil.Command = 0x00000147
	CmdCertify                    tpmutil.Command = 0x00000148
	CmdCertifyCreation            tpmutil.Command = 0x0000014A
	CmdReadNV                     tpmutil.Command = 0x0000014E
	CmdReadLockNV                 tpmutil.Command = 0x0000014F
	CmdPolicySecret               tpmutil.Command = 0x00000151
	CmdCreate                     tpmutil.Command = 0x00000153
	CmdECDHZGen                   tpmutil.Command = 0x00000154
	CmdImport                     tpmutil.Command = 0x00000156
	CmdLoad                       tpmutil.Command = 0x00000157
	CmdQuote                      tpmutil.Command = 0x00000158
	CmdRSADecrypt                 tpmutil.Command = 0x00000159
	CmdSequenceUpdate             tpmutil.Command = 0x0000015C
	CmdSign                       tpmutil.Command = 0x0000015D
	CmdUnseal                     tpmutil.Command = 0x0000015E
	CmdContextLoad                tpmutil.Command = 0x00000161
	CmdContextSave                tpmutil.Command = 0x00000162
	CmdECDHKeyGen                 tpmutil.Command = 0x00000163
	CmdEncryptDecrypt             tpmutil.Command = 0x00000164
	CmdFlushContext               tpmutil.Command = 0x00000165
	CmdLoadExternal               tpmutil.Command = 0x00000167
	CmdMakeCredential             tpmutil.Command = 0x00000168
	CmdReadPublicNV               tpmutil.Command = 0x00000169
	CmdPolicyCommandCode          tpmutil.Command = 0x0000016C
	CmdPolicyOr                   tpmutil.Command = 0x00000171
	CmdReadPublic                 tpmutil.Command = 0x00000173
	CmdRSAEncrypt                 tpmutil.Command = 0x00000174
	CmdStartAuthSession           tpmutil.Command = 0x00000176
	CmdGetCapability              tpmutil.Command = 0x0000017A
	CmdGetRandom                  tpmutil.Command = 0x0000017B
	CmdHash                       tpmutil.Command = 0x0000017D
	CmdPCRRead                    tpmutil.Command = 0x0000017E
	CmdPolicyPCR                  tpmutil.Command = 0x0000017F
	CmdReadClock                  tpmutil.Command = 0x00000181
	CmdPCRExtend                  tpmutil.Command = 0x00000182
	CmdEventSequenceComplete      tpmutil.Command = 0x00000185
	CmdHashSequenceStart          tpmutil.Command = 0x00000186
	CmdPolicyGetDigest            tpmutil.Command = 0x00000189
	CmdPolicyPassword             tpmutil.Command = 0x0000018C
	CmdEncryptDecrypt2            tpmutil.Command = 0x00000193
)

Supported TPM operations.

View Source
const (
	RCInitialize      RCFmt0 = 0x00
	RCFailure                = 0x01
	RCSequence               = 0x03
	RCPrivate                = 0x0B
	RCHMAC                   = 0x19
	RCDisabled               = 0x20
	RCExclusive              = 0x21
	RCAuthType               = 0x24
	RCAuthMissing            = 0x25
	RCPolicy                 = 0x26
	RCPCR                    = 0x27
	RCPCRChanged             = 0x28
	RCUpgrade                = 0x2D
	RCTooManyContexts        = 0x2E
	RCAuthUnavailable        = 0x2F
	RCReboot                 = 0x30
	RCUnbalanced             = 0x31
	RCCommandSize            = 0x42
	RCCommandCode            = 0x43
	RCAuthSize               = 0x44
	RCAuthContext            = 0x45
	RCNVRange                = 0x46
	RCNVSize                 = 0x47
	RCNVLocked               = 0x48
	RCNVAuthorization        = 0x49
	RCNVUninitialized        = 0x4A
	RCNVSpace                = 0x4B
	RCNVDefined              = 0x4C
	RCBadContext             = 0x50
	RCCPHash                 = 0x51
	RCParent                 = 0x52
	RCNeedsTest              = 0x53
	RCNoResult               = 0x54
	RCSensitive              = 0x55
)

Format 0 error codes.

View Source
const (
	RCAsymmetric   = 0x01
	RCAttributes   = 0x02
	RCHash         = 0x03
	RCValue        = 0x04
	RCHierarchy    = 0x05
	RCKeySize      = 0x07
	RCMGF          = 0x08
	RCMode         = 0x09
	RCType         = 0x0A
	RCHandle       = 0x0B
	RCKDF          = 0x0C
	RCRange        = 0x0D
	RCAuthFail     = 0x0E
	RCNonce        = 0x0F
	RCPP           = 0x10
	RCScheme       = 0x12
	RCSize         = 0x15
	RCSymmetric    = 0x16
	RCTag          = 0x17
	RCSelector     = 0x18
	RCInsufficient = 0x1A
	RCSignature    = 0x1B
	RCKey          = 0x1C
	RCPolicyFail   = 0x1D
	RCIntegrity    = 0x1F
	RCTicket       = 0x20
	RCReservedBits = 0x21
	RCBadAuth      = 0x22
	RCExpired      = 0x23
	RCPolicyCC     = 0x24
	RCBinding      = 0x25
	RCCurve        = 0x26
	RCECCPoint     = 0x27
)

Format 1 error codes.

View Source
const (
	RCContextGap     RCWarn = 0x01
	RCObjectMemory          = 0x02
	RCSessionMemory         = 0x03
	RCMemory                = 0x04
	RCSessionHandles        = 0x05
	RCObjectHandles         = 0x06
	RCLocality              = 0x07
	RCYielded               = 0x08
	RCCanceled              = 0x09
	RCTesting               = 0x0A
	RCReferenceH0           = 0x10
	RCReferenceH1           = 0x11
	RCReferenceH2           = 0x12
	RCReferenceH3           = 0x13
	RCReferenceH4           = 0x14
	RCReferenceH5           = 0x15
	RCReferenceH6           = 0x16
	RCReferenceS0           = 0x18
	RCReferenceS1           = 0x19
	RCReferenceS2           = 0x1A
	RCReferenceS3           = 0x1B
	RCReferenceS4           = 0x1C
	RCReferenceS5           = 0x1D
	RCReferenceS6           = 0x1E
	RCNVRate                = 0x20
	RCLockout               = 0x21
	RCRetry                 = 0x22
	RCNVUnavailable         = 0x23
)

Warning codes.

Variables

View Source
var EmptyAuth []byte

EmptyAuth represents the empty authorization value.

Functions

func ActivateCredential

func ActivateCredential(rw io.ReadWriter, activeHandle, keyHandle tpmutil.Handle, activePassword, protectorPassword string, credBlob, secret []byte) ([]byte, error)

ActivateCredential associates an object with a credential. Returns decrypted certificate information.

func ActivateCredentialUsingAuth

func ActivateCredentialUsingAuth(rw io.ReadWriter, auth []AuthCommand, activeHandle, keyHandle tpmutil.Handle, credBlob, secret []byte) ([]byte, error)

ActivateCredentialUsingAuth associates an object with a credential, using the given set of authorizations. Two authorization must be provided. Returns decrypted certificate information.

func Certify

func Certify(rw io.ReadWriter, objectAuth, signerAuth string, object, signer tpmutil.Handle, qualifyingData []byte) ([]byte, []byte, error)

Certify generates a signature of a loaded TPM object with a signing key signer. This function calls encodeCertify which makes use of the hardcoded signing scheme {AlgRSASSA, AlgSHA256}. Returned values are: attestation data (TPMS_ATTEST), signature and error, if any.

func CertifyCreation

func CertifyCreation(rw io.ReadWriter, objectAuth string, object, signer tpmutil.Handle, qualifyingData, creationHash []byte, sigScheme SigScheme, creationTicket Ticket) (attestation, signature []byte, err error)

CertifyCreation generates a signature of a newly-created & loaded TPM object, using signer as the signing key.

func CertifyEx added in v0.3.1

func CertifyEx(rw io.ReadWriter, objectAuth, signerAuth string, object, signer tpmutil.Handle, qualifyingData []byte, scheme SigScheme) ([]byte, []byte, error)

CertifyEx generates a signature of a loaded TPM object with a signing key signer. This function differs from Certify in that it takes the scheme to be used as an additional argument and calls encodeCertifyEx instead of encodeCertify. Returned values are: attestation data (TPMS_ATTEST), signature and error, if any.

func Clear added in v0.3.0

func Clear(rw io.ReadWriter, handle tpmutil.Handle, auth AuthCommand) error

Clear clears lockout, endorsement and owner hierarchy authorization values

func ContextLoad

func ContextLoad(rw io.ReadWriter, saveArea []byte) (tpmutil.Handle, error)

ContextLoad reloads context data created by ContextSave.

func ContextSave

func ContextSave(rw io.ReadWriter, handle tpmutil.Handle) ([]byte, error)

ContextSave returns an encrypted version of the session, object or sequence context for storage outside of the TPM. The handle references context to store.

func CreatePrimary

func CreatePrimary(rw io.ReadWriter, owner tpmutil.Handle, sel PCRSelection, parentPassword, ownerPassword string, p Public) (tpmutil.Handle, crypto.PublicKey, error)

CreatePrimary initializes the primary key in a given hierarchy. The second return value is the public part of the generated key.

func CreatePrimaryRawTemplate

func CreatePrimaryRawTemplate(rw io.ReadWriter, owner tpmutil.Handle, sel PCRSelection, parentPassword, ownerPassword string, public []byte) (tpmutil.Handle, crypto.PublicKey, error)

CreatePrimaryRawTemplate is CreatePrimary, but with the public template (TPMT_PUBLIC) provided pre-encoded. This is commonly used with key templates stored in NV RAM.

func DecryptSymmetric added in v0.2.0

func DecryptSymmetric(rw io.ReadWriteCloser, keyAuth string, key tpmutil.Handle, iv, data []byte) ([]byte, error)

DecryptSymmetric decrypts data using a symmetric key.

WARNING: This command performs low-level cryptographic operations. Secure use of this command is subtle and requires careful analysis. Please consult with experts in cryptography for how to use it securely.

The iv is the initialization vector. The iv must not be empty and its size depends on the details of the symmetric encryption scheme.

The data may be longer than block size, DecryptSymmetric will chain multiple TPM calls to decrypt the entire blob.

Key handle should point at SymCipher object which is a child of the key (and not e.g. RSA key itself).

func DictionaryAttackLockReset added in v0.3.0

func DictionaryAttackLockReset(rw io.ReadWriter, auth AuthCommand) error

DictionaryAttackLockReset cancels the effect of a TPM lockout due to a number of successive authorization failures, by setting the lockout counter to zero. The command requires Lockout Authorization and only one lockoutAuth authorization failure is allowed for this command during a lockoutRecovery interval. Lockout Authorization value by default is empty and can be changed via a call to HierarchyChangeAuth(HandleLockout).

func DictionaryAttackParameters added in v0.3.0

func DictionaryAttackParameters(rw io.ReadWriter, auth AuthCommand, maxTries, recoveryTime, lockoutRecovery uint32) error

DictionaryAttackParameters changes the lockout parameters. The command requires Lockout Authorization and has same authorization policy as in DictionaryAttackLockReset.

func EncryptSymmetric added in v0.2.0

func EncryptSymmetric(rw io.ReadWriteCloser, keyAuth string, key tpmutil.Handle, iv, data []byte) ([]byte, error)

EncryptSymmetric encrypts data using a symmetric key.

WARNING: This command performs low-level cryptographic operations. Secure use of this command is subtle and requires careful analysis. Please consult with experts in cryptography for how to use it securely.

The iv is the initialization vector. The iv must not be empty and its size depends on the details of the symmetric encryption scheme.

The data may be longer than block size, EncryptSymmetric will chain multiple TPM calls to encrypt the entire blob.

Key handle should point at SymCipher object which is a child of the key (and not e.g. RSA key itself).

func EvictControl

func EvictControl(rw io.ReadWriter, ownerAuth string, owner, objectHandle, persistentHandle tpmutil.Handle) error

EvictControl toggles persistence of an object within the TPM.

func FlushContext

func FlushContext(rw io.ReadWriter, handle tpmutil.Handle) error

FlushContext removes an object or session under handle to be removed from the TPM. This must be called for any loaded handle to avoid out-of-memory errors in TPM.

func GetCapability

func GetCapability(rw io.ReadWriter, capa Capability, count, property uint32) (vals []interface{}, moreData bool, err error)

GetCapability returns various information about the TPM state.

Currently only CapabilityHandles (list active handles) and CapabilityAlgs (list supported algorithms) are supported. CapabilityHandles will return a []tpmutil.Handle for vals, CapabilityAlgs will return []AlgorithmDescription.

moreData is true if the TPM indicated that more data is available. Follow the spec for the capability in question on how to query for more data.

func GetManufacturer added in v0.2.0

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

GetManufacturer returns the manufacturer ID

func GetRandom

func GetRandom(rw io.ReadWriter, size uint16) ([]byte, error)

GetRandom gets random bytes from the TPM.

func HashSequenceStart added in v0.3.2

func HashSequenceStart(rw io.ReadWriter, sequenceAuth string, hashAlg Algorithm) (seqHandle tpmutil.Handle, err error)

HashSequenceStart starts a hash or an event sequence. If hashAlg is an implemented hash, then a hash sequence is started. If hashAlg is TPM_ALG_NULL, then an event sequence is started.

func HierarchyChangeAuth added in v0.3.0

func HierarchyChangeAuth(rw io.ReadWriter, handle tpmutil.Handle, auth AuthCommand, newAuth string) error

HierarchyChangeAuth changes the authorization values for a hierarchy or for the lockout authority

func Import added in v0.3.0

func Import(rw io.ReadWriter, parentHandle tpmutil.Handle, auth AuthCommand, publicBlob, privateBlob, symSeed, encryptionKey []byte, sym *SymScheme) ([]byte, error)

Import allows a user to import a key created on a different computer or in a different TPM. The publicBlob and privateBlob must always be provided. symSeed should be non-nil iff an "outer wrapper" is used. Both of encryptionKey and sym should be non-nil iff an "inner wrapper" is used.

func KDFa

func KDFa(hashAlg Algorithm, key []byte, label string, contextU, contextV []byte, bits int) ([]byte, error)

KDFa implements TPM 2.0's default key derivation function, as defined in section 11.4.9.2 of the TPM revision 2 specification part 1. See: https://trustedcomputinggroup.org/resource/tpm-library-specification/ The key & label parameters must not be zero length. The label parameter is a non-null-terminated string. The contextU & contextV parameters are optional.

func KDFe added in v0.3.0

func KDFe(hashAlg Algorithm, z []byte, use string, partyUInfo, partyVInfo []byte, bits int) ([]byte, error)

KDFe implements TPM 2.0's ECDH key derivation function, as defined in section 11.4.9.3 of the TPM revision 2 specification part 1. See: https://trustedcomputinggroup.org/resource/tpm-library-specification/ The z parameter is the x coordinate of one parties private ECC key and the other parties public ECC key. The use parameter is a non-null-terminated string. The partyUInfo and partyVInfo are the x coordinates of the initiators and the responders ECC points respectively.

func Load

func Load(rw io.ReadWriter, parentHandle tpmutil.Handle, parentAuth string, publicBlob, privateBlob []byte) (tpmutil.Handle, []byte, error)

Load loads public/private blobs into an object in the TPM. Returns loaded object handle and its name.

func LoadExternal

func LoadExternal(rw io.ReadWriter, pub Public, private Private, hierarchy tpmutil.Handle) (tpmutil.Handle, []byte, error)

LoadExternal loads a public (and optionally a private) key into an object in the TPM. Returns loaded object handle and its name.

func LoadUsingAuth added in v0.2.0

func LoadUsingAuth(rw io.ReadWriter, parentHandle tpmutil.Handle, auth AuthCommand, publicBlob, privateBlob []byte) (tpmutil.Handle, []byte, error)

LoadUsingAuth loads public/private blobs into an object in the TPM using the provided AuthCommand. Returns loaded object handle and its name.

func MakeCredential

func MakeCredential(rw io.ReadWriter, protectorHandle tpmutil.Handle, credential, activeName []byte) ([]byte, []byte, error)

MakeCredential creates an encrypted credential for use in MakeCredential. Returns encrypted credential and wrapped secret used to encrypt it.

func NVDefineSpace

func NVDefineSpace(rw io.ReadWriter, owner, handle tpmutil.Handle, ownerAuth, authString string, policy []byte, attributes NVAttr, dataSize uint16) error

NVDefineSpace creates an index in TPM's NV storage.

func NVDefineSpaceEx added in v0.3.1

func NVDefineSpaceEx(rw io.ReadWriter, owner tpmutil.Handle, authVal string, pubInfo NVPublic, authArea AuthCommand) error

NVDefineSpaceEx accepts NVPublic structure and AuthCommand, allowing more flexibility.

func NVIncrement

func NVIncrement(rw io.ReadWriter, handle tpmutil.Handle, authString string) error

NVIncrement increments a counter in NVRAM.

func NVRead

func NVRead(rw io.ReadWriter, index tpmutil.Handle) ([]byte, error)

NVRead reads a full data blob from an NV index. This function is deprecated; use NVReadEx instead.

func NVReadEx

func NVReadEx(rw io.ReadWriter, index, authHandle tpmutil.Handle, password string, blockSize int) ([]byte, error)

NVReadEx reads a full data blob from an NV index, using the given authorization handle. NVRead commands are done in blocks of blockSize. If blockSize is 0, the TPM is queried for TPM_PT_NV_BUFFER_MAX, and that value is used.

func NVReadLock added in v0.3.0

func NVReadLock(rw io.ReadWriter, owner, handle tpmutil.Handle, authString string) error

NVReadLock inhibits further reads of the given NV index if AttrReadSTClear is set. After the TPM is restarted the index can be read again (see the Startup function).

NVReadLock returns an error if the AttrReadSTClear bit is not set.

It is not an error to call NVReadLock for an index that is already locked for reading.

func NVUndefineSpace

func NVUndefineSpace(rw io.ReadWriter, ownerAuth string, owner, index tpmutil.Handle) error

NVUndefineSpace removes an index from TPM's NV storage.

func NVUndefineSpaceEx added in v0.3.1

func NVUndefineSpaceEx(rw io.ReadWriter, owner, index tpmutil.Handle, authArea AuthCommand) error

NVUndefineSpaceEx removes an index from NVRAM. Unlike, NVUndefineSpace(), custom command authorization can be provided.

func NVUndefineSpaceSpecial added in v0.3.1

func NVUndefineSpaceSpecial(rw io.ReadWriter, nvIndex tpmutil.Handle, nvAuth, platformAuth AuthCommand) error

NVUndefineSpaceSpecial This command allows removal of a platform-created NV Index that has TPMA_NV_POLICY_DELETE SET. The policy to authorize NV index access needs to be created with PolicyCommandCode(rw, sessionHandle, CmdNVUndefineSpaceSpecial) function nvAuthCmd takes the session handle for the policy and the AuthValue (which can be emptyAuth) for the authorization. platformAuth takes either a sessionHandle for the platform policy or HandlePasswordSession and the platformAuth value for authorization.

func NVWrite

func NVWrite(rw io.ReadWriter, authHandle, nvIndex tpmutil.Handle, authString string, data tpmutil.U16Bytes, offset uint16) error

NVWrite writes data into the TPM's NV storage.

func NVWriteEx added in v0.3.1

func NVWriteEx(rw io.ReadWriter, authHandle, nvIndex tpmutil.Handle, authArea AuthCommand, data tpmutil.U16Bytes, offset uint16) error

NVWriteEx does the same as NVWrite with the exception of letting the user take care of the AuthCommand before calling the function. This allows more flexibility and does not limit the AuthCommand to PasswordSession.

func NVWriteLock added in v0.3.0

func NVWriteLock(rw io.ReadWriter, owner, handle tpmutil.Handle, authString string) error

NVWriteLock inhibits further writes on the given NV index if at least one of the AttrWriteSTClear or AttrWriteDefine bits is set.

AttrWriteSTClear causes the index to be locked until the TPM is restarted (see the Startup function).

AttrWriteDefine causes the index to be locked permanently if data has been written to the index; otherwise the lock is removed on startup.

NVWriteLock returns an error if neither bit is set.

It is not an error to call NVWriteLock for an index that is already locked for writing.

func OpenTPM

func OpenTPM(path string) (io.ReadWriteCloser, error)

OpenTPM opens a channel to the TPM at the given path. If the file is a device, then it treats it like a normal TPM device, and if the file is a Unix domain socket, then it opens a connection to the socket.

func PCREvent

func PCREvent(rw io.ReadWriter, pcr tpmutil.Handle, eventData []byte) error

PCREvent writes an update to the specified PCR.

func PCRExtend

func PCRExtend(rw io.ReadWriter, pcr tpmutil.Handle, hashAlg Algorithm, hash []byte, password string) error

PCRExtend extends a value into the selected PCR

func PolicyCommandCode added in v0.3.0

func PolicyCommandCode(rw io.ReadWriter, session tpmutil.Handle, cc tpmutil.Command) error

PolicyCommandCode indicates that the authorization will be limited to a specific command code

func PolicyGetDigest

func PolicyGetDigest(rw io.ReadWriter, handle tpmutil.Handle) ([]byte, error)

PolicyGetDigest returns the current policyDigest of the session.

func PolicyOr added in v0.3.0

func PolicyOr(rw io.ReadWriter, session tpmutil.Handle, digests TPMLDigest) error

PolicyOr compares PolicySession→Digest against the list of provided values. If the current Session→Digest does not match any value in the list, the TPM shall return TPM_RC_VALUE. Otherwise, the TPM will reset policySession→Digest to a Zero Digest. Then policySession→Digest is extended by the concatenation of TPM_CC_PolicyOR and the concatenation of all of the digests.

func PolicyPCR

func PolicyPCR(rw io.ReadWriter, session tpmutil.Handle, expectedDigest []byte, sel PCRSelection) error

PolicyPCR sets PCR state binding for authorization on a session.

expectedDigest is optional. When specified, it's compared against the digest of PCRs matched by sel.

Note that expectedDigest must be a *digest* of the expected PCR value. You must compute the digest manually. ReadPCR returns raw PCR values, not their digests. If you wish to select multiple PCRs, concatenate their values before computing the digest. See "TPM 2.0 Part 1, Selecting Multiple PCR".

func PolicyPassword

func PolicyPassword(rw io.ReadWriter, handle tpmutil.Handle) error

PolicyPassword sets password authorization requirement on the object.

func QuoteRaw added in v0.3.0

func QuoteRaw(rw io.ReadWriter, signingHandle tpmutil.Handle, parentPassword, ownerPassword string, toQuote []byte, sel PCRSelection, sigAlg Algorithm) ([]byte, []byte, error)

QuoteRaw is very similar to Quote, except that it will return the raw signature in a byte array without decoding.

func RSADecrypt added in v0.2.0

func RSADecrypt(rw io.ReadWriter, key tpmutil.Handle, password string, message []byte, scheme *AsymScheme, label string) ([]byte, error)

RSADecrypt performs RSA decryption in the TPM according to RFC 3447. The key must be a private RSA key in the TPM with FlagDecrypt set. Note that when using OAEP with a label, a null byte is appended to the label and the null byte is included in the padding scheme.

func RSAEncrypt added in v0.2.0

func RSAEncrypt(rw io.ReadWriter, key tpmutil.Handle, message []byte, scheme *AsymScheme, label string) ([]byte, error)

RSAEncrypt performs RSA encryption in the TPM according to RFC 3447. The key must be a (public) key loaded into the TPM beforehand. Note that when using OAEP with a label, a null byte is appended to the label and the null byte is included in the padding scheme.

func ReadClock

func ReadClock(rw io.ReadWriter) (uint64, uint64, error)

ReadClock returns current clock values from the TPM.

First return value is time in milliseconds since TPM was initialized (since system startup).

Second return value is time in milliseconds since TPM reset (since Storage Primary Seed is changed).

func ReadPCR

func ReadPCR(rw io.ReadWriter, pcr int, hashAlg Algorithm) ([]byte, error)

ReadPCR reads the value of the given PCR.

func ReadPCRs

func ReadPCRs(rw io.ReadWriter, sel PCRSelection) (map[int][]byte, error)

ReadPCRs reads PCR values from the TPM. This is only a wrapper over TPM2_PCR_Read() call, thus can only return at most 8 PCRs digests.

func Seal

func Seal(rw io.ReadWriter, parentHandle tpmutil.Handle, parentPassword, objectPassword string, objectAuthPolicy []byte, sensitiveData []byte) ([]byte, []byte, error)

Seal creates a data blob object that seals the sensitive data under a parent and with a password and auth policy. Access to the parent must be available with a simple password. Returns private and public portions of the created object.

func SequenceUpdate added in v0.3.2

func SequenceUpdate(rw io.ReadWriter, sequenceAuth string, seqHandle tpmutil.Handle, buffer []byte) error

SequenceUpdate is used to add data to a hash or HMAC sequence.

func Shutdown

func Shutdown(rw io.ReadWriter, typ StartupType) error

Shutdown shuts down a TPM (usually done by the OS).

func StartAuthSession

func StartAuthSession(rw io.ReadWriter, tpmKey, bindKey tpmutil.Handle, nonceCaller, secret []byte, se SessionType, sym, hashAlg Algorithm) (tpmutil.Handle, []byte, error)

StartAuthSession initializes a session object. Returns session handle and the initial nonce from the TPM.

func Startup

func Startup(rw io.ReadWriter, typ StartupType) error

Startup initializes a TPM (usually done by the OS).

func Unseal

func Unseal(rw io.ReadWriter, itemHandle tpmutil.Handle, password string) ([]byte, error)

Unseal returns the data for a loaded sealed object.

func UnsealWithSession

func UnsealWithSession(rw io.ReadWriter, sessionHandle, itemHandle tpmutil.Handle, password string) ([]byte, error)

UnsealWithSession returns the data for a loaded sealed object.

Types

type Algorithm

type Algorithm uint16

Algorithm represents a TPM_ALG_ID value.

const (
	AlgUnknown   Algorithm = 0x0000
	AlgRSA       Algorithm = 0x0001
	AlgSHA1      Algorithm = 0x0004
	AlgHMAC      Algorithm = 0x0005
	AlgAES       Algorithm = 0x0006
	AlgKeyedHash Algorithm = 0x0008
	AlgXOR       Algorithm = 0x000A
	AlgSHA256    Algorithm = 0x000B
	AlgSHA384    Algorithm = 0x000C
	AlgSHA512    Algorithm = 0x000D
	AlgNull      Algorithm = 0x0010
	AlgRSASSA    Algorithm = 0x0014
	AlgRSAES     Algorithm = 0x0015
	AlgRSAPSS    Algorithm = 0x0016
	AlgOAEP      Algorithm = 0x0017
	AlgECDSA     Algorithm = 0x0018
	AlgECDH      Algorithm = 0x0019
	AlgECDAA     Algorithm = 0x001A
	AlgKDF2      Algorithm = 0x0021
	AlgECC       Algorithm = 0x0023
	AlgSymCipher Algorithm = 0x0025
	AlgSHA3_256  Algorithm = 0x0027
	AlgSHA3_384  Algorithm = 0x0028
	AlgSHA3_512  Algorithm = 0x0029
	AlgCTR       Algorithm = 0x0040
	AlgOFB       Algorithm = 0x0041
	AlgCBC       Algorithm = 0x0042
	AlgCFB       Algorithm = 0x0043
	AlgECB       Algorithm = 0x0044
)

Supported Algorithms.

func HashToAlgorithm added in v0.3.2

func HashToAlgorithm(hash crypto.Hash) (Algorithm, error)

HashToAlgorithm looks up the TPM2 algorithm corresponding to the provided crypto.Hash

func (Algorithm) Hash added in v0.3.0

func (a Algorithm) Hash() (crypto.Hash, error)

Hash returns a crypto.Hash based on the given TPM_ALG_ID. An error is returned if the given algorithm is not a hash algorithm or is not available.

func (Algorithm) IsNull

func (a Algorithm) IsNull() bool

IsNull returns true if a is AlgNull or zero (unset).

func (Algorithm) UsesCount

func (a Algorithm) UsesCount() bool

UsesCount returns true if a signature algorithm uses count value.

func (Algorithm) UsesHash added in v0.2.0

func (a Algorithm) UsesHash() bool

UsesHash returns true if the algorithm requires the use of a hash.

type AlgorithmAttributes

type AlgorithmAttributes uint32

AlgorithmAttributes represents a TPMA_ALGORITHM value.

type AlgorithmDescription

type AlgorithmDescription struct {
	ID         Algorithm
	Attributes AlgorithmAttributes
}

AlgorithmDescription represents a TPMS_ALGORITHM_DESCRIPTION structure.

type AsymScheme added in v0.2.0

type AsymScheme struct {
	Alg  Algorithm
	Hash Algorithm
}

AsymScheme represents am asymmetric encryption scheme.

type AttestationData

type AttestationData struct {
	Magic                uint32
	Type                 tpmutil.Tag
	QualifiedSigner      Name
	ExtraData            tpmutil.U16Bytes
	ClockInfo            ClockInfo
	FirmwareVersion      uint64
	AttestedCertifyInfo  *CertifyInfo
	AttestedQuoteInfo    *QuoteInfo
	AttestedCreationInfo *CreationInfo
}

AttestationData contains data attested by TPM commands (like Certify).

func DecodeAttestationData

func DecodeAttestationData(in []byte) (*AttestationData, error)

DecodeAttestationData decode a TPMS_ATTEST message. No error is returned if the input has extra trailing data.

func (AttestationData) Encode

func (ad AttestationData) Encode() ([]byte, error)

Encode serializes an AttestationData structure in TPM wire format.

type AuthCommand

type AuthCommand struct {
	Session    tpmutil.Handle
	Nonce      tpmutil.U16Bytes
	Attributes SessionAttributes
	Auth       tpmutil.U16Bytes
}

AuthCommand represents a TPMS_AUTH_COMMAND. This structure encapsulates parameters which authorize the use of a given handle or parameter.

type Capability

type Capability uint32

Capability identifies some TPM property or state type.

const (
	CapabilityAlgs Capability = iota
	CapabilityHandles
	CapabilityCommands
	CapabilityPPCommands
	CapabilityAuditCommands
	CapabilityPCRs
	CapabilityTPMProperties
	CapabilityPCRProperties
	CapabilityECCCurves
	CapabilityAuthPolicies
)

TPM Capabilities.

type CertifyInfo

type CertifyInfo struct {
	Name          Name
	QualifiedName Name
}

CertifyInfo contains Certify-specific data for TPMS_ATTEST.

type ClockInfo

type ClockInfo struct {
	Clock        uint64
	ResetCount   uint32
	RestartCount uint32
	Safe         byte
}

ClockInfo contains TPM state info included in AttestationData.

type CreationData

type CreationData struct {
	PCRSelection        PCRSelection
	PCRDigest           tpmutil.U16Bytes
	Locality            byte
	ParentNameAlg       Algorithm
	ParentName          Name
	ParentQualifiedName Name
	OutsideInfo         tpmutil.U16Bytes
}

CreationData describes the attributes and environment for an object created on the TPM. This structure encodes/decodes to/from TPMS_CREATION_DATA.

func DecodeCreationData

func DecodeCreationData(buf []byte) (*CreationData, error)

DecodeCreationData decodes a TPMS_CREATION_DATA message. No error is returned if the input has extra trailing data.

type CreationInfo

type CreationInfo struct {
	Name Name
	// Most TPM2B_Digest structures contain a TPMU_HA structure
	// and get parsed to HashValue. This is never the case for the
	// digest in TPMS_CREATION_INFO.
	OpaqueDigest tpmutil.U16Bytes
}

CreationInfo contains Creation-specific data for TPMS_ATTEST.

type ECCParams

type ECCParams struct {
	Symmetric *SymScheme
	Sign      *SigScheme
	CurveID   EllipticCurve
	KDF       *KDFScheme
	Point     ECPoint
}

ECCParams represents parameters of an ECC key pair.

Symmetric, Sign and KDF may be nil, depending on key Attributes in Public.

type ECPoint

type ECPoint struct {
	XRaw, YRaw tpmutil.U16Bytes
}

ECPoint represents a ECC coordinates for a point using byte buffers.

func ECDHKeyGen added in v0.3.0

func ECDHKeyGen(rw io.ReadWriter, key tpmutil.Handle) (zPoint, pubPoint *ECPoint, err error)

ECDHKeyGen generates an ephemeral ECC key, calculates the ECDH point multiplcation of the ephemeral private key and a loaded public key, and returns the public ephemeral point along with the coordinates of the resulting point.

func ECDHZGen added in v0.3.0

func ECDHZGen(rw io.ReadWriter, key tpmutil.Handle, password string, inPoint ECPoint) (zPoint *ECPoint, err error)

ECDHZGen performs ECDH point multiplication between a private key held in the TPM and a given public point, returning the coordinates of the resulting point. The key must have FlagDecrypt set.

func (ECPoint) X

func (p ECPoint) X() *big.Int

X returns the X Point value reprsented by XRaw.

func (ECPoint) Y

func (p ECPoint) Y() *big.Int

Y returns the Y Point value reprsented by YRaw.

type EllipticCurve

type EllipticCurve uint16

EllipticCurve identifies specific EC curves.

type Error added in v0.1.1

type Error struct {
	Code RCFmt0
}

Error is returned for all Format 0 errors from the TPM. It is used for general errors not specific to a parameter, handle or session.

func (Error) Error added in v0.1.1

func (e Error) Error() string

type HandleError added in v0.1.1

type HandleError struct {
	Code   RCFmt1
	Handle RCIndex
}

HandleError describes an error related to a handle, and the handle number.

func (HandleError) Error added in v0.1.1

func (e HandleError) Error() string

type HandleType added in v0.1.1

type HandleType uint8

HandleType defines a type of handle.

const (
	HandleTypePCR           HandleType = 0x00
	HandleTypeNVIndex       HandleType = 0x01
	HandleTypeHMACSession   HandleType = 0x02
	HandleTypeLoadedSession HandleType = 0x02
	HandleTypePolicySession HandleType = 0x03
	HandleTypeSavedSession  HandleType = 0x03
	HandleTypePermanent     HandleType = 0x40
	HandleTypeTransient     HandleType = 0x80
	HandleTypePersistent    HandleType = 0x81
)

Supported handle types

type HashValue

type HashValue struct {
	Alg   Algorithm
	Value tpmutil.U16Bytes
}

HashValue is an algorithm-specific hash value.

func EventSequenceComplete added in v0.3.2

func EventSequenceComplete(rw io.ReadWriter, pcrAuth, sequenceAuth string, pcrHandle, seqHandle tpmutil.Handle, buffer []byte) (digests []*HashValue, err error)

EventSequenceComplete adds the last part of data, if any, to an Event Sequence and returns the result in a digest list. If pcrHandle references a PCR and not AlgNull, then the returned digest list is processed in the same manner as the digest list input parameter to PCRExtend() with the pcrHandle in each bank extended with the associated digest value.

func (HashValue) Encode

func (hv HashValue) Encode() ([]byte, error)

Encode represents the given hash value as a TPMT_HA structure.

type IDObject

type IDObject struct {
	IntegrityHMAC tpmutil.U16Bytes
	// EncIdentity is packed raw, as the bytes representing the size
	// of the credential value are present within the encrypted blob.
	EncIdentity tpmutil.RawBytes
}

IDObject represents an encrypted credential bound to a TPM object.

type KDFScheme

type KDFScheme struct {
	Alg  Algorithm
	Hash Algorithm
}

KDFScheme represents a KDF (Key Derivation Function) scheme.

type KeyProp

type KeyProp uint32

KeyProp is a bitmask used in Attributes field of key templates. Individual flags should be OR-ed to form a full mask.

const (
	FlagFixedTPM            KeyProp = 0x00000002
	FlagStClear             KeyProp = 0x00000004
	FlagFixedParent         KeyProp = 0x00000010
	FlagSensitiveDataOrigin KeyProp = 0x00000020
	FlagUserWithAuth        KeyProp = 0x00000040
	FlagAdminWithPolicy     KeyProp = 0x00000080
	FlagNoDA                KeyProp = 0x00000400
	FlagRestricted          KeyProp = 0x00010000
	FlagDecrypt             KeyProp = 0x00020000
	FlagSign                KeyProp = 0x00040000

	FlagSealDefault   = FlagFixedTPM | FlagFixedParent
	FlagSignerDefault = FlagSign | FlagRestricted | FlagFixedTPM |
		FlagFixedParent | FlagSensitiveDataOrigin | FlagUserWithAuth
	FlagStorageDefault = FlagDecrypt | FlagRestricted | FlagFixedTPM |
		FlagFixedParent | FlagSensitiveDataOrigin | FlagUserWithAuth
)

Key properties.

type KeyedHashParams added in v0.2.0

type KeyedHashParams struct {
	Alg    Algorithm
	Hash   Algorithm
	KDF    Algorithm
	Unique tpmutil.U16Bytes
}

KeyedHashParams represents parameters of a keyed hash TPM object.

type NVAttr added in v0.1.0

type NVAttr uint32

NVAttr is a bitmask used in Attributes field of NV indexes. Individual flags should be OR-ed to form a full mask.

const (
	AttrPPWrite        NVAttr = 0x00000001
	AttrOwnerWrite     NVAttr = 0x00000002
	AttrAuthWrite      NVAttr = 0x00000004
	AttrPolicyWrite    NVAttr = 0x00000008
	AttrPolicyDelete   NVAttr = 0x00000400
	AttrWriteLocked    NVAttr = 0x00000800
	AttrWriteAll       NVAttr = 0x00001000
	AttrWriteDefine    NVAttr = 0x00002000
	AttrWriteSTClear   NVAttr = 0x00004000
	AttrGlobalLock     NVAttr = 0x00008000
	AttrPPRead         NVAttr = 0x00010000
	AttrOwnerRead      NVAttr = 0x00020000
	AttrAuthRead       NVAttr = 0x00040000
	AttrPolicyRead     NVAttr = 0x00080000
	AttrNoDA           NVAttr = 0x02000000
	AttrOrderly        NVAttr = 0x04000000
	AttrClearSTClear   NVAttr = 0x08000000
	AttrReadLocked     NVAttr = 0x10000000
	AttrWritten        NVAttr = 0x20000000
	AttrPlatformCreate NVAttr = 0x40000000
	AttrReadSTClear    NVAttr = 0x80000000
)

NV Attributes

func (NVAttr) String added in v0.3.0

func (p NVAttr) String() string

String returns a textual representation of the set of NVAttr

type NVPublic

type NVPublic struct {
	NVIndex    tpmutil.Handle
	NameAlg    Algorithm
	Attributes NVAttr
	AuthPolicy tpmutil.U16Bytes
	DataSize   uint16
}

NVPublic contains the public area of an NV index.

func NVReadPublic added in v0.1.0

func NVReadPublic(rw io.ReadWriter, index tpmutil.Handle) (NVPublic, error)

NVReadPublic reads the public data of an NV index.

type Name

type Name struct {
	Handle *tpmutil.Handle
	Digest *HashValue
}

Name represents a TPM2B_NAME, a name for TPM entities. Only one of Handle or Digest should be set.

func DecodeName added in v0.2.0

func DecodeName(in *bytes.Buffer) (*Name, error)

DecodeName deserializes a Name hash from the TPM wire format.

func (Name) Encode added in v0.2.0

func (n Name) Encode() ([]byte, error)

Encode serializes a Name hash into the TPM wire format.

func (Name) MatchesPublic

func (n Name) MatchesPublic(p Public) (bool, error)

MatchesPublic compares Digest in Name against given Public structure. Note: this only works for regular Names, not Qualified Names.

type PCRSelection

type PCRSelection struct {
	Hash Algorithm
	PCRs []int
}

PCRSelection contains a slice of PCR indexes and a hash algorithm used in them.

type ParameterError added in v0.1.1

type ParameterError struct {
	Code      RCFmt1
	Parameter RCIndex
}

ParameterError describes an error related to a parameter, and the parameter number.

func (ParameterError) Error added in v0.1.1

func (e ParameterError) Error() string

type Private

type Private struct {
	Type      Algorithm
	AuthValue tpmutil.U16Bytes
	SeedValue tpmutil.U16Bytes
	Sensitive tpmutil.U16Bytes
}

Private contains private section of a TPM key.

func (Private) Encode

func (p Private) Encode() ([]byte, error)

Encode serializes a Private structure in TPM wire format.

type Public

type Public struct {
	Type       Algorithm
	NameAlg    Algorithm
	Attributes KeyProp
	AuthPolicy tpmutil.U16Bytes

	// Exactly one of the following fields should be set
	// When encoding/decoding, one will be picked based on Type.
	RSAParameters       *RSAParams
	ECCParameters       *ECCParams
	SymCipherParameters *SymCipherParams
	KeyedHashParameters *KeyedHashParams
}

Public contains the public area of an object.

func DecodePublic

func DecodePublic(buf []byte) (Public, error)

DecodePublic decodes a TPMT_PUBLIC message. No error is returned if the input has extra trailing data.

func ReadPublic

func ReadPublic(rw io.ReadWriter, handle tpmutil.Handle) (Public, []byte, []byte, error)

ReadPublic reads the public part of the object under handle. Returns the public data, name and qualified name.

func (Public) Encode

func (p Public) Encode() ([]byte, error)

Encode serializes a Public structure in TPM wire format.

func (Public) Key added in v0.2.0

func (p Public) Key() (crypto.PublicKey, error)

Key returns the (public) key from the public area of an object.

func (Public) MatchesTemplate added in v0.2.0

func (p Public) MatchesTemplate(template Public) bool

MatchesTemplate checks if the Public area has the same algorithms and parameters as the provided template. Note that this does not necessarily mean that the key was created from this template, as the Unique field is both provided in the template and overriden in the key creation process.

func (Public) Name added in v0.2.0

func (p Public) Name() (Name, error)

Name computes the Digest-based Name from the public area of an object.

type QuoteInfo

type QuoteInfo struct {
	PCRSelection PCRSelection
	PCRDigest    tpmutil.U16Bytes
}

QuoteInfo represents a TPMS_QUOTE_INFO structure.

type RCFmt0 added in v0.1.1

type RCFmt0 uint8

RCFmt0 holds Format 0 error codes

type RCFmt1 added in v0.1.1

type RCFmt1 uint8

RCFmt1 holds Format 1 error codes

type RCIndex added in v0.1.1

type RCIndex uint8

RCIndex is used to reference arguments, handles and sessions in errors

const (
	RC1 RCIndex = iota + 1
	RC2
	RC3
	RC4
	RC5
	RC6
	RC7
	RC8
	RC9
	RCA
	RCB
	RCC
	RCD
	RCE
	RCF
)

Indexes for arguments, handles and sessions.

type RCWarn added in v0.1.1

type RCWarn uint8

RCWarn holds error codes used in warnings

type RSAParams

type RSAParams struct {
	Symmetric   *SymScheme
	Sign        *SigScheme
	KeyBits     uint16
	ExponentRaw uint32
	ModulusRaw  tpmutil.U16Bytes
}

RSAParams represents parameters of an RSA key pair.

Symmetric and Sign may be nil, depending on key Attributes in Public.

ExponentRaw and ModulusRaw are the actual data encoded in the template, which is useful for templates that differ in zero-padding, for example.

func (*RSAParams) Exponent

func (p *RSAParams) Exponent() uint32

Exponent returns the RSA exponent value represented by ExponentRaw, handling the fact that an exponent of 0 represents a value of 65537 (2^16 + 1).

func (*RSAParams) Modulus

func (p *RSAParams) Modulus() *big.Int

Modulus returns the RSA modulus value represented by ModulusRaw, handling the fact that the same modulus value can have multiple different representations.

type SessionAttributes

type SessionAttributes byte

SessionAttributes represents an attribute of a session.

const (
	AttrContinueSession SessionAttributes = 1 << iota
	AttrAuditExclusive
	AttrAuditReset

	AttrDecrypt
	AttrEcrypt
	AttrAudit
)

Session Attributes (Structures 8.4 TPMA_SESSION)

type SessionError added in v0.1.1

type SessionError struct {
	Code    RCFmt1
	Session RCIndex
}

SessionError describes an error related to a session, and the session number.

func (SessionError) Error added in v0.1.1

func (e SessionError) Error() string

type SessionType

type SessionType uint8

SessionType defines the type of session created in StartAuthSession.

const (
	SessionHMAC   SessionType = 0x00
	SessionPolicy SessionType = 0x01
	SessionTrial  SessionType = 0x03
)

Supported session types.

type SigScheme

type SigScheme struct {
	Alg   Algorithm
	Hash  Algorithm
	Count uint32
}

SigScheme represents a signing scheme.

type Signature

type Signature struct {
	Alg Algorithm
	RSA *SignatureRSA
	ECC *SignatureECC
}

Signature combines all possible signatures from RSA and ECC keys. Only one of RSA or ECC will be populated.

func DecodeSignature added in v0.2.0

func DecodeSignature(in *bytes.Buffer) (*Signature, error)

DecodeSignature decodes a serialized TPMT_SIGNATURE structure.

func Quote

func Quote(rw io.ReadWriter, signingHandle tpmutil.Handle, parentPassword, ownerPassword string, toQuote []byte, sel PCRSelection, sigAlg Algorithm) ([]byte, *Signature, error)

Quote returns a quote of PCR values. A quote is a signature of the PCR values, created using a signing TPM key.

Returns attestation data and the decoded signature.

func Sign

func Sign(rw io.ReadWriter, key tpmutil.Handle, password string, digest []byte, validation *Ticket, sigScheme *SigScheme) (*Signature, error)

Sign computes a signature for digest using a given loaded key. Signature algorithm depends on the key type. If 'key' references a Restricted Decryption key, 'validation' must be a valid hash verification ticket from the TPM, which can be obtained by using Hash() to hash the data with the TPM. If 'validation' is nil, a NULL ticket is passed to TPM2_Sign.

func SignWithSession added in v0.3.0

func SignWithSession(rw io.ReadWriter, sessionHandle, key tpmutil.Handle, password string, digest []byte, validation *Ticket, sigScheme *SigScheme) (*Signature, error)

SignWithSession computes a signature for digest using a given loaded key. Signature algorithm depends on the key type. Used for keys with non-password authorization policies. If 'key' references a Restricted Decryption key, 'validation' must be a valid hash verification ticket from the TPM, which can be obtained by using Hash() to hash the data with the TPM. If 'validation' is nil, a NULL ticket is passed to TPM2_Sign.

type SignatureECC

type SignatureECC struct {
	HashAlg Algorithm
	R       *big.Int
	S       *big.Int
}

SignatureECC is an ECC-specific signature value.

type SignatureRSA

type SignatureRSA struct {
	HashAlg   Algorithm
	Signature tpmutil.U16Bytes
}

SignatureRSA is an RSA-specific signature value.

type StartupType

type StartupType uint16

StartupType instructs the TPM on how to handle its state during Shutdown or Startup.

const (
	StartupClear StartupType = iota
	StartupState
)

Startup types

type SymCipherParams added in v0.2.0

type SymCipherParams struct {
	Symmetric *SymScheme
	Unique    tpmutil.U16Bytes
}

SymCipherParams represents parameters of a symmetric block cipher TPM object.

type SymScheme

type SymScheme struct {
	Alg     Algorithm
	KeyBits uint16
	Mode    Algorithm
}

SymScheme represents a symmetric encryption scheme. Known in the specification by TPMT_SYM_DEF_OBJECT.

type TPMLDigest added in v0.3.0

type TPMLDigest struct {
	Digests []tpmutil.U16Bytes
}

TPMLDigest represents the TPML_Digest structure It is used to convey a list of digest values. This type is used in TPM2_PolicyOR() and in TPM2_PCR_Read()

func DecodeTPMLDigest added in v0.3.1

func DecodeTPMLDigest(buf []byte) (*TPMLDigest, error)

DecodeTPMLDigest decodes a TPML_Digest part of a message.

func (*TPMLDigest) Encode added in v0.3.1

func (list *TPMLDigest) Encode() ([]byte, error)

Encode converts the TPMLDigest structure into a byte slice

type TPMProp

type TPMProp uint32

TPMProp represents a Property Tag (TPM_PT) used with calls to GetCapability(CapabilityTPMProperties).

const (
	FamilyIndicator TPMProp = 0x100 + iota
	SpecLevel
	SpecRevision
	SpecDayOfYear
	SpecYear
	Manufacturer
	VendorString1
	VendorString2
	VendorString3
	VendorString4
	VendorTPMType
	FirmwareVersion1
	FirmwareVersion2
	InputMaxBufferSize
	TransientObjectsMin
	PersistentObjectsMin
	LoadedObjectsMin
	ActiveSessionsMax
	PCRCount
	PCRSelectMin
	ContextGapMax

	NVCountersMax
	NVIndexMax
	MemoryMethod
	ClockUpdate
	ContextHash
	ContextSym
	ContextSymSize
	OrderlyCount
	CommandMaxSize
	ResponseMaxSize
	DigestMaxSize
	ObjectContextMaxSize
	SessionContextMaxSize
	PSFamilyIndicator
	PSSpecLevel
	PSSpecRevision
	PSSpecDayOfYear
	PSSpecYear
	SplitSigningMax
	TotalCommands
	LibraryCommands
	VendorCommands
	NVMaxBufferSize
	TPMModes
	CapabilityMaxBufferSize
)

TPM Capability Properties, see TPM 2.0 Spec, Rev 1.38, Table 23. Fixed TPM Properties (PT_FIXED)

const (
	TPMAPermanent TPMProp = 0x200 + iota
	TPMAStartupClear
	HRNVIndex
	HRLoaded
	HRLoadedAvail
	HRActive
	HRActiveAvail
	HRTransientAvail
	CurrentPersistent
	AvailPersistent
	NVCounters
	NVCountersAvail
	AlgorithmSet
	LoadedCurves
	LockoutCounter
	MaxAuthFail
	LockoutInterval
	LockoutRecovery
	NVWriteRecovery
	AuditCounter0
	AuditCounter1
)

Variable TPM Properties (PT_VAR)

const (
	PCRFirst           TPMProp = 0x00000000
	HMACSessionFirst   TPMProp = 0x02000000
	LoadedSessionFirst TPMProp = 0x02000000
	PolicySessionFirst TPMProp = 0x03000000
	ActiveSessionFirst TPMProp = 0x03000000
	TransientFirst     TPMProp = 0x80000000
	PersistentFirst    TPMProp = 0x81000000
	PersistentLast     TPMProp = 0x81FFFFFF
	PlatformPersistent TPMProp = 0x81800000
	NVIndexFirst       TPMProp = 0x01000000
	NVIndexLast        TPMProp = 0x01FFFFFF
	PermanentFirst     TPMProp = 0x40000000
	PermanentLast      TPMProp = 0x4000010F
)

Allowed ranges of different kinds of Handles (TPM_HANDLE) These constants have type TPMProp for backwards compatibility.

type TaggedProperty

type TaggedProperty struct {
	Tag   TPMProp
	Value uint32
}

TaggedProperty represents a TPMS_TAGGED_PROPERTY structure.

type Ticket

type Ticket struct {
	Type      tpmutil.Tag
	Hierarchy tpmutil.Handle
	Digest    tpmutil.U16Bytes
}

Ticket represents evidence the TPM previously processed information.

func CreateKey

func CreateKey(rw io.ReadWriter, owner tpmutil.Handle, sel PCRSelection, parentPassword, ownerPassword string, pub Public) (private, public, creationData, creationHash []byte, creationTicket Ticket, err error)

CreateKey creates a new key pair under the owner handle. Returns private key and public key blobs as well as the creation data, a hash of said data and the creation ticket.

func CreateKeyUsingAuth added in v0.2.0

func CreateKeyUsingAuth(rw io.ReadWriter, owner tpmutil.Handle, sel PCRSelection, auth AuthCommand, ownerPassword string, pub Public) (private, public, creationData, creationHash []byte, creationTicket Ticket, err error)

CreateKeyUsingAuth creates a new key pair under the owner handle using the provided AuthCommand. Returns private key and public key blobs as well as the creation data, a hash of said data, and the creation ticket.

func CreateKeyWithSensitive added in v0.3.0

func CreateKeyWithSensitive(rw io.ReadWriter, owner tpmutil.Handle, sel PCRSelection, parentPassword, ownerPassword string, pub Public, sensitive []byte) (private, public, creationData, creationHash []byte, creationTicket Ticket, err error)

CreateKeyWithSensitive is very similar to CreateKey, except that it can take in a piece of sensitive data.

func CreatePrimaryEx

func CreatePrimaryEx(rw io.ReadWriter, owner tpmutil.Handle, sel PCRSelection, parentPassword, ownerPassword string, pub Public) (keyHandle tpmutil.Handle, public, creationData, creationHash []byte, ticket Ticket, creationName []byte, err error)

CreatePrimaryEx initializes the primary key in a given hierarchy. This function differs from CreatePrimary in that all response elements are returned, and they are returned in relatively raw form.

func Hash

func Hash(rw io.ReadWriter, alg Algorithm, buf tpmutil.U16Bytes, hierarchy tpmutil.Handle) (digest []byte, validation *Ticket, err error)

Hash computes a hash of data in buf using TPM2_Hash, returning the computed digest and validation ticket. The validation ticket serves as confirmation from the TPM that the data in buf did not begin with TPM_GENERATED_VALUE. NOTE: TPM2_Hash can only accept data up to MAX_DIGEST_BUFFER in size, which is implementation-dependent, but guaranteed to be at least 1024 octets.

func PolicySecret

func PolicySecret(rw io.ReadWriter, entityHandle tpmutil.Handle, entityAuth AuthCommand, policyHandle tpmutil.Handle, policyNonce, cpHash, policyRef []byte, expiry int32) (*Ticket, error)

PolicySecret sets a secret authorization requirement on the provided entity. If expiry is non-zero, the authorization is valid for expiry seconds.

func SequenceComplete added in v0.3.2

func SequenceComplete(rw io.ReadWriter, sequenceAuth string, seqHandle, hierarchy tpmutil.Handle, buffer []byte) (digest []byte, validation *Ticket, err error)

SequenceComplete adds the last part of data, if any, to a hash/HMAC sequence and returns the result.

type VendorError added in v0.1.1

type VendorError struct {
	Code uint32
}

VendorError represents a vendor-specific error response. These types of responses are not decoded and Code contains the complete response code.

func (VendorError) Error added in v0.1.1

func (e VendorError) Error() string

type Warning added in v0.1.1

type Warning struct {
	Code RCWarn
}

Warning is typically used to report transient errors.

func (Warning) Error added in v0.1.1

func (w Warning) Error() string

Directories

Path Synopsis
Package credactivation implements generation of data blobs to be used when invoking the ActivateCredential command, on a TPM.
Package credactivation implements generation of data blobs to be used when invoking the ActivateCredential command, on a TPM.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL