tpm2-tss implements the TCG TPM 2.0 stack layer by layer

A stack of five libraries, each with its own TCG specification

The tpm2-tss repository holds a C implementation of the Trusted Computing Group's TPM2 Software Stack. The way the project is organised is the answer to the question most people arrive with, which is where to start if you want to talk to a TPM 2.0. The stack is described from top to bottom, and each layer is a separate library with a corresponding TCG specification document behind it. At the top sits the Feature API, shipped as libtss2-fapi, described as a high level API for simple TPM usage and backed by the FAPI specification and the TSS 2.0 JSON Data Types and Policy Language specification. Below it are the Enhanced System API and the System API, then the marshalling layer, and at the bottom the transport. The practical consequence is that a caller chooses a level. Writing a policy driven key operation is a different job from issuing a raw command, and the stack lets you descend only as far as your problem requires.

FAPI sits above the command layer for ordinary key operations

The Feature API is the layer most application code should touch, and the project's own description of it is deliberately modest: a high level API for simple TPM usage. What makes it more than a convenience wrapper is the policy language that ships with it. The TCG TSS 2.0 JSON Data Types and Policy Language specification is listed alongside the FAPI specification, and the JSON policy data types are what let a policy be expressed as data rather than code. For an application that needs to key a sealing or signing operation to a set of conditions, that separation is the difference between a policy handled in the program and a policy handled by the library. The trade-off is that FAPI introduces its own concepts, its own configuration and its own failure modes on top of the TPM's. A project that only needs to send a handful of commands may find the simpler layers less of an obstacle, which is exactly why the rest of the stack is exposed rather than hidden.

ESAPI adds sessions, object metadata and asynchronous calls

Below FAPI sits the Enhanced System API, libtss2-esys, and the difference between it and the layer beneath is small in the library list and large in practice. ESAPI is a one to one mapping of the TPM2 commands, and it adds three capabilities: session handling, tracking of metadata for TPM objects, and asynchronous calls. Session handling matters because a TPM will not process a command without an authorization session, and the rules for password, HMAC and policy sessions differ. Object metadata tracking matters because the TPM returns handles, not descriptions, and an application that loses track of what a handle refers to cannot recover it without a read public operation. Asynchronous calls matter for anything that issues work without blocking, and the implementation behind that call form is where the SAPI and ESAPI lines converge. The System API, libtss2-sys, is the same one to one command mapping without the extras, apart from asynchronous calls. The choice between them is a deliberate one, not a maturity one.

MU handles the byte level, TCTI handles the wire

Two lower layers do the mechanical work. The marshalling and unmarshalling library, libtss2-mu, converts all data types in the TPM library specification between the C structures an application uses and the byte streams the chip expects. It sits under the command APIs because both SAPI and ESAPI need it, and it is the layer where the format of every command and response is defined. The TPM Command Transmission Interface, shipped as libtss2-tcti-device, libtss2-tcti-tbs, libtss2-tctildr and libtss2-tcti-swtpm among others, is the standard API for transmitting and receiving TPM commands and responses, and the project points to doc/tcti.md for the detail. The TCTI is the pluggable boundary of the stack: the same code above it works against a real device, against the kernel's TPM interface or against a simulator, because only the transport changes. A loader module, which is what the tctildr name suggests, is what makes that selection possible at runtime.

Installation is delegated to INSTALL.md, and the build tree shows how it is done

There is no install command in the README, and the project says so directly: build and installation instructions for tpm2-tss are available in the INSTALL file. What the repository layout does tell you is the shape of the build. The tree is an Autotools project, with configure.ac, a bootstrap script, a Makefile.am, and additional Makefile-test.am and Makefile-fuzz.am files alongside them, plus a configure-generated dist directory. Tooling configuration lives in m4 and a script directory, documentation is generated from a Doxyfile.in with a sphinx directory for the site, and the man directory holds the manual pages. A REUSE.toml file and a LICENSES directory sit at the top for licence metadata, and there is a separate tss2-dlopen directory and an afl-fuzzing directory, which tells you that dynamic loading of the TCTI and fuzzing are supported workstreams rather than incidental. Documentation can be built locally or browsed on the project's readthedocs site.

