feat: add option to allow TPM encryption #71

dkaser · 2025-11-15T15:19:02Z

Summary by CodeRabbit

New Features
- Added a TPM setting to enable using a Trusted Platform Module to encrypt and bind the Tailscale node key to device hardware (requires TPM 2.0). Disabling TPM after enabling requires reauthentication.
User Interface
- New TPM control with contextual help and an inline warning shown when toggled.
Documentation
- Added localized help text and a detailed warning explaining TPM implications and recovery considerations.

Signed-off-by: Derek Kaser <[email protected]>

coderabbitai · 2025-11-15T15:19:11Z

Walkthrough

Adds TPM support controls and wiring: UI selection and warnings, new locale strings, a Config property, conditional startup parameter generation based on UseTPM, and removal of hardcoded TPM-related flags from the startup script.

Changes

Cohort / File(s)	Summary
UI & Warning Logic `src/usr/local/emhttp/plugins/tailscale/include/Pages/Settings.php`	Added a TPM selection control (`USE_TPM`) with yes/no options and onchange handling; extended client-side warning/message maps to include a `tpm` entry and documentation link.
Localization `src/usr/local/emhttp/plugins/tailscale/locales/en_US.json`	Added translation keys for `settings.tpm`, `settings.context.tpm`, and `warnings.more_info.tpm` with label, explanatory context, and detailed TPM warning.
Backend Config `src/usr/local/php/unraid-tailscale-utils/unraid-tailscale-utils/Config.php`	Added public boolean property `UseTPM` and initialize it from `USE_TPM` config (default `"0"`).
Startup parameter generation `src/usr/local/php/unraid-tailscale-utils/unraid-tailscale-utils/System.php`	Modified `createTailscaledParamsFile` to append `-encrypt-state=false` and `-hardware-attestation=false` only when `UseTPM` is false.
Startup script `src/usr/local/emhttp/plugins/tailscale/rc.tailscale`	Removed hardcoded `-encrypt-state=false` and `-hardware-attestation=false` flags from the `tailscaled` startup invocation.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant UI as Settings UI
    participant Config as Config Handler
    participant System as Startup Params
    participant Tailscaled

    User->>UI: Toggle "Allow TPM to Encrypt Node Key"
    UI->>UI: Display/Update TPM warning & docs link
    UI->>Config: Save `USE_TPM` value
    Config->>System: Load `UseTPM`
    System->>System: Build tailscaled params
    alt UseTPM = true
        System->>Tailscaled: Start tailscaled (default, TPM allowed)
    else UseTPM = false
        System->>Tailscaled: Start tailscaled with -encrypt-state=false -hardware-attestation=false
    end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Pay attention to System::createTailscaledParamsFile to ensure flags are only emitted when intended and parameter escaping/formatting is correct.
Verify Config.php initialization handles missing/invalid config values robustly.
Review Settings.php onchange wiring and that the tpm message key matches the locale path.
Confirm rc.tailscale removal of flags doesn't leave duplicated behavior or break startup in environments without the new config applied.

Pre-merge checks and finishing touches

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title accurately reflects the main change: adding a TPM encryption option across the UI, configuration, and startup parameters.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feat/tpm

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between fae3863 and cbd24a7.

📒 Files selected for processing (1)

src/usr/local/emhttp/plugins/tailscale/locales/en_US.json (2 hunks)

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: dkaser
Repo: unraid/unraid-tailscale PR: 51
File: src/usr/local/emhttp/plugins/tailscale/rc.tailscale:14-14
Timestamp: 2025-10-25T02:28:03.838Z
Learning: In Tailscale 1.90.2+, the `-hardware-attestation` and `-encrypt-state` flags are valid command-line options for tailscaled, even though they may not be fully documented in public knowledge base articles yet. The `-hardware-attestation` flag uses hardware-backed keys (TPM 2.0) to bind node identity, and `-encrypt-state` encrypts the state file on disk.

