testutil

package
v1.6.2 Latest Latest
Warning

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

 Go to latest Published: Apr 10, 2024 License: LGPL-3.0 Imports: 27 Imported by: 2

Documentation

Overview

Package testutil contains utilities for writing unit tests using go-tpm2.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// TPMBackend defines the type of TPM connection that should be used for tests.
	TPMBackend TPMBackendType = TPMBackendNone

	// PermittedTPMFeatures defines the permitted feature set for tests that use a TPMContext
	// and where TPMBackend is not TPMBackendMssim. Tests that require features that aren't
	// permitted should be skipped. This is to facilitate testing on real TPM devices where it
	// might not be desirable to perform certain actions.
	PermittedTPMFeatures TPMFeatureFlags

	// TPMDevicePath defines the path of the TPM character device where TPMBackend is TPMBackendDevice.
	TPMDevicePath string = "/dev/tpm0"

	// MssimPort defines the port number of the TPM simulator command port where TPMBackend is TPMBackendMssim.
	MssimPort uint = 2321

	ErrSkipNoTPM = errors.New("no TPM configured for the test")
)
View Source 
var TPMValueDeepEquals Checker = &tpmValueDeepEqualsChecker{
	&CheckerInfo{Name: "TPMValueDeepEquals", Params: []string{"obtained", "expected"}}}

TPMValueDeepEquals checks that the obtained TPM value is deeply equal to the expected TPM value. This works by first checking that both values have the same type, and then serializing them both to the TPM wire format and checking that they are bit-for-bit identical. Both values need to be valid TPM types for this to work, and they need to be representable by the TPM wire format.

For example: 

 expected := &tpm2.NVPublic{
	Index: 0x0180000,
	NameAlg: tpm2.HashAlgorithmSHA256,
	Attrs: tpm2.NVTypeOrdinary.WithAttrs(tpm2.AttrNVAuthWrite|tpm2.AttrNVAuthRead|tpm2.AttrNVWritten),
	Size: 8}
 c.Check(public, TPMValueDeepEquals, expected)

Functions

func AddCommandLineFlags 

func AddCommandLineFlags()

AddCommandLineFlags adds various command line flags to the current executable, which can be used for setting test parameters. This should be called from inside of the init function for a package.

func ClearTPMUsingPlatformHierarchyT 

func ClearTPMUsingPlatformHierarchyT(t *testing.T, tpm *tpm2.TPMContext)

ClearTPMUsingPlatformHierarchyT enables the TPM2_Clear command and then clears the TPM using the platform hierarchy.

func LaunchTPMSimulator 

func LaunchTPMSimulator(opts *TPMSimulatorOptions) (stop func(), err error)

LaunchTPMSimulator launches a TPM simulator with the TCP command channel listening on opts.Port. The platform channel will listen on opts.Port + 1. If opts.Port is zero, then the value of MssimPort is used.

If opts.SourcePath and opts.WorkDir are empty, the simulator will run with ephemeral storage if this is supported. When not using ephemeral storage, a temporary working directory is created in XDG_RUNTIME_DIR. The location of the temporary working directory can be overridden with opts.WorkDir.

If opts.SourcePath is not empty, the file at the specified path will be copied to the working directory and used as the persistent NV storage. If opts.SavePersistent is also true, the updated persistent storage will be copied back to opts.SourcePath on exit. This is useful for generating test data that needs to be checked into a repository. If opts.SavePersistent is true then the file at opts.SourcePath doesn't need to exist.

The temporary working directory is cleaned up on exit, unless opts.KeepWorkDir is set.

On success, it returns a function that can be used to stop the simulator and clean up its temporary directory.

func NewDevice added in v1.4.0 

func NewDevice(c *C, features TPMFeatureFlags) tpm2.TPMDevice

NewDevice returns a new tpm2.TPMDevice for testing, for integration with test suites that might have a custom way to create a TPMContext. If TPMBackend is TPMBackendNone then the returned device will return ErrSkipNoTPM instead of a transport. If TPMBackend is TPMBackendMssim, the returned device will wrap a *mssim.Device for the TPM simulator on the port specified by the MssimPort variable. If TPMBackend is TPMBackendDevice, the returned device will wrap a *linux.RawDevice for the character device at the path specified by the TPMDevicePath variable if the requested features are permitted, as defined by the PermittedTPMFeatures variable. If the test requires features that are not permitted, then the device will return ErrSkipNoTPM instead of a transport.

func NewDeviceT added in v1.4.0 

func NewDeviceT(t *testing.T, features TPMFeatureFlags) tpm2.TPMDevice

NewDeviceT returns a new tpm2.TPMDevice for testing, for integration with test suites that might have a custom way to create a TPMContext. If TPMBackend is TPMBackendNone then the returned device will return ErrSkipNoTPM instead of a transport. If TPMBackend is TPMBackendMssim, the returned device will wrap a *mssim.Device for the TPM simulator on the port specified by the MssimPort variable. If TPMBackend is TPMBackendDevice, the returned device will wrap a *linux.RawDevice for the character device at the path specified by the TPMDevicePath variable if the requested features are permitted, as defined by the PermittedTPMFeatures variable. If the test requires features that are not permitted, then the device will return ErrSkipNoTPM instead of a transport.

func NewECCKeyTemplate 

