feat: [#411] detect passphrase-protected SSH key and warn during create environment

josecelano · josecelano · commit e688a7ce5b9f · 2026-04-07T16:49:15.000+01:00
- Add is_passphrase_protected() in new src/adapters/ssh/key_inspector.rs - Detection uses byte inspection: bcrypt KDF scan for OpenSSH format, header check for legacy PEM (ENCRYPTED/Proc-Type: 4,ENCRYPTED) - Use base64 crate (already transitive, now direct) instead of inline decoder - Add ProgressReporter::warn() for advisory user-facing warnings - Emit non-blocking warning in CreateEnvironmentCommandController::execute() when the configured SSH private key appears passphrase-protected - Add encrypted ed25519 test fixture (fixtures/testing_ed25519_encrypted) - Add ADR: docs/decisions/ssh-key-passphrase-detection.md - Add user guide: docs/user-guide/ssh-keys.md - Update docs/user-guide/providers/hetzner.md with SSH key requirements - Update docs/user-guide/commands/create.md with passphrase warning note - Update docs/user-guide/README.md with ssh-keys link Closes #411
diff --git a/Cargo.toml b/Cargo.toml
@@ -44,6 +44,7 @@ path = "src/bin/test_logging.rs"
 [dependencies]
 tokio = { version = "1.0", features = [ "full" ] }
 anyhow = "1.0"
+base64 = "0.22"
 chrono = { version = "0.4", features = [ "serde" ] }
 clap = { version = "4.0", features = [ "derive" ] }
 derive_more = { version = "2.1", features = [ "display", "from" ] }
diff --git a/docs/decisions/README.md b/docs/decisions/README.md
@@ -6,6 +6,7 @@ This directory contains architectural decision records for the Torrust Tracker D
 
 | Status        | Date       | Decision                                                                                                  | Summary                                                                                    |
 | ------------- | ---------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| ✅ Accepted   | 2026-04-07 | [SSH Key Passphrase Detection](./ssh-key-passphrase-detection.md)                                         | Detect passphrase-protected keys via byte inspection; reject ssh-keygen probe approach     |
 | ✅ Accepted   | 2026-02-26 | [SDK Package Naming](./sdk-package-naming.md)                                                             | Keep "SDK" name for packages/sdk — the modern API-wrapper meaning is industry-standard     |
 | ✅ Accepted   | 2026-02-24 | [SDK Presentation Layer Interface Design](./sdk-presentation-layer-interface-design.md)                   | Return () from SDK operations; no domain types or typestate pattern in the SDK public API  |
 | ✅ Accepted   | 2026-02-24 | [Docker Compose Local Validation Placement](./docker-compose-local-validation-placement.md)               | Validate rendered docker-compose.yml in the infrastructure generator, not the app layer    |
diff --git a/docs/decisions/ssh-key-passphrase-detection.md b/docs/decisions/ssh-key-passphrase-detection.md
@@ -0,0 +1,90 @@
+# Decision: SSH Key Passphrase Detection via Byte Inspection
+
+## Status
+
+✅ Accepted
+
+## Date
+
+2026-04-07
+
+## Context
+
+When a user configures a passphrase-protected SSH private key in `ssh_credentials`,
+the deployer fails silently during the `provision` step with a misleading
+`Permission denied (publickey,password)` error. The root cause — that the key is
+encrypted and cannot be decrypted without a passphrase in an unattended environment —
+is never surfaced.
+
+To give users an early, actionable warning, the `create environment` command needs to
+detect whether the configured private key is passphrase-protected before it runs the
+deployment workflow. Two approaches were considered.
+
+See also: [Issue #411](../../docs/issues/411-bug-ssh-key-passphrase-breaks-automated-deployment.md)
+
+## Decision
+
+Detect passphrase protection by reading and inspecting the raw bytes of the key file
+(**byte inspection**), implemented as a pure-Rust free function
+`is_passphrase_protected(path: &Path) -> bool` in
+`src/adapters/ssh/credentials.rs`.
+
+Detection rules:
+
+- **Legacy PEM format** (`PKCS#8` / traditional): the header line contains
+  `BEGIN ENCRYPTED PRIVATE KEY` or the `Proc-Type: 4,ENCRYPTED` header is present.
+- **OpenSSH format** (`-----BEGIN OPENSSH PRIVATE KEY-----`): the binary body
+  (base64-decoded) contains the byte sequence `bcrypt` within the first 100 bytes.
+  OpenSSH uses `bcrypt` as the KDF name when a passphrase is set; the KDF name is
+  `none` for unencrypted keys.
+
+The check is **best-effort**:
+
+- A false negative (encrypted key not detected) is acceptable — the warning is advisory.
+- A false positive (unencrypted key flagged) must be avoided — it would confuse users.
+- Any I/O or parse error returns `false` (no spurious warning).
+
+## Consequences
+
+**Positive**:
+
+- Pure Rust, zero new dependencies. No external process is spawned just for detection.
+- Fast: reads only the first ~150 bytes of the file (header + base64 start).
+- Works in any environment, including minimal Docker images where `ssh-keygen` may not
+  be present.
+- Handles both common key formats (legacy PEM, OpenSSH).
+
+**Negative / Risks**:
+
+- False-negative risk for exotic or future key formats (e.g., PKCS#1 passphrase-
+  protected RSA keys with `Proc-Type` elsewhere in the file). Acceptable per spec.
+- Requires maintaining a small inline base64 decoder (~25 lines) because no base64
+  crate is in the dependency list. The decoder is minimal but covers the standard
+  alphabet only; malformed base64 returns `false` rather than an error.
+
+## Alternatives Considered
+
+### `ssh-keygen -y` probe
+
+Spawn `ssh-keygen -y -f <key> < /dev/null`: this exits non-zero when the key is
+passphrase-protected, allowing detection via the exit code.
+
+**Rejected because**:
+
+- Requires `ssh-keygen` to be present at runtime. Docker images used in CI/CD may not
+  include it, making the check environment-dependent.
+- Spawns an external process with I/O redirection just for an advisory check — this
+  adds latency and error-handling complexity (exit codes must distinguish "encrypted"
+  from "file not found" or "unsupported format").
+- The byte-inspection approach is faster, self-contained, and sufficient for the
+  best-effort goal.
+
+## Related Decisions
+
+- [Validated Deserialization for Domain Types](./validated-deserialization-for-domain-types.md)
+
+## References
+
+- [Issue #411 spec](../issues/411-bug-ssh-key-passphrase-breaks-automated-deployment.md)
+- [OpenSSH key format](https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.key)
+- Implementation: `src/adapters/ssh/credentials.rs`
diff --git a/docs/user-guide/README.md b/docs/user-guide/README.md
@@ -388,6 +388,13 @@ See individual service guides for detailed configuration options and verificatio
 - Production security checklist
 - Security incident response
 
+### SSH Keys
+
+The deployer uses SSH for all remote operations (`provision`, `configure`, `release`, `run`).
+Automated deployments (Docker, CI/CD) require a passphrase-free key or SSH agent forwarding.
+
+**[📖 SSH Keys Guide →](ssh-keys.md)**
+
 ### Logging Configuration
 
 Control logging output with command-line options:
diff --git a/docs/user-guide/commands/create.md b/docs/user-guide/commands/create.md
@@ -833,6 +833,32 @@ ssh-keygen -t rsa -b 4096 -f ~/.ssh/deployer_key
 "public_key_path": "~/.ssh/deployer_key.pub"
 ```
 
+### Passphrase-Protected SSH Key Warning
+
+**During `create environment` you may see**:
+
+```text
+⚠️  SSH private key appears to be passphrase-protected.
+  Key: /home/you/.ssh/torrust_key
+
+  Automated deployment (e.g. Docker, CI/CD) requires an SSH key that can be
+  used without interactive input. A passphrase-protected key will cause the
+  `provision` step to fail with "Permission denied" unless one of the
+  following is arranged: …
+```
+
+This is a **warning, not an error** — the environment is created normally. The warning
+means the configured key is encrypted and may not work in automated contexts (Docker,
+CI/CD) without an SSH agent.
+
+**Resolution options**:
+
+1. Remove the passphrase: `ssh-keygen -p -f /path/to/your/key`
+2. Forward your SSH agent socket into the Docker container.
+3. Use a separate passphrase-free deployment key.
+
+See the [SSH Keys Guide](../ssh-keys.md) for full details on all three workflows.
+
 ### Environment Already Exists
 
 **Problem**: `Environment 'my-env' already exists`
diff --git a/docs/user-guide/providers/hetzner.md b/docs/user-guide/providers/hetzner.md
@@ -145,6 +145,32 @@ cat /var/log/cloud-init-output.log
 4. **Regular updates** - Keep server packages updated
 5. **Disable root SSH access** - For production, see [SSH Root Access Guide](../../security/ssh-root-access-hetzner.md)
 
+## SSH Key Requirements
+
+> ⚠️ **Docker deployments require a passphrase-free SSH key (or SSH agent forwarding).**
+
+When you run the deployer inside a Docker container (the recommended approach for
+Hetzner), there is no SSH agent and no interactive terminal. A passphrase-protected
+private key will cause the `provision` step to fail with
+`Permission denied (publickey,password)`.
+
+**Options**:
+
+1. **Remove the passphrase** (recommended for dedicated deployment keys):
+
+   ```bash
+   ssh-keygen -p -f ~/.ssh/your_deployment_key
+   # Press Enter twice for an empty new passphrase
+   ```
+
+2. **Forward your SSH agent** into the container (see [SSH Keys Guide](../ssh-keys.md#workflow-2--passphrase-protected-key-with-ssh-agent-forwarding-into-docker)).
+
+The `create environment` command will warn you if it detects a passphrase-protected key
+so you can resolve this before reaching `provision`.
+
+For more detail on generating keys, removing passphrases, and security considerations,
+see the [SSH Keys Guide](../ssh-keys.md).
+
 ## SSH Key Behavior
 
 Hetzner deployments configure SSH access through two mechanisms:
diff --git a/docs/user-guide/ssh-keys.md b/docs/user-guide/ssh-keys.md
@@ -0,0 +1,146 @@
+# SSH Key Handling
+
+This page covers everything you need to know about SSH keys for the Torrust Tracker Deployer:
+why they are required, what format they must be in for automated deployment, and how to
+generate or adjust them.
+
+## Why the Deployer Needs SSH Keys
+
+The deployer uses SSH for every remote operation after infrastructure is provisioned:
+
+- **`provision`** — Waits for the VM to accept SSH connections; verifies cloud-init ran
+  successfully.
+- **`configure`** — Uploads configuration files and runs Ansible playbooks over SSH.
+- **`release`** — Pushes Docker images and starts Docker Compose over SSH.
+- **`run`** — Triggers service restarts and smoke tests over SSH.
+
+All steps use the key pair configured in `ssh_credentials.private_key_path` /
+`ssh_credentials.public_key_path`.
+
+## Key Requirements for Unattended Automation
+
+When running in an automated environment (Docker container, CI/CD pipeline, GitHub
+Actions), there is **no interactive terminal and no SSH agent**. This means:
+
+| Scenario                           | Works? |
+| ---------------------------------- | ------ |
+| Unencrypted (passphrase-free) key  | ✅ Yes |
+| Passphrase-protected + SSH agent   | ✅ Yes |
+| Passphrase-protected, no SSH agent | ❌ No  |
+
+A passphrase-protected key without an accessible SSH agent will cause every `provision`
+(and later) step to fail with:
+
+```text
+Permission denied (publickey,password)
+```
+
+This error is indistinguishable from a wrong key or an unconfigured `authorized_keys`
+file. The deployer will emit a warning during `create environment` if it detects a
+passphrase-protected key so you can resolve this before reaching the `provision` step.
+
+## Supported Workflows
+
+### Workflow 1 — Passphrase-free dedicated deployment key (recommended)
+
+Generate a dedicated key with no passphrase and use it only for deploying this
+environment. This is the simplest and most portable approach.
+
+```bash
+ssh-keygen -t ed25519 -C "torrust-tracker-deployer" \
+    -f ~/.ssh/torrust_tracker_deployer_ed25519
+# Leave the passphrase empty (press Enter twice)
+```
+
+Configure it in your environment JSON:
+
+```json
+"ssh_credentials": {
+  "private_key_path": "/home/you/.ssh/torrust_tracker_deployer_ed25519",
+  "public_key_path":  "/home/you/.ssh/torrust_tracker_deployer_ed25519.pub"
+}
+```
+
+### Workflow 2 — Passphrase-protected key with SSH agent forwarding into Docker
+
+If you need to keep the passphrase on the key, you can forward your local SSH agent
+socket into the deployer Docker container:
+
+```bash
+# Make sure your key is loaded into the agent
+ssh-add ~/.ssh/torrust_tracker_deployer_ed25519
+
+# Pass the agent socket when running the container
+docker run --rm \
+  -v "$SSH_AUTH_SOCK:/tmp/ssh-agent.sock" \
+  -e SSH_AUTH_SOCK=/tmp/ssh-agent.sock \
+  -v $(pwd)/envs:/var/lib/torrust/deployer/envs \
+  -v $(pwd)/build:/var/lib/torrust/deployer/build \
+  torrust/tracker-deployer:latest \
+  provision my-environment
+```
+
+The deployer will use the agent socket to authenticate without needing the passphrase
+in plaintext.
+
+### Workflow 3 — Native (non-Docker) execution with an SSH agent on the host
+
+When running the deployer binary directly (not in Docker), your desktop SSH agent is
+typically already running and holds the unlocked key. The deployer inherits the
+`SSH_AUTH_SOCK` environment variable automatically.
+
+```bash
+# Load your key once per session
+ssh-add ~/.ssh/torrust_tracker_deployer_ed25519
+
+# Run the deployer natively — the agent socket is inherited
+torrust-tracker-deployer provision my-environment
+```
+
+## Removing an Existing Passphrase
+
+If you already created a key with a passphrase and want to remove it:
+
+```bash
+ssh-keygen -p -f ~/.ssh/torrust_tracker_deployer_ed25519
+# Enter old passphrase, then press Enter twice for the new (empty) passphrase
+```
+
+## Security Notes
+
+- **Dedicated deployment keys** — Use a separate key pair for each deployer environment;
+  never reuse your personal SSH key for automated deployments.
+- **Key rotation** — Replace deployment keys after the deployment is complete or the
+  environment is destroyed.
+- **Filesystem permissions** — Private key files must be readable only by the owner:
+
+  ```bash
+  chmod 600 ~/.ssh/torrust_tracker_deployer_ed25519
+  ```
+
+- **Never commit private keys** — Add key paths to `.gitignore`; store them outside the
+  repository.
+
+## Configuration Reference
+
+The SSH key paths are specified in the `ssh_credentials` section of the environment
+configuration file:
+
+```json
+"ssh_credentials": {
+  "private_key_path": "/absolute/path/to/private_key",
+  "public_key_path":  "/absolute/path/to/private_key.pub",
+  "username": "torrust",
+  "port": 22
+}
+```
+
+See the [environment config JSON schema](../../schemas/environment-config.json) for the
+full `ssh_credentials` field documentation.
+
+## Related Documentation
+
+- [Create Environment Command](commands/create.md) — passphrase warning details
+- [Hetzner Provider Guide](providers/hetzner.md) — SSH key requirements for cloud deployments
+- [Security Guide](security.md) — broader security considerations
+- [ADR: SSH Key Passphrase Detection](../../docs/decisions/ssh-key-passphrase-detection.md)
diff --git a/fixtures/testing_ed25519_encrypted b/fixtures/testing_ed25519_encrypted
@@ -0,0 +1,8 @@
+-----BEGIN OPENSSH PRIVATE KEY-----
+b3BlbnNzaC1rZXktdjEAAAAACmFlczI1Ni1jdHIAAAAGYmNyeXB0AAAAGAAAABCtM/OB+H
+A9QtdudEIKnvoDAAAAGAAAAAEAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIIkjTjzVEWbr51lw
+dxmTUtxE2yb1tm90w0Pof0cxtdosAAAAoJHTSbtCOaQBtfxlDt5ucdRRPAHeOztym/RMYw
+AINeYEA2IgJsBB0oGwmqhg8xBQiXdJPcdCMWvaNgp95YgXkJN0IdNObCsbbimCf67fZJca
+GQ6uDsVJKwZigrEtZl34dbIHrlQoer0lfIDAn7zOvhqi9QqlMj+SNt46d5xyv0aTjhy5BS
+8VzGOS3INun2IjIixrN+VaIL/fYeCLoWADdaA=
+-----END OPENSSH PRIVATE KEY-----
diff --git a/fixtures/testing_ed25519_encrypted.pub b/fixtures/testing_ed25519_encrypted.pub
@@ -0,0 +1 @@
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIkjTjzVEWbr51lwdxmTUtxE2yb1tm90w0Pof0cxtdos test-only-do-not-use
diff --git a/src/adapters/ssh/credentials.rs b/src/adapters/ssh/credentials.rs
@@ -1,4 +1,4 @@
-//! SSH credentials management for remote authentication
+//! SSH credentials for remote instance authentication
 //!
 //! This module provides the `SshCredentials` struct which manages SSH authentication
 //! information including private/public key paths and username configuration.
diff --git a/src/adapters/ssh/key_inspector.rs b/src/adapters/ssh/key_inspector.rs
diff --git a/src/adapters/ssh/mod.rs b/src/adapters/ssh/mod.rs
diff --git a/src/presentation/cli/controllers/create/subcommands/environment/handler.rs b/src/presentation/cli/controllers/create/subcommands/environment/handler.rs
diff --git a/src/presentation/cli/views/progress/mod.rs b/src/presentation/cli/views/progress/mod.rs

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIkjTjzVEWbr51lwdxmTUtxE2yb1tm90w0Pof0cxtdos test-only-do-not-use`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-//! SSH credentials management for remote authentication`
	`1`	`+//! SSH credentials for remote instance authentication`
`2`	`2`	`//!`
`3`	`3`	//! This module provides the `SshCredentials` struct which manages SSH authentication
`4`	`4`	`//! information including private/public key paths and username configuration.`