📚 Learning: 2025-10-25T02:28:03.838Z

Learnt from: dkaser
Repo: unraid/unraid-tailscale PR: 51
File: src/usr/local/emhttp/plugins/tailscale/rc.tailscale:14-14
Timestamp: 2025-10-25T02:28:03.838Z
Learning: In Tailscale 1.90.2+, the `-hardware-attestation` and `-encrypt-state` flags are valid command-line options for tailscaled, even though they may not be fully documented in public knowledge base articles yet. The `-hardware-attestation` flag uses hardware-backed keys (TPM 2.0) to bind node identity, and `-encrypt-state` encrypts the state file on disk.

Applied to files:

src/usr/local/emhttp/plugins/tailscale/locales/en_US.json

🔇 Additional comments (2)

src/usr/local/emhttp/plugins/tailscale/locales/en_US.json (2)

53-55: TPM setting label and context approved.

The TPM label and description are clear, informative, and grammatically correct. The context properly explains TPM 2.0 requirements and hardware binding semantics.

113-114: Verify peer_relay_no_acl addition is intentional for this PR.

Line 113 introduces a new warning string for peer_relay_no_acl that doesn't appear directly related to the TPM feature. Confirm whether this is an intentional inclusion in this feature PR or an unrelated change that should be tracked separately.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1027a3b and fae3863.

📒 Files selected for processing (5)

src/usr/local/emhttp/plugins/tailscale/include/Pages/Settings.php (2 hunks)
src/usr/local/emhttp/plugins/tailscale/locales/en_US.json (2 hunks)
src/usr/local/emhttp/plugins/tailscale/rc.tailscale (1 hunks)
src/usr/local/php/unraid-tailscale-utils/unraid-tailscale-utils/Config.php (2 hunks)
src/usr/local/php/unraid-tailscale-utils/unraid-tailscale-utils/System.php (1 hunks)

🧰 Additional context used

🧠 Learnings (3)

📓 Common learnings

Learnt from: dkaser
Repo: unraid/unraid-tailscale PR: 51
File: src/usr/local/emhttp/plugins/tailscale/rc.tailscale:14-14
Timestamp: 2025-10-25T02:28:03.838Z
Learning: In Tailscale 1.90.2+, the `-hardware-attestation` and `-encrypt-state` flags are valid command-line options for tailscaled, even though they may not be fully documented in public knowledge base articles yet. The `-hardware-attestation` flag uses hardware-backed keys (TPM 2.0) to bind node identity, and `-encrypt-state` encrypts the state file on disk.

📚 Learning: 2025-10-25T02:28:03.838Z

Learnt from: dkaser
Repo: unraid/unraid-tailscale PR: 51
File: src/usr/local/emhttp/plugins/tailscale/rc.tailscale:14-14
Timestamp: 2025-10-25T02:28:03.838Z
Learning: In Tailscale 1.90.2+, the `-hardware-attestation` and `-encrypt-state` flags are valid command-line options for tailscaled, even though they may not be fully documented in public knowledge base articles yet. The `-hardware-attestation` flag uses hardware-backed keys (TPM 2.0) to bind node identity, and `-encrypt-state` encrypts the state file on disk.

Applied to files:

src/usr/local/php/unraid-tailscale-utils/unraid-tailscale-utils/System.php
src/usr/local/emhttp/plugins/tailscale/locales/en_US.json
src/usr/local/emhttp/plugins/tailscale/rc.tailscale

📚 Learning: 2025-11-15T03:15:08.212Z

Learnt from: dkaser
Repo: unraid/unraid-tailscale PR: 68
File: src/usr/local/php/unraid-tailscale-utils/unraid-tailscale-utils/System.php:371-373
Timestamp: 2025-11-15T03:15:08.212Z
Learning: In the unraid-tailscale project, tailscaled accepts both single-dash and double-dash formats for command-line flags (e.g., both `-port` and `--port` are valid). The project uses single-dash format for consistency across daemon parameters in the System.php file.

