Authentication & SSH Agent

Secure connection authentication is the core of PhanTerm. We employ a dual-track credential storage mechanism and native Agent integration to ensure your secrets are always safe.

Secure Credential Storage

Whether it’s the main connection password, jump host password, or the passphrase protecting your SSH private key, PhanTerm provides you with rigorous local encryption protection.

• Windows Users: Updating to version 0.13.0 automatically handles and migrates your credentials to the higher-level Windows CNG (Cryptography Next Generation) encryption protection. This process is completely silent and provides stronger isolation and security compared to the traditional Windows Credential Manager.
• macOS / Linux Users: PhanTerm prioritizes saving passwords in your operating system’s System Keyring.

Caution

Your Secrets Always Stay Local Your passwords and credentials are never uploaded to the cloud. When the above system-level key management is unavailable (e.g., on some headless Linux servers), PhanTerm securely falls back to using a local, highly randomized key for AES-256-GCM encrypted storage. The cipher text is saved locally in connections.yaml.

SSH Key Authentication

When creating or editing a connection, you can set the Auth Type to Key and specify the path to your private key file (e.g., ~/.ssh/id_ed25519). PhanTerm securely reads the key for authentication and can automatically prompt you to decrypt password-protected private keys.

SSH Agent Integration

PhanTerm perfectly supports SSH Agent, meaning you can avoid repeatedly entering your private key password.

1. System Agent Bridging

If you are already running an SSH Agent on your operating system:

• Windows: PhanTerm automatically detects and bridges to the OpenSSH Agent (\\.\pipe\openssh-ssh-agent).
• macOS / Linux: It automatically detects and bridges to SSH_AUTH_SOCK.

2. Built-in Agent & Agent Forwarding

Even if you don’t use a system-level agent, PhanTerm runs its own Agent service in memory. By enabling Forward Agent in your connection settings, PhanTerm securely forwards your credential authorization to the remote server via the RFC 4254 protocol. This allows you to clone Git repositories directly or jump to other machines from the remote server without copying your private key files there.

Authentication Priority Order: If multiple authentication methods are enabled, PhanTerm attempts to log in in the following order:

1. Keys provided by the System Agent
2. Keys provided by PhanTerm’s built-in Agent
3. The specified private key file
4. Username and password

Hardware Security Keys and Cryptographic Authentication

PhanTerm fully supports FIDO2/U2F-based hardware security keys (such as YubiKey or Windows Hello). This authentication method securely locks your private key within physical hardware or a TPM chip, providing cryptographic-strength identity verification and fundamentally defending against malware that attempts to steal credentials by reading disk or memory.

Physical Security Keys (YubiKey, etc.) Bridging Guide

If you use a physical security key, PhanTerm seamlessly bridges to it via the system’s SSH Agent (supported on macOS, Linux, and Windows):

1. Run ssh-add in your terminal to load your security key into the operating system’s SSH Agent (e.g., ssh-add ~/.ssh/id_ed25519_sk).
2. In the PhanTerm connection form, set the Auth Type to Key.
3. Point the Key Path to your security key’s public key or private key stub file to use it seamlessly.

Windows Hello Native Key Guide

For Windows users, PhanTerm provides native Windows Hello hardware key integration. This means you can generate an unexportable security key directly within your device’s TPM chip.

Security Advantage: The private key is generated and permanently resides inside the TPM chip and cannot be exported. This effectively prevents local trojans or unauthorized processes from silently stealing plaintext passwords or software private keys.

1. One-Click Upgrade Path (Highly Recommended)

If you previously used a password to log into a server, we strongly recommend using the “one-click upgrade” feature to elevate your connection to hardware protection smoothly and securely:

1. Connect to the server successfully using your password as usual.
2. After a successful connection, an “Upgrade to Hardware Protection” notification banner will pop up in the bottom right corner of the interface.
3. Upon agreeing to the upgrade, the system will prompt for Windows Hello verification (Fingerprint/Face/PIN) and automatically generate a hardware-bound security key locally.
4. PhanTerm will automatically reuse the current active session to securely push the newly generated public key to the remote server’s ~/.ssh/authorized_keys.
5. The system will automatically perform a background verification using the new key. Once verified, it will completely and permanently destroy the locally stored password.

2. New Connection Form Path

When creating a new connection, you can also choose to generate a hardware-bound key directly within the form.

Known Limitation: Manual Remote Configuration Required

When generating a key in the new connection form, the system only generates the hardware credential on your local device (the public key and private key stub). Since no remote SSH session has been established at this point, the system cannot push the public key automatically. You must manually copy and append the contents of the generated <keyPath>.pub file to the target server’s ~/.ssh/authorized_keys, otherwise the key will fail server authentication.

Windows Hello Security Boundary Clarification

To ensure you fully understand the characteristics of hardware security keys, please note the following expected security mechanisms:

• Mandatory Verification Every Time: Due to the TPM’s hardware gatekeeping mechanism and the strict requirements of the WebAuthn specification, PhanTerm does not and cannot cache your verification status in memory. This means that every time you connect, reconnect, or trigger a handshake signature, the operating system will inevitably pop up the Windows Hello (Fingerprint/Face/PIN) verification prompt. This operation cannot be bypassed and is a core expected security design.
• Nature of Built-in Caching: You may notice that PhanTerm includes a built-in Agent caching mechanism. This cache is solely used to store ssh.Signer runtime objects to reduce disk I/O and key matching time; it does not exempt you from biometric verification requirements.