Connection Profiles & Key Deployment

The Connection Manager in sshs3 (accessible via Ctrl+Shift+O or the primary sidebar) centralizes configuration, credentials, and topology management for SSH servers, Kubernetes clusters, and Amazon S3 object storage in a unified, searchable workspace.

1. SSH Profiles & Hierarchical Folders

Organize fleets of hundreds or thousands of servers into logical folder trees (e.g. Prod/Database/Stockholm, Staging/Web) and filter targets instantly in real time.

Cross-Source Search & Origin Badges

Typing in the search bar finds matching profiles across all profile backends simultaneously:

• Local personal connections
• Remote Profile Sync connections
• All joined Team Vaults

Matches outside the current view display an origin badge (e.g. Team: Infra or Sync), making it effortless to jump to any server across all your teams without switching tabs.

"Unlock All" for Locked Hardware Teams

When one or more Team Vaults are currently locked, an Unlock all action button is displayed. Clicking it sequentially prompts your hardware security key or smartcard PIN to unlock all your team vaults in one flow.

SSH Profile Field Reference

Technical Architecture: Storage & Secret Encryption

Profiles are serialized into profiles.json inside the user data directory (~/.config/sshs3/). Writes execute sequentially via queueMutation promises to prevent file corruption during concurrent operations. Secret fields (passwords, private key passphrases) are extracted and encrypted via Electron's safeStorage API using your native OS keyring (libsecret on Linux, DPAPI on Windows, Keychain on macOS).

Good to Know & Limitations: Profile Organization & Folders

• Folder Names: Group and folder names cannot contain reserved filesystem characters (<, >, :, ", |, ?, *). Subfolders are created by separating segments with / (e.g. Databases/Postgres/Replica).
• Pruning Empty Folders: Personal profile folders are virtual groupings; empty folders are cleaned up automatically when all member profiles are moved or deleted. (For persistent empty folders, use Team Vault).

2. Authentication Methods & Hardware Tokens

sshs3 supports five distinct authentication mechanisms:

1. Password: Traditional password authentication, encrypted at rest via the OS keyring.
2. Private Key File: Local private key file (id_ed25519, id_rsa) with optional passphrase.
3. SSH Agent: Delegates authentication to the running SSH agent ($SSH_AUTH_SOCK).
4. FIDO2 / Hardware Security Key: Hardware WebAuthn/FIDO2 credentials via YubiKey (ed25519-sk, ecdsa-sk).
5. Smartcard (PKCS#11): Smartcards (PIV, CAC, SITHS) via native PKCS#11 libraries (p11-kit, opensc, libykcs11).

Hardware Key Guidelines

• FIDO2 Resident Credentials: Select FIDO2 and tick Use a resident (discoverable) credential stored on the device. No key file is needed: the app queries resident credentials stored inside the physical token upon connection.
• Generate New FIDO2 Key: Expand Generate a new key on this security key, choose ED25519-SK (or ECDSA-SK for legacy firmware), tick Require PIN + touch on every use, and touch your key when prompted.
• U2F-Only Keys: Older keys (YubiKey 4, NEO) lack FIDO2 support (ykman info reports FIDO2 Not available). On these devices, generate an ECDSA-SK key without PIN and without resident storage, or use the token's PIV smartcard application instead.
• Safe Password Fallback: When password authentication is chosen, sshs3 passes -o PubkeyAuthentication=no so inserted hardware keys cannot trigger unexpected touch prompts.

Security Model: Zero Private Key Extraction

sshs3 enforces Zero Private Key Extraction. Private key bytes never traverse Node.js or Chromium heaps:

• FIDO2: Key files reference a key handle (-i ~/.ssh/id_ed25519_sk). Resident keys load via OpenSSH's native agent integration (ssh-add -K).
• Smartcards: Configured via -o PKCS11Provider=<library-path> coupled with the app's internal AskpassServer, delivering user PINs over an isolated Unix domain socket.

Good to Know & Limitations: Hardware Keys & Protocol Compatibility

• OpenSSH Version Requirement: FIDO2 security keys require OpenSSH 8.2 or later on both your local workstation and the destination SSH server.
• U2F-Only Keys (YubiKey 4, NEO): Older hardware tokens support U2F but not the FIDO2 standard (ykman info shows FIDO2 Not available). They cannot generate ed25519-sk keys, resident discoverable credentials, or keys with PIN protection (verify-required), causing generation to fail with PIN incorrect or Windows' "This security key can't be used". On these tokens, choose ECDSA-SK, untick Require PIN + touch and Resident, and specify a new output filename; the token will require physical touch only. Alternatively, utilize the card's PIV smartcard applet.
• Dedicated Key Filenames: Assign distinct filenames to each key handle (e.g. id_ed25519_sk_work, id_ed25519_sk_personal) so multiple tokens do not overwrite each other's credentials.

3. Public Key Deployment (ssh-copy-id GUI)

Replace error-prone manual ssh-copy-id commands with a graphical multi-key deployer that safely installs public keys without duplicating lines in ~/.ssh/authorized_keys:

1. Right-click any SSH profile and select Install public key (or click the key icon in the profile editor).
2. Select the public keys you want to authorize (e.g. workstation key, YubiKey FIDO2 key, or smartcard certificate).
3. Select your login method under Log in with (Automatic, Password, or Existing Key) and click Install.
4. Out-of-Band Copy: Click Copy command (Bash) or Copy PowerShell to generate a safe, idempotent one-liner ready to paste into web consoles or out-of-band management terminals (iLO, iDRAC):

mkdir -p -m 700 ~/.ssh && echo 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG...' >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys

5-Stage Connection Health Timeline

The Access Check timeline automatically diagnoses remote connection health before or during key installation:

1. Reach Host: Verifies raw TCP socket connectivity to target port.
2. Host Key: Validates the server's public key fingerprint against ~/.ssh/known_hosts.
3. Login Methods: Probes the OpenSSH daemon for permitted authentication methods without requiring PIN entry.
4. Key Installed: Scans ~/.ssh/authorized_keys to determine whether selected public keys are already present.
5. Login Works: Executes an end-to-end authentication test verifying session authorization.

Good to Know & Limitations: Public Key Deployment

• Initial Login Access: Automated installation requires an existing authentication path (password authentication or an already authorized SSH key). If password authentication is disabled on the server, use Copy command (Bash) and run it via an out-of-band console.
• Read-Only / SELinux Filesystems: Deployment fails if the remote filesystem is mounted read-only, if disk quota is exceeded, or if strict SELinux policies on the server reject writes to ~/.ssh/authorized_keys.

4. Trust On First Use (TOFU) & Host Verification

Connecting to an unknown host displays an interactive fingerprint dialog:

┌────────────────────────────────────────────────────────────────────────┐
│ ⚠️  The authenticity of host '10.0.4.12 (ED25519)' can't be established.│
│ Fingerprint: SHA256:d8b248a...                                         │
│ Are you sure you want to continue connecting?                          │
│ [ Trust Host ]                                           [ Cancel ]    │
└────────────────────────────────────────────────────────────────────────┘

• Verify Fingerprint: Review the SHA256 host key fingerprint and click Trust Host to append the key to ~/.ssh/known_hosts.
• Changed Host Key Guard: If a host key changes unexpectedly, OpenSSH rejects the connection to protect against Man-In-The-Middle (MITM) attacks. sshs3 displays a security warning and allows you to replace the stale key only after explicit confirmation.
• Fail-Closed Policy: Host key prompts captured by AskpassServer abort automatically if not answered within 60 seconds.

Good to Know & Limitations: Host Key Replacement & TOFU

• Host Key Replacement: If a remote server is reinstalled and generates a new host key, OpenSSH halts with HOST KEY VERIFICATION FAILED and sshs3 presents a red security warning. Clicking Replace Key removes the outdated entry from ~/.ssh/known_hosts (identical to ssh-keygen -R <host>), allowing you to verify and trust the new key. Only execute key replacement when you know the remote server was reinstalled intentionally.

5. Advanced OpenSSH Protocol Options

In any SSH profile, expand Advanced SSH Options to fine-tune low-level OpenSSH flags:

6. Migration: Import & Export (~/.ssh/config & JSON)

• Import from OpenSSH: In the Connection Manager, click Import Hosts from ~/.ssh/config. Imports all Host stanzas, hostnames, ports, users, IdentityFile, and ProxyJump directives into organized folders.
• JSON Backup: Click Export JSON Backup to save your folder structure and profiles to a clean JSON file. Saved passwords and secret keys are stripped for safety.
• Import JSON: Restore saved profiles on a new workstation via Import JSON Backup.

Good to Know & Limitations: Configuration Import Filtering

• Directive Allowlist: When importing from ~/.ssh/config, only safe connection parameters are imported (Host, HostName, User, Port, IdentityFile, ProxyJump, LocalForward, RemoteForward, DynamicForward). Wildcard patterns (*, ?) and executable directives (ProxyCommand, LocalCommand) are strictly ignored to prevent configuration injection.

7. Troubleshooting & Diagnostics