Security

Security

ssm is designed so that passwords never touch disk and never appear on a command line or in a persistent environment variable.

Password storage

Passwords are stored in the OS keychain — macOS Keychain on macOS, Secret Service (D-Bus) on Linux — via the keyring crate. The keychain entry is keyed by the session name under the service dots-ssm.

How passwords reach ssh (and herdr)

When a session has a stored password, ssm hands it to OpenSSH through the SSH_ASKPASS mechanism (SSH_ASKPASS_REQUIRE=force, OpenSSH 8.4+):

1. ssm spawns a small Unix domain socket server protected by a one-time nonce.
2. ssm sets SSH_ASKPASS to point at itself and SSH_ASKPASS_REQUIRE=force.
3. When ssh needs the password, it re-execs ssm as its askpass helper.
4. The helper connects to the socket, presents the nonce, and receives the password — once. Serve-once semantics prevent brute-force loops on wrong passwords.
5. The socket is torn down immediately after a successful serve.

Nothing is written to disk, and the password never appears on a command line or in a persistent environment variable.

Notes

• For plain ssh, ssm adds -o StrictHostKeyChecking=accept-new, so first-time connections to new hosts still work; a changed host key still aborts (MITM guard).
• herdr --remote takes only a target (no ssh flags), so per-session port / ProxyJump must live in ~/.ssh/config, and the host should already be in known_hosts.
• Because herdr --remote shells out to system ssh, the same SSH_ASKPASS mechanism supplies the password to herdr connections too — stored passwords work in both modes without sshpass.

Selective prompt answering

ssm only answers password prompts. It does not answer key passphrases or host key confirmation prompts — those are left for the user.

Biometric unlock (optional)

Off by default. Enable via Space → Settings → b, or biometric_unlock = true in config.toml. When on, ssm requires a biometric check before revealing a stored password at connect time. Passwords are loaded lazily (only at connect), so the prompt actually gates access.

Linux

Uses fprintd-verify — a fingerprint presence gate in front of the Secret Service release. This is not cryptographically bound to the secret; it's a convenience gate.

macOS

Touch ID is not wired up yet. A real implementation needs LocalAuthentication and a stably code-signed binary so the Secure Enclave keychain item survives rebuilds. Use scripts/sign-macos.sh with a free self-signed "Code Signing" certificate for personal use, or a Developer ID certificate + notarization to distribute. Until it lands, enabling biometric on macOS falls back to a plain keychain read with a warning.

Fallback

If biometric is enabled but no verifier is available, ssm warns and proceeds rather than locking you out of your own hosts.