func NewECCKeyTemplate(usage objectutil.Usage, scheme *tpm2.ECCScheme) *tpm2.Public

NewECCKeyTemplate is a wrapper around objectutil.NewECCKeyTemplate that defines the noDA attribute.

func NewECCStorageKeyTemplate 

func NewECCStorageKeyTemplate() *tpm2.Public

NewECCStorageKeyTemplate is a wrapper around objectutil.NewECCStorageKeyTemplate that defines the noDA attribute.

func NewExternalHMACKey 

func NewExternalHMACKey(authValue tpm2.Auth, key []byte) (*tpm2.Public, *tpm2.Sensitive)

NewExternalHMACKey is a wrapper around objectutil.NewHMACKey that sets the noDA attribute.

func NewExternalRSAStoragePublicKey 

func NewExternalRSAStoragePublicKey(key *rsa.PublicKey) *tpm2.Public

NewExternalRSAStoragePublicKey creates the public area for a RSA storage key from the supplied key.

func NewExternalSealedObject 

func NewExternalSealedObject(authValue tpm2.Auth, data []byte) (*tpm2.Public, *tpm2.Sensitive)

NewExternalSealedObject is a wrapper around objectutil.NewSealedObject that sets the noDA attribute.

func NewRSAKeyTemplate 

func NewRSAKeyTemplate(usage objectutil.Usage, scheme *tpm2.RSAScheme) *tpm2.Public

NewRSAKeyTemplate is a wrapper around objectutil.NewRSAKeyTemplate that defines the noDA attribute.

func NewRSAStorageKeyTemplate 

func NewRSAStorageKeyTemplate() *tpm2.Public

NewRSAStorageKeyTemplate is a wrapper around objectutil.NewRSAStorageKeyTemplate that defines the noDA attribute.

func NewRestrictedECCSigningKeyTemplate 

func NewRestrictedECCSigningKeyTemplate(scheme *tpm2.ECCScheme) *tpm2.Public

NewRestrictedECCSigningKeyTemplate is a wrapper around objectutil.NewECCAttestationKeyTemplate that defines the noDA attribute.

func NewRestrictedRSASigningKeyTemplate 

func NewRestrictedRSASigningKeyTemplate(scheme *tpm2.RSAScheme) *tpm2.Public

NewRestrictedRSASigningKeyTemplate is a wrapper around objectutil.NewRSAAttestationKeyTemplate that defines the noDA attribute.

func NewSealedObjectTemplate 

func NewSealedObjectTemplate() *tpm2.Public

NewSealedObject is a wrapper around objectutil.NewSealedObjectTemplate that defines the noDA attribute.

func NewSimulatorDevice added in v1.4.0 

func NewSimulatorDevice() tpm2.TPMDevice

NewSimulatorDevice returns a new tpm2.TPMDevice that wraps a *mssim.Device for the TPM simulator on the port specified by the MssimPort variable. If TPMBackedn is not TPMBackendMssim, then the device will return ErrSkipNoTPM instead of a transport.

func PrivateToSensitive added in v1.0.0 

func PrivateToSensitive(private tpm2.Private, name tpm2.Name, hashAlg tpm2.HashAlgorithmId, symmetricAlg *tpm2.SymDefObject, seed []byte) (sensitive *tpm2.Sensitive, err error)

PrivateToSensitive unwraps a TPM private area into its corresponding sensitive structure. The supplied name is the name of the object associated with sensitive.

The removes the outer wrapper from the private area using the specified digest algorithm, symmetric algorithm and seed. These values are associated with the parent storage key that that is used to load the object into the TPM. The seed is part of the parent storage key's sensitive area and will only be known for objects created outside of the TPM and then imported, or objects created inside of the TPM that can be duplicated and unwrapped outside of the TPM.

func ProduceOuterWrap added in v1.0.0 

func ProduceOuterWrap(hashAlg tpm2.HashAlgorithmId, symmetricAlg *tpm2.SymDefObject, name tpm2.Name, seed []byte, useIV bool, data []byte) ([]byte, error)

ProduceOuterWrap adds an outer wrapper to the supplied data. The supplied name is associated with the data.

It encrypts the data using the specified symmetric algorithm and a key derived from the supplied seed and name.

It then prepends an integrity HMAC of the encrypted data and the supplied name using the specified digest algorithm and a key derived from the supplied seed.

func ResetTPMSimulatorT 

func ResetTPMSimulatorT(t *testing.T, tpm *tpm2.TPMContext, transport *Transport)

ResetTPMSimulatorT issues a Shutdown -> Reset -> Startup cycle of the TPM simulator.

func SensitiveToPrivate added in v1.0.0 

func SensitiveToPrivate(sensitive *tpm2.Sensitive, name tpm2.Name, hashAlg tpm2.HashAlgorithmId, symmetricAlg *tpm2.SymDefObject, seed []byte) (tpm2.Private, error)

SensitiveToPrivate creates a TPM private area from the supplied sensitive structure. The supplied name is the name of the object associated with sensitive.

This applies an outer wrapper to the sensitive structure using the specified digest algorithm, symmetric algorithm and seed. These values are associated with the parent storage key that that will be used to load the object into the TPM. The seed is part of the parent storage key's sensitive area and will only be known for objects created outside of the TPM and then imported, or objects created inside of the TPM that can be duplicated and unwrapped outside of the TPM.

func UnwrapOuter added in v1.0.0 

