simulator

package
Version: v0.2.7 Latest Latest
Warning

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

Go to latest
Published: Jun 2, 2021 License: Apache-2.0, BSD-3-Clause Imports: 7 Imported by: 0

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:

  • Debain 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/ProsaicSatsuma/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

Constants

This section is empty.

Variables

View Source
var ErrSimulatorInUse = errors.New("simulator is being used by another caller")

ErrSimulatorInUse indicates another open Simulator already exists.

Functions

This section is empty.

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() will return ErrSimulatorInUse 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) 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().

Source Files

Directories

Path Synopsis
Package internal provides low-level bindings to the Microsoft TPM2 simulator.
Package internal provides low-level bindings to the Microsoft TPM2 simulator.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL