tpm-fido

tpm-fido is a FIDO2/WebAuthn platform authenticator for Linux that protects credential keys using your system's TPM (Trusted Platform Module). It works with Chrome/Chromium via Native Messaging and supports the PRF (Pseudo-Random Function) extension for deriving cryptographic material from credentials.

Install with one command:

curl -sSL https://raw.githubusercontent.com/vitorpy/tpm-fido2-prf/main/scripts/install-latest.sh | bash

Or download the latest release and run:

tar -xzf tpm-fido-*-complete.tar.gz
cd tpm-fido-*/
./install.sh

This installs both the native binary and Chrome extension with a smart installer that checks prerequisites and guides you through setup.

• Binary: ~/bin/tpm-fido (4.5MB static binary)
• Extension: ~/.local/share/tpm-fido-extension/
• Native messaging manifest: ~/.config/{google-chrome,chromium}/NativeMessagingHosts/

After installation, the script will automatically open chrome://extensions. Follow the on-screen instructions to load the extension from ~/.local/share/tpm-fido-extension/.

• TPM-backed keys: Private keys never leave the TPM
• Fingerprint verification: User presence via fprintd
• PRF extension support: Derive encryption keys from credentials (works during create and get)
• Resident keys: Discoverable credentials stored locally
• Platform authenticator: Presents as a built-in authenticator to websites

tpm-fido uses the TPM 2.0 API. The overall design is as follows:

On registration, tpm-fido generates a new P256 primary key under the Owner hierarchy on the TPM. To ensure that the key is unique per site and registration, tpm-fido generates a random 20 byte seed for each registration. The primary key template is populated with unique values from a sha256 hkdf of the 20 byte random seed and the application parameter provided by the browser.

A signing child key is then generated from that primary key. The key handle returned to the caller is a concatenation of the child key's public and private key handles and the 20 byte seed.

On an authentication request, tpm-fido will attempt to load the primary key by initializing the hkdf in the same manner as above. It will then attempt to load the child key from the provided key handle. Any incorrect values or values created by a different TPM will fail to load.

1. TPM access: Your user must have permission to access /dev/tpmrm0

   sudo usermod -aG tss $USER
   # Log out and back in for group changes to take effect

2. Fingerprint enrollment: Enroll at least one fingerprint via fprintd

   fprintd-enroll

3. Go compiler: Required to build from source

   # Arch Linux
   sudo pacman -S go
   
   # Ubuntu/Debian
   sudo apt install golang

1. Clone the repository

   git clone https://github.com/vitorpy/tpm-fido2-prf.git
   cd tpm-fido2-prf

2. Load the Chrome extension

   • Open Chrome and navigate to chrome://extensions
   • Enable "Developer mode"
   • Click "Load unpacked" and select the tpm-fido2-extension directory
   • Copy the extension ID (32-character string shown below the extension name)

3. Run the install script

   ./contrib/install.sh <extension-id>

   This will:

   • Build the tpm-fido binary
   • Install it to ~/bin/tpm-fido
   • Configure the Native Messaging manifest for Chrome/Chromium

4. Restart Chrome to pick up the Native Messaging host

1. Visit webauthn.io to test basic registration and authentication
2. Check the extension's service worker console for debug logs:
   • Go to chrome://extensions
   • Find "TPM-FIDO2 Platform Authenticator"
   • Click "Inspect views: service worker"

Resident credential metadata is stored at:

~/.local/share/tpm-fido/credentials.json

This file contains credential metadata only (user info, RP info, credential ID). Private keys remain in the TPM and are never stored on disk.

For details on the Native Messaging protocol between the Chrome extension and tpm-fido, see docs/EXTENSION_PROTOCOL.md.

• pinentry: For fingerprint verification prompts (usually installed with GPG)
• fprintd: For fingerprint authentication

• Verify the native messaging manifest is installed correctly:

  cat ~/.config/google-chrome/NativeMessagingHosts/com.vitorpy.tpmfido.json

• Check that the binary path in the manifest points to an existing executable
• Check that the extension ID in the manifest matches your loaded extension

• Add your user to the tss group:

  sudo usermod -aG tss $USER

• Log out and back in for group changes to take effect

• Ensure fingerprints are enrolled: fprintd-list $USER
• Enroll a fingerprint: fprintd-enroll

See LICENSE file.