func UnwrapOuter(hashAlg tpm2.HashAlgorithmId, symmetricAlg *tpm2.SymDefObject, name tpm2.Name, seed []byte, useIV bool, data []byte) ([]byte, error)

UnwrapOuter removes an outer wrapper from the supplied sensitive data blob. The supplied name is associated with the data.

It checks the integrity HMAC is valid using the specified digest algorithm and a key derived from the supplied seed and returns an error if the check fails.

It then decrypts the data blob using the specified symmetric algorithm and a key derived from the supplied seed and name.

func WrapDevice added in v1.4.0 

func WrapDevice(device tpm2.TPMDevice, features TPMFeatureFlags) tpm2.TPMDevice

WrapDevice wraps the supplied device so that transports created by it are wrapped by WrapTransport and authorized to use the specified features. If the test requires features that are not permitted, as defined by the PermittedTPMFeatures variable, the wrapped device will return ErrSkipNoTPM instead of a transport.

Types

type BaseTest 

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

BaseTest is a base test suite for all tests. It has the ability to run callbacks to perform cleanup actions at the end of each test.

func (*BaseTest) AddCleanup 

func (b *BaseTest) AddCleanup(fn func())

AddCleanup queues a function to be called at the end of the test.

func (*BaseTest) AddFixtureCleanup 

func (b *BaseTest) AddFixtureCleanup(fn func(c *C))

AddFixtureCleanup queues a function to be called at the end of the test, and is intended to be called during SetUpTest. The function is called with the TearDownTest *check.C which allows failures to result in a fixture panic, as failures recorded to the originating *check.C are ignored at this stage.

func (*BaseTest) InitCleanup 

func (b *BaseTest) InitCleanup(c *C)

InitCleanup should be called before any call to AddCleanup or AddFixtureCleanup. It is called by SetUpTest, but can be called prior to this, If InitCleanup is called for the first time in a test after a cleanup handler has already been registered, it will assert. This is to detect a missing call to TearDownTest, which might happen because the fixture decides a test should be skipped after registering a cleanup handler.

InitCleanup can be called multiple times in the same test.

func (*BaseTest) SetUpTest 

func (b *BaseTest) SetUpTest(c *C)

func (*BaseTest) TearDownTest 

func (b *BaseTest) TearDownTest(c *C)

type CommandRecord 

type CommandRecord struct {
	CmdCode     tpm2.CommandCode
	CmdHandles  tpm2.HandleList
	CmdAuthArea []tpm2.AuthCommand
	CpBytes     []byte

	RspCode     tpm2.ResponseCode
	RspHandle   tpm2.Handle // Will be tpm2.HandleUnassigned if no handle was returned
	RpBytes     []byte
	RspAuthArea []tpm2.AuthResponse
}

CommandRecord provides information about a command executed via the Transport interface.

func (*CommandRecord) GetCommandCode deprecated 

func (r *CommandRecord) GetCommandCode() (tpm2.CommandCode, error)

GetCommandCode returns the command code associated with this record.

Deprecated: use the CmdCode field.

func (*CommandRecord) UnmarshalCommand deprecated 

func (r *CommandRecord) UnmarshalCommand() (handles tpm2.HandleList, authArea []tpm2.AuthCommand, parameters []byte, err error)

UnmarshalCommand unmarshals the command packet associated with this record, returning the handles, auth area and parameters. The parameters will still be in the TPM wire format.

Deprecated: use the CmdHandles, CmdAuthArea and CpBytes fields.

func (*CommandRecord) UnmarshalResponse deprecated 

func (r *CommandRecord) UnmarshalResponse() (rc tpm2.ResponseCode, handle tpm2.Handle, parameters []byte, authArea []tpm2.AuthResponse, err error)

UnmarshalResponse unmarshals the response packet associated with this record, returning the response code, handle, parameters and auth area. The parameters will still be in the TPM wire format. For commands that don't respond with a handle, the returned handle will be tpm2.HandleUnassigned.

Deprecated: use the RspCode, RspHandle, RpBytes and RspAuthArea fields.

type CommandRecordC 

type CommandRecordC struct {
	*CommandRecord
}

CommandRecordC is a helper for CommandRecord that integrates with *check.C.

func (*CommandRecordC) GetCommandCode deprecated 

func (r *CommandRecordC) GetCommandCode(c *C) tpm2.CommandCode

Deprecated: use CommandRecord.CmdCode.

func (*CommandRecordC) UnmarshalCommand deprecated 

func (r *CommandRecordC) UnmarshalCommand(c *C) (handles tpm2.HandleList, authArea []tpm2.AuthCommand, parameters []byte)

Deprecated: use CommandRecord.CmdHandles, CommandRecord.CmdAuthArea and CommandRecord.CpBytes.

func (*CommandRecordC) UnmarshalResponse deprecated 

func (r *CommandRecordC) UnmarshalResponse(c *C) (rc tpm2.ResponseCode, handle tpm2.Handle, parameters []byte, authArea []tpm2.AuthResponse)

Deprecated: use CommandRecord.RspCode, CommandRecord.RspHandle, CommandRecord.RpBytes and CommandRecord.RspAuthArea.

type TCTI deprecated 

type TCTI = Transport

TCTI is a special proxy inteface used for testing, which wraps a real interface. It tracks changes to the TPM state and restores it when the connection is closed, and also performs some permission checks to ensure that a test does not access functionality that it has not declared as permitted.

Deprecated: Use Transport.

type TCTIWrapper deprecated 

type TCTIWrapper = TransportWrapper

Deprecated: use TransportWrapper.

type TPMBackendType 

type TPMBackendType int
const (
	TPMBackendNone TPMBackendType = iota
	TPMBackendDevice
	TPMBackendMssim
)

type TPMFeatureFlags 

type TPMFeatureFlags uint32

TPMFeatureFlags indicates the TPM features required by a test. It allows the test runner to restrict the features available to tests to make the tests more friendly with real TPM devices. 

const (
	// TPMFeatureOwnerHierarchy indicates that the test requires the use of the storage hierarchy. The
	// authorization value should be empty at the start of the test.
	TPMFeatureOwnerHierarchy TPMFeatureFlags = (1 << iota)

	// TPMFeatureEndorsementHierarchy indicates that the test requires the use of the endorsement hierarchy.
	// The authorization value should be empty at the start of the test.
	TPMFeatureEndorsementHierarchy

	// TPMFeatureLockoutHierarchy indicates that the test requires the use of the lockout hierarchy. The
	// authorization value should be empty at the start of the test.
	TPMFeatureLockoutHierarchy

	// TPMFeaturePlatformHierarchy indicates that the test requires the use of the platform hierarchy. The
	// authorization value should be empty at the start of the test.
	TPMFeaturePlatformHierarchy

	// TPMFeaturePCR indicates that the test requires the use of a PCR. This is only required for
	// commands that require authorization - ie, it is not required for TPM2_PCR_Read.
	TPMFeaturePCR

	// TPMFeatureStClearChange indicates that the test needs to make changes that can't be undone without a
	// TPM2_Startup(CLEAR). On a physical TPM device, these changes can only be undone with a platform
	// reset or restart. This is not required for TPM2_HierarchyControl if TPMFeaturePlatformHierarchy is
	// set because the test fixture can undo changes made by this command, as long as the test doesn't
	// disable use of the platform hierarchy.
	TPMFeatureStClearChange

	// TPMFeatureSetCommandCodeAuditStatus indicates that the test uses the TPM2_SetCommandCodeAuditStatus
	// command. This isn't required if TPMFeatureEndorsementHierarchy is set, as changes made by this
	// command can be undone. This implies TPMFeatureNV for the TPM2_SetCommandCodeAuditStatus command.
	TPMFeatureSetCommandCodeAuditStatus

	// TPMFeatureClear indicates that the test uses the TPM2_Clear command. This also requires either
	// TPMFeatureLockoutHierarchy or TPMFeaturePlatformHierarchy. This implies TPMFeatureNV for the
	// TPM2_Clear command.
	TPMFeatureClear

	// TPMFeatureClearControl indicates that the test uses the TPM2_ClearControl command. Changes made by
	// the test can only be undone with the use of the platform hierarchy, which on a proper implementation
	// requires assistance from the platform firmware. This is not needed if TPMFeaturePlatformHierarchy
	// is set, as the test harness will restore the value of disableClear automatically. This implies
	// TPMFeatureNV for the TPM2_ClearControl command.
	TPMFeatureClearControl

	// TPMFeatureShutdown indicates that the test uses the TPM2_Shutdown command. This implies
	// TPMFeatureNV for the TPM2_Shutdown command.
	TPMFeatureShutdown

	// TPMFeatureNVGlobalWriteLock indicates that the test uses the TPM2_NV_GlobalWriteLock command. This
	// may make NV indices that weren't created by the test permanently read only if they define the
	// TPMA_NV_GLOBALLOCK attribute. This implies TPMFeatureNV for the TPM2_NV_GlobalWriteLock command.
	TPMFeatureNVGlobalWriteLock

	// TPMFeatureDAProtectedCapability indicates that the test makes use of a DA protected resource. The
	// test may cause the DA counter to be incremented either intentionally or in the event of a test
	// failure, which may eventually cause the TPM to enter DA lockout mode. This is not needed if
	// TPMFeatureLockoutHierarchy is provided, as this will cause the test harness to automatically
	// reset the DA counter.
	TPMFeatureDAProtectedCapability

	// TPMFeatureNV indicates that the test makes use of a command that may write to NV. Physical
	// TPMs may employ rate limiting on these commands.
	TPMFeatureNV

	// TPMFeaturePersistent indicates that the test may make changes to persistent resources that
	// were not created by the test, such as writing to or undefining NV indices or evicting
	// persistent objects.
	TPMFeaturePersistent
)

func (*TPMFeatureFlags) Set 

func (f *TPMFeatureFlags) Set(value string) error

func (TPMFeatureFlags) String 

func (f TPMFeatureFlags) String() string

type TPMSimulatorOptions 

type TPMSimulatorOptions struct {
	// Port is the TCP port to use for the command channel. This port + 1 will also be used for the
	// platform channel. If this is zero, then the value of [MssimPort] will be used.
	Port uint

	SourcePath     string    // Path for the source persistent data file
	Manufacture    bool      // Indicates that the simulator should be executed in re-manufacture mode
	SavePersistent bool      // Saves the persistent data file back to SourcePath on exit
	Stdout         io.Writer // Specify stdout for simulator
	Stderr         io.Writer // Specify stderr for simulator
	WorkDir        string    // Specify a temporary working directory for the simulator. One will be created if not specified
	KeepWorkDir    bool      // Keep the working directory on exit. Requires WorkDir.
}

