tpm-ca-certificates

Motivation

This project is the TPM equivalent of ca-certificates, centralizing and standardizing the management of root certificates used by Trusted Platform Modules (TPMs) to facilitate their integration across systems and applications.

Why it's important?

Validating the Endorsement Key Certificate's chain allows you to verify that a TPM is genuine by confirming it was manufactured by a trusted vendor. Once the device's nature has been verified (and typically added to an inventory), you can leverage advanced security capabilities such as:

• Provisioning: securely add secrets or keys to the TPM
• Remote Attestation: verify the integrity and configuration of a remote system
• HMAC Salted Sessions: establish secure, authenticated communication channels with the TPM

Without a trusted root certificate bundle, there's no reliable way to validate the provenance of a TPM device.

The Problem

Today, information about TPM root certificates is scattered across manufacturer websites and documentation, making it difficult to find and collect — a paradox given their critical importance for security. This fragmentation has a counterproductive effect: most open-source tools that interact with TPMs skip certificate verification entirely 🫠. This is the equivalent of running curl -sS --insecure https://letsencrypt.org — accepting any certificate without validation.

This repository aims to correct this situation through a collective community effort to centralize, standardize, and make TPM root certificates easily accessible and verifiable.

Primitives

📖 Human-readable Configuration

Both bundles are generated from a dedicated human-readable configuration file (.tpm-roots.yaml for roots and .tpm-intermediates.yaml for intermediates). Anyone can see and understand how the bundle is built. Additionally, git provides a history of changes.

[!IMPORTANT] The configuration file only points to public resources (URLs) and does not include any certificates directly. This ensures that the certificates used in the bundle are accessible to everyone and can be independently verified.

🧑‍⚖️ Certificate Acceptance

The repository implements a strict validation process for adding certificates to the bundle. Each certificate addition requires concrete evidence (e.g., PDFs, official documentation links) proving that the certificate URL is publicly published by the TPM manufacturer. Once validated, these sources are added to the repository's src/ directory for transparency and future reference.

🔄 Reproducibility

The repository provides a CLI tool (tpmtb) designed to enable users to locally reproduce any released bundle. Simply clone the repository, checkout a specific tag, and run a single command to regenerate the exact same bundle.

This deterministic generation process ensures transparency and verifiability — two generation processes executed under the same conditions must produce identical results.

[!NOTE] See Bundle Generation Backward Compatibility for more details on how we maintain reproducibility across versions.

🔐 Integrity

Users and systems must be able to verify that a bundle release is authentic and originates from the expected pipeline. To achieve this, the project leverages a public transparency log (Rekor) to store signatures and attestations that can be verified by anyone.

This allows verification that:

1. The bundle is indeed the product of the repository's pipeline
2. The bundle has not been altered since its publication

[!NOTE] This verification capability also applies to the tpmtb CLI binary and its OCI image.

Quick Start

The easiest way to use this bundle is through the tpmtb (TPM Trust Bundle) CLI tool, which handles downloading, verification, and validation automatically.

go install github.com/loicsikidi/tpm-ca-certificates/cmd/tpmtb@latest

docker pull ghcr.io/loicsikidi/tpm-ca-certificates/tpmtb:latest

docker run --rm ghcr.io/loicsikidi/tpm-ca-certificates/tpmtb:latest --help

Download the Bundle

Download the latest trust bundle with automatic integrity and provenance verification:

tpmtb bundle download

[!NOTE] This command:

1. 📥 Downloads the latest bundle from GitHub releases
2. 🔐 Verifies the bundle's integrity against the public transparency log (Rekor)
3. 🔐 Validates the provenance attestation against the public transparency log (Rekor)

The verification ensures that the bundle was genuinely produced by this repository's CI pipeline and hasn't been tampered with since publication.

[!TIP] When using the OCI image, you can output the bundle to stdout (since the container filesystem is read-only):

docker run --rm ghcr.io/loicsikidi/tpm-ca-certificates/tpmtb:latest bundle download --type root --output-dir - > tpm-ca-certificates.pem
docker run --rm ghcr.io/loicsikidi/tpm-ca-certificates/tpmtb:latest bundle download --type intermediate --output-dir - > tpm-intermediate-ca-certificates.pem

Now you can use tpm-ca-certificates.pem as the trusted root certificate bundle for your TPM interactions 💫.

Documentation

The companion blog series is a great starting point to understand the motivation and design decisions. If you want to dive deeper into the technical details, the documentation index provides a comprehensive collection of guides, specifications, and references to explore.

Tracing

[!WARNING] This feature is experimental and may change or be removed in future releases without notice.

The project includes OpenTelemetry tracing to measure and analyze performance of the GetTrustedBundle operation. Tracing is disabled by default and must be explicitly enabled.

Enabling Tracing

To enable tracing, set the OTEL_ENABLED environment variable:

export OTEL_ENABLED=true
tpmtb bundle download

Configuration

Tracing can be configured via environment variables:

Supported samplers: always_on, always_off, traceidratio

Example with Jaeger

Run Jaeger to collect and visualize traces:

docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

Enable tracing and run the CLI:

export OTEL_ENABLED=true
tpmtb bundle download

View traces at http://localhost:16686

Roadmap

• Improve certificate catalog
  • We are actively looking to expand the number of root certificates included in the bundle. Contributions are welcome! Please refer to the Contributing Guide for details on how you could help.
• Gather feedback from early adopters to improve usability and address real-world needs
  • Please open discussions or issues on GitHub to share your thoughts!
• Support offline verification mode for air-gapped or restricted environments
  • Step 1: verify bundle integrity + provenance offline (only with root certificates)
  • Step 2: provide Intermediates certificates for full chain validation offline
    • note: this will require way more effort to gather and maintain the intermediates certificates and is a lower priority for now
• Add tpmtb in nixpkgs for easy installation via Nix
• Enhance CI/CD pipeline
  • Monitor certificate links for availability and integrity
  • Monitor when a root CA is about to expire
  • Monitor release verification process to ensure it continues to work as expected
• Provide a golang-sdk to ease integration in Go
• Code a minimal project using golang-sdk in order to demonstrate its usage and validate its ergonomics and usability
  • Deliverable: 🧿 tpm-trust

License

BSD-3-Clause License. See the LICENSE file for detail

Alternatives

Microsoft maintains an archive with a number of TPM root and intermediate certificates as described in their documentation.

Here's a comparative overview:

[^1]: Provenance here means that there is a publicly accessible URL (owned by the TPM vendor) to retrieve the certificate.