google / go-tpm-tools

Go packages built on go-tpm providing a high-level API for using TPMs

Go-TPM tools

The go-tpm-tools module is a TPM 2.0 support library designed to complement Go-TPM.

It contains the following public packages:

• client: A Go package providing simplified abstractions and utility functions for interacting with a TPM 2.0, including:
  • Signing
  • Attestation
  • Reading PCRs
  • Sealing/Unsealing data
  • Importing Data and Keys
  • Reading NVData
  • Getting the TCG Event Log
• server: A Go package providing functionality for a remote server to send, receive, and interpret TPM 2.0 data. None of the commands in this package issue TPM commands, but instead handle:
  • TCG Event Log parsing
  • Attestation verification
  • Creating data for Importing into a TPM
• proto: Common Protocol Buffer messages that are exchanged between the client and server libraries. This package also contains helper methods for validating these messages.
• simulator: Go bindings to the Microsoft's TPM 2.0 simulator.

This repository also contains gotpm, a command line tool for using the TPM. Run gotpm --help and gotpm <command> --help for more documentation.

Use prebuilt gotpm binary

You can download the binary from a release directly.

# VERSION: 0.4.4 ARCH: Linux_x86_64
curl -L https://github.com/google/go-tpm-tools/releases/download/[VERSION]/go-tpm-tools_[ARCH].tar.gz -o go-tpm-tools.tar.gz
tar xvf go-tpm-tools.tar.gz
# You may need to copy the binary to a directory with executable permissions.
# NOTE: on Container-Optimized OS, /var/lib/google/ is executable
./gotpm --help

Building and Installing gotpm

gotpm can be directly installed from this repo by running:

go install github.com/google/go-tpm-tools/cmd/gotpm@latest
# gotpm will be installed to $GOBIN
gotpm --help

Alternatively, to build gotpm from a cloned version of this repo, run:

cd /my/path/to/cloned/go-tpm-tools/cmd/gotpm
go build
# gotpm will be in the cmd/gotpm subdirectory of the repo
./gotpm --help

Minimum Required Go Version

This project currently requires Go 1.20 or newer. Any update to the minimum required Go version will be released as a minor version update.

openssl errors when building simulator

Similarly, when building the simulator library (or tests), you may get an error that looks like:

fatal error: openssl/aes.h: No such file or directory
   47 | // #include <openssl/aes.h>
      |           ^~~~~~~~~~~~~~~~
compilation terminated.

This is because the simulator library depends on having the OpenSSL headers installed. To fix this error, install the appropriate header package:

Linux

# Ubuntu/Debian based systems
sudo apt install libssl-dev
# Redhat/Centos based systems
sudo yum install openssl-devel
# Arch Linux (headers/library in the same package)
sudo pacman -S openssl

macOS

First, install Homebrew. Then run:

brew install openssl

Windows

First, install Chocolatey. Then run:

choco install openssl

Custom install location

If you want to use a different installation of OpenSSL, or you are getting linker errors like ld: library not found for -lcrypto, you can directly point Go your installation. We will assume your installation is located at $OPENSSL_PATH (with lib and include subdirectories).

Add OpenSSL to the include and library path at the command line

This solution does not require modifying go-tpm-tools code and is useful when working on other projects that depend on go-tpm-tools/simulator.

C_INCLUDE_PATH="$OPENSSL_PATH/include" LIBRARY_PATH="$OPENSSL_PATH/lib" go test ...

Add OpenSSL to the include and library path in the code

This solution modifies your local copy of the go-tpm-tools simulator source and removes the need to provide the paths on the command line.

Modify the CFLAGS/LDFLAGS options beginning with #cgo darwin or #cgo windows in simulator/internal/internal.go to point at your installation. This could look something like:

// #cgo darwin CFLAGS: -I $OPENSSL_PATH/include
// #cgo darwin LDFLAGS: -L $OPENSSL_PATH/lib

Remember to revert your modifications to simulator/internal/internal.go before committing your changes.

No TPM 1.2 support

Unlike Go-TPM (which supports TPM 1.2 and TPM 2.0), this module explicitly only supports TPM 2.0. Users should avoid use of TPM 1.2 due to the inherent reliance on SHA1 (which is quite broken).

Confidential VMs with Intel TDX

For Ubuntu image, the tdx_guest module was moved to linux-modules-extra package in the 1016 and newer kernels. You should be able to install the module, and either manually load the module or reboot.

To install the linux-modules-extra package, run:

sudo apt-get install linux-modules-extra-gcp

To manually load the module, run:

sudo modprobe tdx_guest

Legal

Copyright 2018 Google Inc. under the Apache 2.0 License. Microsoft's TPM simulator code is licensed under a 3-clause BSD license and the TCG software license. See the LICENSE file for more information.

This is not an official Google product.