TPMSimulatorOptions provide the options to LaunchTPMSimulator

type TPMSimulatorTest 

type TPMSimulatorTest struct {
	TPMTest
}

TPMSimulatorTest is a base test suite for all tests that require a TPM simulator. This test suite requires the use of the transmission interface from this package, which takes care of restoring the TPM state when it is closed.

func (*TPMSimulatorTest) Mssim 

func (b *TPMSimulatorTest) Mssim(c *C) *mssim.Transport

Mssim returns the underlying simulator connection.

func (*TPMSimulatorTest) ResetAndClearTPMSimulatorUsingPlatformHierarchy 

func (b *TPMSimulatorTest) ResetAndClearTPMSimulatorUsingPlatformHierarchy(c *C)

ResetAndClearTPMSimulatorUsingPlatformHierarchy issues a Shutdown -> Reset -> Startup cycle of the TPM simulator which ensures that the platform hierarchy is enabled, and then enables the TPM2_Clear command and clears the TPM using the platform hierarchy.

func (*TPMSimulatorTest) ResetTPMSimulator 

func (b *TPMSimulatorTest) ResetTPMSimulator(c *C)

ResetTPMSimulator issues a Shutdown -> Reset -> Startup cycle of the TPM simulator and causes the test to fail if it is not successful.

func (*TPMSimulatorTest) SetUpTest 

func (b *TPMSimulatorTest) SetUpTest(c *C)

SetUpTest is called to set up the test fixture before each test. If the TCTI member has not been set before this is called, a connection to the TPM simulator and a TPMContext will be created automatically. If TPMBackend is not TPMBackendMssim, then the test will be skipped.

If the TCTI member is set prior to calling SetUpTest, then a TPMContext is created using this connection if necessary.

If the TCTI and TPM members are both set prior to calling SetUpTest, then these will be used by the test.

When TearDownTest is called, the TPM simulator will be reset and cleared and the TPMContext will be closed, unless the test clears the TPM member first.

type TPMTest 

type TPMTest struct {
	BaseTest

	TPM    *tpm2.TPMContext // The TPM context for the test
	TCTI   *Transport       // The TPM transmission interface for the test
	Device tpm2.TPMDevice   // The TPM device that supplies the transmission interface

	TPMFeatures TPMFeatureFlags // TPM features required by tests in this suite
}

TPMTest is a base test suite for all tests that require a TPM and are able to execute on a real TPM or a simulator. This test suite requires the use of the transmission interface from this package, which takes care of restoring the TPM state when it is closed.

func (*TPMTest) ClearTPMUsingPlatformHierarchy 

func (b *TPMTest) ClearTPMUsingPlatformHierarchy(c *C)

ClearTPMUsingPlatformHierarchy enables the TPM2_Clear command and then clears the TPM using the platform hierarchy. It causes the test to fail if it isn't successful.

func (*TPMTest) CommandLog 

func (b *TPMTest) CommandLog() (log []*CommandRecordC)

CommandLog returns a log of TPM commands that have been executed since the start of the test, or since the last call to ForgetCommands.

func (*TPMTest) CreatePrimary 

func (b *TPMTest) CreatePrimary(c *C, hierarchy tpm2.Handle, template *tpm2.Public) tpm2.ResourceContext

CreatePrimary calls the tpm2.TPMContext.CreatePrimary function and asserts if it is not succesful.

func (*TPMTest) CreateStoragePrimaryKeyRSA 

func (b *TPMTest) CreateStoragePrimaryKeyRSA(c *C) tpm2.ResourceContext

CreateStoragePrimaryKeyRSA creates a primary storage key in the storage hierarchy, with the template returned from StorageKeyRSATemplate. On success, it returns the context for the newly created object. It asserts if it is not successful.

func (*TPMTest) EvictControl 

func (b *TPMTest) EvictControl(c *C, auth tpm2.Handle, object tpm2.ResourceContext, persistentHandle tpm2.Handle) tpm2.ResourceContext

EvictControl calls the tpm2.TPMContext.EvictControl function and asserts if it is not successful.

func (*TPMTest) ForgetCommands 

func (b *TPMTest) ForgetCommands()

ForgetCommands forgets the log of TPM commands that have been executed since the start of the test or since the last call to ForgetCommands.

func (*TPMTest) HierarchyChangeAuth 

func (b *TPMTest) HierarchyChangeAuth(c *C, hierarchy tpm2.Handle, auth tpm2.Auth)

HierarchyChangeAuth calls the tpm2.TPMContext.HierarchyChangeAuth function and causes the test to fail if it is not successful.

func (*TPMTest) LastCommand 

func (b *TPMTest) LastCommand(c *C) *CommandRecordC

LastCommand returns a record of the last TPM command that was executed. It asserts if no command has been executed.

func (*TPMTest) NVDefineSpace 

func (b *TPMTest) NVDefineSpace(c *C, authHandle tpm2.Handle, auth tpm2.Auth, publicInfo *tpm2.NVPublic) tpm2.ResourceContext

NVDefineSpace calls the tpm2.TPMContext.NVDefineSpace function and asserts if it is not successful.

func (*TPMTest) NextAvailableHandle 

func (b *TPMTest) NextAvailableHandle(c *C, handle tpm2.Handle) tpm2.Handle

NextAvailableHandle returns the next unused handle starting from the supplied handle. This upper 17-bits of the returned handle will match the upper 17-bits of the supplied handle - ie, if the supplied handle is in a reserved group as defined by the "Registry of reserved TPM 2.0 handles and localities" specification, the returned handle will be in the same reserved group.

It asserts if no handle is available.

func (*TPMTest) RequireAlgorithm 

func (b *TPMTest) RequireAlgorithm(c *C, alg tpm2.AlgorithmId)

RequireAlgorithm checks if the required algorithm is known to the TPM and skips the test if it isn't.

func (*TPMTest) RequireCommand 

func (b *TPMTest) RequireCommand(c *C, code tpm2.CommandCode)

RequireCommand checks if the required command is supported by the TPM and skips the test if it isn't.

func (*TPMTest) RequireECCCurve 

func (b *TPMTest) RequireECCCurve(c *C, curve tpm2.ECCCurve)

RequireECCCurve checks if the specified elliptic curve is known to the TPM and skips the test if it isn't.

func (*TPMTest) RequireRSAKeySize 

func (b *TPMTest) RequireRSAKeySize(c *C, keyBits uint16)

RequireRSAKeySize checks if a RSA object can be created with the specified key size and skips the test if it can't.

func (*TPMTest) RequireSymmetricAlgorithm 

func (b *TPMTest) RequireSymmetricAlgorithm(c *C, algorithm tpm2.SymObjectAlgorithmId, keyBits uint16)

RequireSymmetricAlgorithm checks if an object with the specified symmetric algorithm can be created and skips the test if it can't.

func (*TPMTest) SetUpTest 

func (b *TPMTest) SetUpTest(c *C)

SetUpTest is called to set up the test fixture before each test. If the TPM, TCTI and Device members have not been set before this is called, a TPM connection and TPMContext will be created automatically. In this case, the TPMFeatures member should be set prior to calling SetUpTest in order to declare the features that the test will require. If the test requires any features that are not included in PermittedTPMFeatures, the test will be skipped. If TPMBackend is TPMBackendNone, then the test will be skipped.

If the Device member is set prior to calling SetUpTest, a TPM connection and TPMContext is created using this.

If the TCTI member is set prior to calling SetUpTest, a TPMContext is created using this connection if necessary.

If both TPM and TCTI are set prior to calling SetUpTest, then these will be used by the test.

The TPMContext is closed automatically when TearDownTest is called, unless the test clears the TPM member first.

func (*TPMTest) StartAuthSession 

func (b *TPMTest) StartAuthSession(c *C, tpmKey, bind tpm2.ResourceContext, sessionType tpm2.SessionType, symmetric *tpm2.SymDef, authHash tpm2.HashAlgorithmId) tpm2.SessionContext

StartAuthSession calls the tpm2.TPMContext.StartAuthSession function and asserts if it is not successful.

type Transport added in v1.4.0 

type Transport struct {

	// CommandLog keeps a record of all of the commands executed via
	// this interface
	CommandLog []*CommandRecord
	// contains filtered or unexported fields
}

Transport is a special proxy inteface used for testing, which wraps a real interface. It tracks changes to the TPM state and restores it when the connection is closed, and also performs some permission checks to ensure that a test does not access functionality that it has not declared as permitted.

func NewSimulatorTCTI deprecated 

func NewSimulatorTCTI(c *C) *Transport

NewSimulatorTCTI returns a new Transport for testing that corresponds to a connection to the TPM simulator on the port specified by the MssimPort variable. If TPMBackend is not TPMBackendMssim then the test will be skipped.

The returned Transport must be closed when it is no longer required.

Deprecated: Use NewSimulatorDevice.

func NewSimulatorTCTIT deprecated 

func NewSimulatorTCTIT(t *testing.T) *Transport

NewSimulatorTCTIT returns a new Transport for testing that corresponds to a connection to the TPM simulator on the port specified by the MssimPort variable. If TPMBackend is not TPMBackendMssim then the test will be skipped.

The returned Transport must be closed when it is no longer required.

Deprecated: use NewSimulatorTransportT.

func NewSimulatorTransport deprecated added in v1.4.0 

func NewSimulatorTransport(c *C) *Transport

NewSimulatorTransport returns a new Transport for testing that corresponds to a connection to the TPM simulator on the port specified by the MssimPort variable. If TPMBackend is not TPMBackendMssim then the test will be skipped.

The returned Transport must be closed when it is no longer required.

Deprecated: Use NewSimulatorDevice.

func NewSimulatorTransportT added in v1.4.0 

func NewSimulatorTransportT(t *testing.T) *Transport

NewSimulatorTransportT returns a new Transport for testing that corresponds to a connection to the TPM simulator on the port specified by the MssimPort variable. If TPMBackend is not TPMBackendMssim then the test will be skipped.

The returned Transport must be closed when it is no longer required.

func NewTCTI deprecated 

func NewTCTI(c *C, features TPMFeatureFlags) *Transport

