simulator

README

Go bindings to the Microsoft TPM2 Simulator

Microsoft maintains the reference implementation of the TPM2 spec at: https://github.com/Microsoft/ms-tpm-20-ref/.

The Microsoft code used here is actually a fork of the upstream source. It is vendored at simulator/ms-tpm-20-ref to maintain compatiblity with go get. Building the simulator requires the OpenSSL headers to be installed. This can be doen with:

• Debian based systems (including Ubuntu): apt install libssl-dev
• Red Hat based systems: yum install openssl-devel
• Arch Linux based systems: openssl is installed by default (as a dependancy of base) and includes the headers.

Debugging

The simulator provides a useful way to figure out what the TPM is actually doing when it executes a command. If you compile a test which runs against the simulator, you can step through the simulator C source to see the exact operations performed.

To do this:

1. Compile a test as a standalone binary. For example, if you were using a go-tpm-tools/client test (which all run against the simulator), compile the test binary named client.test by running:

   go test -c github.com/google/go-tpm-tools/client
   

2. Now you can debug the binary using GDB:

   # Load the binary into GDB (fixing any errors/warnings you get)
   gdb ./client.test
   # In GDB, set a breakpoint in the funciton you want to use.
   (gdb) break TPM2_CreatePrimary 
   Breakpoint 1 at 0x5d3710: file ./TPMCmd/tpm/src/command/Hierarchy/CreatePrimary.c, line 72.
   # Now you can either run all the tests in the package, or just one.
   # As we want to depug TPM2_CreatePrimary we'll run TestSeal
   (gdb) run -test.run TestSeal
   Starting program: ./client.test -test.run TestSeal
   Thread 1 "client.test" hit Breakpoint 1, TPM2_CreatePrimary
       at ./TPMCmd/tpm/src/command/Hierarchy/CreatePrimary.c:72
   72	{
   # Go to the next line
   (gdb) n
   81	    newObject = FindEmptyObjectSlot(&out->objectHandle);
   # Step into a function
   (gdb) s
   FindEmptyObjectSlot
       at ./TPMCmd/tpm/src/subsystem/Object.c:266
   266	{
   # Continue until the next breakpoint (or exiting)
   (gdb) c
   Continuing.
   PASS
   [Inferior 1 (process 29395) exited normally]
   

IDE Support

When examining the TPM2 C code, is is often useful to have IDE support for things like "Go to Definition". To get this working, all your IDE should need is knowing where the headers are and what #define statements to use.

For example, when using VS Code with the C/C++ extension, add the following file to your workplace root at .vscode/c_cpp_properties.json:

{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                "${workspaceFolder}/**"
            ],
            "defines": [
                "VTPM=NO",
                "SIMULATION=NO",
                "USE_DA_USED=NO",
                "HASH_LIB=Ossl",
                "SYM_LIB=Ossl",
                "MATH_LIB=Ossl"
            ],
            "compilerPath": "/bin/clang",
            "cStandard": "c11",
            "cppStandard": "c++17",
            "intelliSenseMode": "clang-x64"
        }
    ],
    "version": 4
}

Documentation

Overview

Package simulator provides a go interface to the Microsoft TPM2 simulator.

Index

• Variables
• type Simulator
  • func Get() (*Simulator, error)
  • func GetWithFixedSeedInsecure(seed int64) (*Simulator, error)
  • func (s *Simulator) Close() error
  • func (s *Simulator) IsClosed() bool
  • func (s *Simulator) ManufactureReset() error
  • func (s *Simulator) Read(responseBuffer []byte) (int, error)
  • func (s *Simulator) Reset() error
  • func (s *Simulator) Write(commandBuffer []byte) (int, error)

Variables

var ErrUsingClosedSimulator = errors.New("attempting to use a closed simulator")

ErrUsingClosedSimulator is returned if any operation on a Simulator is attempted after it is closed.

Types

type Simulator

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

Simulator represents a go-tpm compatible interface to the IBM TPM2 simulator. Similar to the file-based (for linux) or syscall-based (for Windows) TPM handles, no synchronization is provided; the same simulator handle should not be used from multiple threads.

func Get

func Get() (*Simulator, error)

Get the pointer to an initialized, powered on, and started simulator. As only one simulator may be running at a time, a second call to Get() block until the first Simulator is Closed.

func GetWithFixedSeedInsecure

func GetWithFixedSeedInsecure(seed int64) (*Simulator, error)

GetWithFixedSeedInsecure behaves like Get() expect that all of the internal hierarchy seeds are derived from the input seed. Note that this function compromises the security of the keys/seeds and should only be used for tests.

func (*Simulator) Close

func (s *Simulator) Close() error

Close cleans up and stops the simulator, Close() should always be called when the Simulator is no longer needed, freeing up other callers to use Get().

func (*Simulator) IsClosed

func (s *Simulator) IsClosed() bool

IsClosed returns true if the simulator has been Closed()

func (*Simulator) ManufactureReset

func (s *Simulator) ManufactureReset() error

ManufactureReset behaves like Reset() except that the TPM is complete wiped. All data (NVData, Hierarchy seeds, etc...) is cleared or reset.

func (*Simulator) Read

func (s *Simulator) Read(responseBuffer []byte) (int, error)

Read gets the response of a command previously issued by calling Write().

func (*Simulator) Reset

func (s *Simulator) Reset() error

Reset the TPM as if the host computer had rebooted.

func (*Simulator) Write

func (s *Simulator) Write(commandBuffer []byte) (int, error)

Write executes the command specified by commandBuffer. The command response can be retrieved with a subsequent call to Read().