Applied to files:

src/usr/local/php/unraid-tailscale-utils/unraid-tailscale-utils/System.php
src/usr/local/emhttp/plugins/tailscale/rc.tailscale

🧬 Code graph analysis (1)

src/usr/local/emhttp/plugins/tailscale/include/Pages/Settings.php (1)

src/usr/local/php/unraid-tailscale-utils/unraid-tailscale-utils/Info.php (1)

tr (66-69)

🔇 Additional comments (6)

src/usr/local/php/unraid-tailscale-utils/unraid-tailscale-utils/Config.php (1)

34-34: LGTM! TPM configuration property properly implemented.

The UseTPM property follows the established pattern for boolean configuration values, with a safe default of false that maintains backward compatibility.

Also applies to: 60-60

src/usr/local/emhttp/plugins/tailscale/rc.tailscale (1)

14-14: LGTM! Startup command now uses dynamic parameters.

Removing the hardcoded TPM-related flags in favor of $TAILSCALE_CUSTOM_PARAMS allows the TPM feature to be controlled through the configuration system, as intended.

src/usr/local/emhttp/plugins/tailscale/include/Pages/Settings.php (2)

105-116: LGTM! TPM UI control properly integrated.

The TPM setting is appropriately placed in the advanced section with a warning handler that displays information before enabling. The default option is "No" (safe default), consistent with other security-sensitive settings.

303-311: LGTM! Warning system properly extended for TPM.

The JavaScript warning logic correctly includes TPM messages and documentation link. The trailing comma added to the 'dns' entry improves maintainability.

src/usr/local/emhttp/plugins/tailscale/locales/en_US.json (1)

114-114: LGTM! TPM warning appropriately communicates risks.

The warning clearly explains the implications of enabling TPM, including the hardware lock-in and potential need for reauthentication if TPM is disabled or locks out.

src/usr/local/php/unraid-tailscale-utils/unraid-tailscale-utils/System.php (1)

375-377: Ensure UseTPM configuration is validated against actual TPM 2.0 hardware availability.

The code logic is correct—when UseTPM is false, it explicitly disables the flags; when true, it omits them to use defaults. However, Tailscale will fail to start if -encrypt-state or -hardware-attestation are enabled but the system lacks a functioning TPM 2.0 module. This is not a graceful degradation.

The developer must ensure that the configuration system validates TPM 2.0 hardware availability before setting UseTPM to true, otherwise the daemon will fail to start rather than handling the mismatch gracefully.

src/usr/local/emhttp/plugins/tailscale/locales/en_US.json

Signed-off-by: Derek Kaser <[email protected]>

feat: add option to allow TPM encryption

fae3863

Signed-off-by: Derek Kaser <[email protected]>

github-actions bot added the feat label Nov 15, 2025

coderabbitai bot reviewed Nov 15, 2025

View reviewed changes

src/usr/local/emhttp/plugins/tailscale/locales/en_US.json Outdated Show resolved Hide resolved

fix: typo

cbd24a7

Signed-off-by: Derek Kaser <[email protected]>

dkaser merged commit e2d431f into trunk Nov 15, 2025
6 checks passed

dkaser deleted the feat/tpm branch November 15, 2025 15:28

coderabbitai bot mentioned this pull request Nov 19, 2025

fix: header placement on 7.1 #74

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add option to allow TPM encryption #71

feat: add option to allow TPM encryption #71

Uh oh!

dkaser commented Nov 15, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Nov 15, 2025 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: add option to allow TPM encryption #71

feat: add option to allow TPM encryption #71

Uh oh!

Conversation

dkaser commented Nov 15, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Nov 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Pre-merge checks and finishing touches

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dkaser commented Nov 15, 2025 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Nov 15, 2025 •

edited

Loading