wolfTPM/docs

wolfTPM User Manual

The latest wolfTPM user manual is available at: https://www.wolfssl.com/documentation/manuals/wolftpm/index.html Source generated from: https://github.com/wolfSSL/documentation/blob/master/wolfTPM/src/

Introduction

wolfTPM is a portable TPM 2.0 project, designed for embedded use. It is highly portable, due to having been written in native C, having a single IO callback for SPI hardware interface, no external dependencies, and its compacted code with low resource usage.

Protocol Overview

Trusted Platform Module (TPM, also known as ISO/IEC 11889) is an international standard for a secure crypto processor, a dedicated micro-controller designed to secure hardware through integrated cryptographic keys. Computer programs can use a TPM to authenticate hardware devices, since each TPM chip has a unique and secret RSA key burned in as it is produced.

According to Wikipedia, a TPM provides the following:

• A random number generator
• Facilities for the secure generation of cryptographic keys for limited uses.
• Remote attestation: Creates a nearly unforgettable hash key summary of the hardware and software configuration. The software in charge of hashing the configuration data determines the extent of the summary. This allows a third party to verify that the software has not been changed.
• Binding: Encrypts data using the TPM bind key, a unique RSA key descended from a storage key.
• Sealing: Similar to binding, but in addition, specifies the TPM state for the data to be decrypted (unsealed).

In addition, TPM can also be used for various applications such as platform integrity, disk encryption, password protection, and software license protection.

Hierarchies

• Platform: TPM_RH_PLATFORM
• Owner: PM_RH_OWNER
• Endorsement: TPM_RH_ENDORSEMENT

Each hierarchy has their own manufacture generated seed. The arguments used on TPM2_Create or TPM2_CreatePrimary create a template, which is fed into a KDF to produce the same key based hierarchy used. The key generated is the same each time; even after reboot. The generation of a new RSA 2048 bit key takes about 15 seconds. Typically these are created and then stored in NV using TPM2_EvictControl. Each TPM generates their own keys uniquely based on the seed.

There is also an Ephemeral hierarchy (TPM_RH_NULL), which can be used to create ephemeral keys.

Platform Configuration Registers (PCRs)

Platform Configuration Registers (PCRs) are one of the essential features of a TPM. Their prime use case is to provide a method to cryptographically record (measure) software state: both the software running on a platform and configuration data used by that software.

wolfTPM contains hash digests for SHA-1 and SHA-256 with an index 0-23. These hash digests can be extended to prove the integrity of a boot sequence (secure boot).

Building wolfTPM

To build the wolfTPM library, it's required to first build and install the wolfSSL library. This can be downloaded from the download page, or through a "git clone" command, shown below:

git clone https://github.com/wolfssl/wolfssl

Once the wolfSSL library has been downloaded, it needs to be built with the following options being passed to the configure script:

./configure --enable-wolftpm && make && sudo make install

Then the wolfSSL library just needs to be built and installed however the user prefers.

The next step is to download and install the wolfTPM library. At the time this documentation was written, the wolfTPM library does not have a stable release yet and needs to be cloned from GitHub. The following commands show how to clone and install wolfTPM:

git clone https://github.com/wolfssl/wolftpm
cd wolftpm
./autogen.sh
./configure
make

For detailed build instructions see /README.md.

Getting Started

The wolfTPM library has TPM 2.0 wrapper tests, native tests, and a sample benchmark application that come ready-to-use after a successful installation of wolfTPM. Below are some instructions on how to run the sample applications yourself.

To interface with the hardware platform that is running these applications, please see the function TPM2_IoCb inside of hal/tpm_io.c.

Examples

See /examples/README.md

Benchmarks

See /README.md

wolfTPM Library Design

Library Headers

wolfTPM header files are located in /wolftpm.

The general header files that should be included from wolfTPM is shown below:

#include <wolftpm/tpm2.h>
#include <wolftpm/tpm2_wrap.h> /* If using wrappers */

Example Design

Every example application that is included with wolfTPM includes the tpm_io.h header file, located in /hal.

The tpm_io.c file sets up the example HAL IO callback necessary for testing and running the example applications with a Linux Kernel, STM32 CubeMX HAL or Atmel/Microchip ASF. The reference is easily modified, such that custom IO callbacks or different callbacks may be added or removed as desired.

API Reference

See https://www.wolfssl.com/docs/wolftpm-manual/.

TPM 2.0 TCG API's

See /wolftpm/tpm2.h for inline doxygen style API documentation.

wolfTPM Wrapper API's

See /wolftpm/tpm2_wrap.h for inline doxygen style API documentation.

Support

For questions please email support@wolfssl.com