TPM 2.0-Sealed Biometric "First Unlock" (Cold Boot Unlock) on Linux Desktop

[jon-warner]

Select Topic Area

✅ Code Contribution Proposal

Code Contribution Proposal

Select Topic Area

✅ Code Contribution Proposal

Code Contribution Proposal

TPM 2.0-Sealed Biometric "First Unlock" (Cold Boot Unlock) on Linux Desktop

TL;DR: I want to implement native support for "First Unlock on App Startup" using Linux system authentication (Polkit/PAM). To ensure a robust security posture, the master vault key is cryptographically sealed inside the physical TPM 2.0 chip using systemd-creds (in user space), and only the resulting sealed ciphertext is saved in the OS keyring.

---

Background

On Windows (Windows Hello) and macOS (Touch ID), the Bitwarden Desktop client supports storing biometric-protected keys persistently. However, on Linux Desktop, biometric unlock has historically been ephemeral (in-session unlock only) and does not survive application restarts. On a cold restart, the user is forced to re-type their master password.

Furthermore, standard keyring storage (e.g., plain GNOME Keyring entries) offers a weak security model on Linux because the login keyring is often automatically unlocked at login. Storing the raw vault key in the keyring would effectively allow any user-space application to read it without user presence checks.

To solve this, I want to introduce a physical hardware-gated security model on Linux:

• TPM 2.0 cryptographic sealing: The raw master key is never saved. It is passed to the motherboard's TPM 2.0 chip for encryption, and only the resulting sealed ciphertext is stored in the OS keyring.
• Frictionless Decryption: Decryption requires user presence validation (using Linux's standard Polkit/PAM agent, e.g., local fingerprint readers running fprintd), which subsequently unseals the key from the TPM 2.0 hardware chip.

---

Current State

• ✅ Desktop App (Windows/macOS): Persistently stores biometrics-sealed keys (Windows Hello DPAPI / macOS Keychain Access Control).
• ⚠️ Desktop App (Linux): Biometric unlock is ephemeral (cleared from memory on restart). No persistent keyring backup is supported.
• ❌ Linux Startup Gating: The app has no mechanism to verify if TPM 2.0 hardware is functional before offering biometric settings, leading to potential setup failures.

---

Use Cases

• Linux Desktop Users: Power users on modern Linux distributions (e.g., Ubuntu 24.04+, Fedora, Arch) who want passwordless startup convenience using their system's biometric/PAM configuration.
• Security-Conscious Environments: Users who want to unlock their vault with a fingerprint but demand that the master key be hardware-bound to their physical machine.

---

Proposed Implementation

1. Hardware Sealing via systemd-creds

Instead of implementing raw TPM 2.0 interface code, we use standard Linux systemd-creds commands running in user-space (using the --user flag) to encrypt/decrypt payload data. This avoids the need for elevated root permissions or Polkit prompts during keyring reads.

• Encryption (Enrollment):

  systemd-creds encrypt --name=BitwardenBiometricsV2 --user - -

  The resulting ciphertext is stored in GNOME Keyring under the service BitwardenBiometricsV2 and the specific Bitwarden user GUID as the account.

• Decryption (Unlock):

  systemd-creds decrypt --user - -

  The app feeds the ciphertext from GNOME Keyring to the decrypt command, which unseals it only after a successful authentication challenge via the system Polkit agent.

2. Runtime Gating & Fallbacks

To prevent UI settings from showing broken configurations on systems without a TPM 2.0 chip, the Rust native layer (desktop_native) performs a one-time check during initialization by running a test encryption payload.

• If is_tpm_available() fails, the setting is hidden or disabled.
• The JS/TS layer is updated to gate supportsBiometrics() on this status.

3. Prompt Ordering Optimization

To prevent annoying "phantom" biometric prompts on startup, we check for the presence of the keyring entry before initiating the user challenge:

if self.secure_memory.lock().await.has(user_id) {
    // Session is active (in RAM) -> prompt system auth
} else {
    // Cold launch: check if TPM ciphertext exists in keyring *before* triggering the prompt
    let encrypted = password::get_password(KEYCHAIN_SERVICE_NAME, user_id).await?;
    // Target ciphertext exists -> proceed to biometric prompt and decrypt
}

---

Ready to Contribute

I have verified this implementation locally on Ubuntu. It compiles cleanly and successfully unlocks the desktop vault on app startup using the local TPM 2.0 chip and system authentication.

I would appreciate your feedback on this architecture (specifically the reliance on systemd-creds --user for Linux user-space TPM operations) before submitting a formal Pull Request!

[github-actions[bot]]

✨ Thank you for your code contribution proposal! While the Bitwarden team reviews your submission, we encourage you to check out our contribution guidelines.

Please ensure that your code contribution includes a detailed description of what you would like to contribute, along with any relevant screenshots and links to existing feature requests. This information helps us gather feedback from the community and Bitwarden team members before you start writing code.

To keep discussions focused, posts that do not include a proposal for a code contribution will be removed.

• 💡 For feature requests and general discussion, please visit the Bitwarden Community Forums.
• ℹ️ For questions and support, visit the Bitwarden Help Center.
• 🐛 To report a potential bug, please visit the corresponding repo. Server | Clients | iOS | Android

Thank you for contributing to Bitwarden!

[quexten]

@jon-warner one quetsion on this; do you happen to know if systemd-creds works from within flatpak / snap sandboxes? The most popular clients by far is flatpak, followed by snap. The unsandboxed installations are much less commonly used, so I'm wondering whether we can get to a solution which works on all platforms.

[jon-warner]

Hi @quexten, thanks for reading my contribution proposal.

systemd-creds is often blocked by sandbox rules for flatpak and snap. The PR I'm proposing would gracefully fail and simply hide the setting. We could document necessary sandbox permissions/libraries to add to gain the feature.

For example:
Snap: Add the :tpm plug interface (e.g. plugs: [tpm]) to expose /dev/tpmrm0 inside the sandbox, and bundle systemd-creds in the snap.
Flatpak: Expose /dev/tpmrm0 via device permissions (e.g. --device=all or custom device paths) and include the systemd-creds utility in the build manifest/SDK."