NewTCTI returns a new Transport for testing, for integration with test suites that might have a custom way to create a TPMContext. If TPMBackend is TPMBackendNone then the current test will be skipped. If TPMBackend is TPMBackendMssim, the returned Transport will wrap a *mssim.Transport and will correspond to a connection to the TPM simulator on the port specified by the MssimPort variable. If TPMBackend is TPMBackendDevice, the returned Transport will wrap a *linux.Transport if the requested features are permitted, as defined by the PermittedTPMFeatures variable. In this case, the Transport will correspond to a connection to the Linux character device at the path specified by the TPMDevicePath variable. If the test requires features that are not permitted, the test will be skipped.

The returned Transport must be closed when it is no longer required.

Deprecated: Use NewDevice.

func NewTCTIT deprecated 

func NewTCTIT(t *testing.T, features TPMFeatureFlags) *Transport

NewTCTIT returns a new Transport for testing, for integration with test suites that might have a custom way to create a TPMContext. If TPMBackend is TPMBackendNone then the current test will be skipped. If TPMBackend is TPMBackendMssim, the returned Transport will wrap a *mssim.Transport and will correspond to a connection to the TPM simulator on the port specified by the MssimPort variable. If TPMBackend is TPMBackendDevice, the returned Transport will wrap a *linux.Transport if the requested features are permitted, as defined by the PermittedTPMFeatures variable. In this case, the Transport will correspond to a connection to the Linux character device at the path specified by the TPMDevicePath variable. If the test requires features that are not permitted, the test will be skipped.

The returned Transport must be closed when it is no longer required.

Deprecated: Use NewDeviceT.

func NewTPMContext 

func NewTPMContext(c *C, features TPMFeatureFlags) (*tpm2.TPMContext, *Transport)

NewTPMContext returns a new TPMContext for testing. If TPMBackend is TPMBackendNone then the current test will be skipped. If TPMBackend is TPMBackendMssim, the returned context will correspond to a connection to the TPM simulator on the port specified by the MssimPort variable. If TPMBackend is TPMBackendDevice, a TPMContext will be returned if the requested features are permitted, as defined by the PermittedTPMFeatures variable. In this case, the TPMContext will correspond to a connection to the Linux character device at the path specified by the TPMDevicePath variable. If the test requires features that are not permitted, the test will be skipped.

The returned TPMContext must be closed when it is no longer required.

func NewTPMContextT 

func NewTPMContextT(t *testing.T, features TPMFeatureFlags) (tpm *tpm2.TPMContext, transport *Transport, close func())

NewTPMContextT returns a new TPMContext for testing. If TPMBackend is TPMBackendNone then the current test will be skipped. If TPMBackend is TPMBackendMssim, the returned context will correspond to a connection to the TPM simulator on the port specified by the MssimPort variable. If TPMBackend is TPMBackendDevice, a TPMContext will be returned if the requested features are permitted, as defined by the PermittedTPMFeatures variable. In this case, the TPMContext will correspond to a connection to the Linux character device at the path specified by the TPMDevicePath variable. If the test requires features that are not permitted, the test will be skipped.

The returned TPMContext must be closed when it is no longer required. This can be done with the returned close callback, which will cause the test to fail if closing doesn't succeed.

func NewTPMSimulatorContext 

func NewTPMSimulatorContext(c *C) (*tpm2.TPMContext, *Transport)

NewTPMSimulatorContext returns a new TPMContext for testing that corresponds to a connection to the TPM simulator on the port specified by the MssimPort variable. If TPMBackend is not TPMBackendMssim then the test will be skipped.

The returned TPMContext must be closed when it is no longer required.

func NewTPMSimulatorContextT 

func NewTPMSimulatorContextT(t *testing.T) (tpm *tpm2.TPMContext, transport *Transport, close func())

NewTPMSimulatorContextT returns a new TPMContext for testing that corresponds to a connection to the TPM simulator on the port specified by the MssimPort variable. If TPMBackend is not TPMBackendMssim then the test will be skipped.

The returned TPMContext must be closed when it is no longer required. This can be done with the returned close callback, which will cause the test to fail if closing doesn't succeed.

func NewTransport deprecated added in v1.4.0 

func NewTransport(c *C, features TPMFeatureFlags) *Transport

NewTransport returns a new Transport for testing, for integration with test suites that might have a custom way to create a TPMContext. If TPMBackend is TPMBackendNone then the current test will be skipped. If TPMBackend is TPMBackendMssim, the returned Transport will wrap a *mssim.Transport and will correspond to a connection to the TPM simulator on the port specified by the MssimPort variable. If TPMBackend is TPMBackendDevice, the returned Transport will wrap a *linux.Transport if the requested features are permitted, as defined by the PermittedTPMFeatures variable. In this case, the Transport will correspond to a connection to the Linux character device at the path specified by the TPMDevicePath variable. If the test requires features that are not permitted, the test will be skipped.

The returned Transport must be closed when it is no longer required.

Deprecated: Use NewDevice.

func NewTransportT deprecated added in v1.4.0 

func NewTransportT(t *testing.T, features TPMFeatureFlags) *Transport

NewTransportT returns a new Transport for testing, for integration with test suites that might have a custom way to create a TPMContext. If TPMBackend is TPMBackendNone then the current test will be skipped. If TPMBackend is TPMBackendMssim, the returned Transport will wrap a *mssim.Transport and will correspond to a connection to the TPM simulator on the port specified by the MssimPort variable. If TPMBackend is TPMBackendDevice, the returned Transport will wrap a *linux.Transport if the requested features are permitted, as defined by the PermittedTPMFeatures variable. In this case, the Transport will correspond to a connection to the Linux character device at the path specified by the TPMDevicePath variable. If the test requires features that are not permitted, the test will be skipped.