The test suite can wear out real TPM flash if you point it at hardware

This is the sharpest warning in the documentation and it should decide whether you run the suite at all. The repository contains a test suite intended to exercise the TCTI, SAPI and ESAPI code, and the README states plainly that it is not intended to test a TPM implementation, so it should only be run against a TPM simulator. If the suite is executed against a TPM other than the software simulator, the documentation says it may cause damage to the TPM, with NV storage wear named as the mechanism. A test suite that repeatedly creates and destroys objects is fine against a simulator and destructive against real flash, and the failure is invisible until the chip wears out. The answer the project gives is to use a simulator. The reference simulator code comes from the TPM library specification and was provided by Microsoft, and there are two Linux implementations of it: swtpm, an open source TPM emulator with socket and character device front ends, whose TCTI module is called swtpm and which has been the default simulator used by this project since tpm2-tss v3.0, and IBM's repackaging of the Microsoft code, distributed as a SourceForge tarball.

One documented deviation from the TCG specification

The stack is meant to follow the TCG documents, and it is worth knowing the single place where it does not. The project notes that it currently deviates from the specification by increasing the value of TPM2_NUM_PCR_BANKS from 3 to 16, in order to ensure compatibility with TPM2 implementations that have enabled a larger than typical number of PCR banks, and that this is expected to be included in a future revision of the specification. The reasoning is practical. A library compiled with a fixed constant of three banks would fail to address banks that a machine exposes, and platform firmware varies in how many it enables. The cost of the deviation is that behaviour differs from the published document, so a reader of the specification alone may be surprised, and code that assumes exactly three banks will not agree with this implementation. Everything else in the stack is described by reference to the specification, including the common structures document that the project calls the basis for all implementations in it.

BSD-2-Clause licensing, recent releases and where to ask questions

The licence field on the repository says BSD-2-Clause, and the tree carries both a LICENSE file and a LICENSES directory with a REUSE.toml file, which is the metadata that maps each file to its licence in a project assembled from many differently licensed pieces. That is a permissive licence with no copyleft obligation on code you link, though the attribution requirements still apply when you redistribute, and the per file mapping is worth reading if you vendor the library into a distribution. On maintenance, the repository is not archived and the last push was on 2026-10-19. The release history shows 4.2.0 and 4.1.4 both published on 2026-07-15, with 4.1.3 dated 2024-05-21, and a CHANGELOG.md plus RELEASE.md at the root to track what changed between them. Support runs through the TPM2 mailing list at lore.kernel.org, with subscription by email to [email protected], since the old list was decommissioned by Linux. There is also an IRC channel, a Gitter room, and a weekly online call at TPM.dev where the tpm2-pkcs11 project and other Linux TPM2 software are discussed.

Editorial conclusion

Adopt tpm2-tss when you are writing Linux software that talks to a TPM 2.0 chip, because it turns command marshalling, session handling and transport into a library boundary instead of a protocol you implement yourself, and because the FAPI, ESAPI and SAPI split lets you pick the amount of machinery you actually need. Do not adopt it for a platform without a TPM, and do not run its test suite against real hardware, since the project states that executing it against anything other than the software simulator may damage the TPM through NV storage wear. Before you start, read INSTALL.md for the build steps, check doc/tcti.md for the transport your deployment uses, and confirm your TPM offers enough PCR banks, because this implementation raises TPM2_NUM_PCR_BANKS from the specified 3 to 16.

Frequently asked questions

Official sources

1. License: BSD-2-Clause
2. Project website
3. README
4. Releases
5. tpm2-software/tpm2-tss on GitHub