The returned Transport must be closed when it is no longer required.

Deprecated: Use NewDeviceT.

func OpenTPMDevice added in v1.4.0 

func OpenTPMDevice(c *C, device tpm2.TPMDevice) (tpm *tpm2.TPMContext, transport *Transport)

OpenTPMDevice opens the supplied device, returning a new TPMContext and transport. If the device returns ErrSkipNoTPM, then the test will be skipped. If the supplied device returns a transport, it must be wrapped with WrapTransport.

func OpenTPMDeviceT added in v1.4.0 

func OpenTPMDeviceT(t *testing.T, device tpm2.TPMDevice) (tpm *tpm2.TPMContext, transport *Transport, close func())

OpenTPMDeviceT opens the supplied device, returning a new TPMContext and transport. If the device returns ErrSkipNoTPM, then the test will be skipped. If the supplied device returns a transport, it must be wrapped with WrapTransport.

func WrapTCTI deprecated 

func WrapTCTI(transport tpm2.Transport, permittedFeatures TPMFeatureFlags) (*Transport, error)

WrapTCTI wraps the supplied transport and authorizes it to use the specified features. If the supplied Transport corresponds to a real TPM device, the caller should verify that the specified features are permitted by the current test environment by checking the value of the PermittedTPMFeatures variable before calling this, and should skip the current test if it needs to use features that are not permitted.

Deprecated: Use WrapTransport.

func WrapTransport added in v1.4.0 

func WrapTransport(transport tpm2.Transport, permittedFeatures TPMFeatureFlags) (*Transport, error)

WrapTransport wraps the supplied transport and authorizes it to use the specified features. If the supplied Transport corresponds to a real TPM device, the caller should verify that the specified features are permitted by the current test environment by checking the value of the PermittedTPMFeatures variable before calling this, and should skip the current test if it needs to use features that are not permitted.

func (*Transport) Close added in v1.4.0 

func (t *Transport) Close() error

Close will attempt to restore the state of the TPM and then close the connection.

If any hierarchies were disabled by a test, they will be re-enabled if TPMFeaturePlatformHierarchy is permitted and the platform hierarchy hasn't been disabled. If TPMFeaturePlatformHierarchy isn't permitted or the platform hierarchy has been disabled, then disabled hierarchies cannot be re-enabled. Note that TPMFeatureStClearChange must be permitted in order to disable hierarchies without being able to reenable them again.

If any hierarchy authorization values are set by a test, they will be cleared. If the authorization value for the owner or endorsement hierarchy cannot be cleared because the test disabled the hierarchy and it cannot be re-enabled, an error will be returned. If an authorization value cannot be cleared because it was set by a command using command parameter encryption, an error will be returned. The test must clear the authorization value itself in this case.

If the TPM2_ClearControl command was used to disable the TPM2_Clear command, it will be re-enabled if TPMFeaturePlatformHierarchy is permitted. If TPMFeaturePlatformHierarchy isn't permitted, then the TPM2_Clear command won't be re-enabled. The TPMFeatureClearControl must be permitted in order to use the TPM2_ClearControl command in this case. If TPMFeaturePlatformHierarchy is permitted and TPMFeatureClearControl is not permitted, but the TPM2_Clear command cannot be re-enabled (eg, because the platform hierarchy was disabled), then an error will be returned.

If TPMFeatureLockoutHierarchy is permitted, the DA counter will be reset. If TPMFeatureLockoutHierarchy is not permitted then the DA counter will not be reset. In this case, TPMFeatureDAProtectedCapability must be permitted in order to use any DA protected resource which might cause the DA counter to be incremented.

Changes made by the TPM2_DictionaryAttackParameters command will be reverted.

Any transient objects or sessions loaded into the TPM will be flushed.

Any persistent resources created by the test will be evicted or undefined. If a persistent resource cannot be evicted or undefined (eg, because the corresponding hierarchy has been disabled and cannot be re-enabled), an error will be returned. If a NV index is defined with the TPMA_NV_POLICY_DELETE attribute set, an error will be returned. The test must undefine the index itself in this case. It is not possible for resources created by a test to remain in the TPM after calling this function without returning an error.

If the TPM2_SetCommandCodeAuditStatus command was used and TPMFeatureEndorsementHierarchy is permitted, changes made by that command will be undone. If TPMFeatureEndorsementHierarchy is not permitted, then TPMFeatureSetCommandCodeAuditStatus must be permitted in order to use that command and in this case, changes made by it won't be undone. If changes can't be undone because, eg, the endorsement hierarchy was disabled and cannot be reenabled, and TPMFeatureSetCommandCodeAuditStatus is not permitted, then an error will be returned.

func (*Transport) Read added in v1.4.0 

func (t *Transport) Read(data []byte) (int, error)

func (*Transport) Unwrap added in v1.4.0 

func (t *Transport) Unwrap() tpm2.Transport

Unwrap returns the real interface that this one wraps.

func (*Transport) Write added in v1.4.0 

func (t *Transport) Write(data []byte) (int, error)

type TransportWrapper added in v1.4.0 

type TransportWrapper interface {
	tpm2.Transport
	Unwrap() tpm2.Transport
}

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.