Reducing SSH Passphrase Prompts with ssh-agent

Introduction

SSH public key authentication is a more robust and manageable authentication mechanism compared to password authentication. If you add a passphrase to your private key, you can further mitigate risks in the event that the key file is leaked. However, when using a key with a passphrase, you are prompted for it every time you connect, which often leads to the feeling that "I'm typing a password even though I shouldn't have to."

In this article, I will summarize how to use ssh-agent to reduce the number of times you need to enter your passphrase while continuing to use keys protected by passphrases. This guide targets client-side environments on macOS and Debian-based Linux (such as Ubuntu or Raspberry Pi OS).

The Role of ssh-agent

In SSH authentication, the private key is used to sign a challenge from the server. ssh-agent is a process that performs this signing process on your behalf. Instead of passing the private key itself to every process on the terminal, the agent handles the key in memory and returns only the necessary signature.

Once you load a key into the agent (which requires entering the passphrase for the first time), the same key can be used repeatedly for the duration of the session. In many cases on Linux, this lasts until you log out or reboot; on macOS, through the Apple Keychain integration mentioned later, you can reduce the need for re-entry even after a reboot.

Methods

Step 1: Check for existing keys

Check if you already have a key. Please adjust the filename according to your environment.

ls ~/.ssh

Step 2: Create a key with a passphrase if you don't have one

If you don't have a key, create one using ssh-keygen. While it is possible to use an empty passphrase, I recommend setting a strong passphrase as a prerequisite for this article.

# Example for UNIX-like systems
ssh-keygen -t ed25519 -C "An ID to identify you (typically an email address):DeviceName" -f ~/.ssh/id_ed25519 -a 100

Step 3: Configure ssh-agent

I will introduce how to configure ssh-agent for two patterns: Debian-based Linux and macOS. The basic strategy is to write the configuration into the rc file that is loaded when you log into the shell, ensuring that the key is set up automatically.

Supplementary note: About rc files

An "rc file" is a file where you list commands that are executed when you first enter a shell, such as opening a Terminal app or logging in via SSH.

Linux systems like Ubuntu use bash as the default shell, while macOS uses zsh. Therefore, their respective rc files are commonly managed as follows:

• Bash: ~/.bashrc
• Zsh: ~/.zshrc

These files may not exist by default, so if they are missing, create them using touch ~/.bashrc or nano ~/.bashrc.

Using keychain on Debian-based Linux (Ubuntu, etc.)

On Linux, using a tool called keychain makes it easy to load the ssh-agent environment variables into your shell and register specified keys all at once. On Debian-based systems, install the package and then configure it.

sudo apt update && sudo apt install -y keychain

Add the following line to ~/.bashrc to persist the configuration. Adjust the path to match your private key.

# Add to ~/.bashrc or similar (Example for SSH agent and automatic key registration)
eval "$(keychain --agents ssh --eval ~/.ssh/id_ed25519)"

When you open a new shell, keychain will prepare the agent, and if the key is not registered, you will be prompted to enter the passphrase at that moment. After entering it, the key will remain loaded in the same agent for the duration of the user's session, avoiding frequent re-entries. For server purposes, where reboots are infrequent, the perceived benefits are significant.

---

Using ssh-agent and Keychain on macOS

On macOS, you can use the --apple-use-keychain option with ssh-add to save your passphrase in the Apple Keychain, automating subsequent loads.

Note: The keychain tool for Debian-based systems and the Apple Keychain are different features.

Only for the first time, execute the following in the terminal to load the key into the agent and Keychain. You will be prompted for your private key's passphrase, so enter it here.

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Next, add the agent startup and key loading commands to ~/.zshrc to make the settings persistent.

# Add to ~/.zshrc or similar (Example for starting ssh-agent and loading the key)
if ! pgrep -u "$USER" ssh-agent > /dev/null; then
    eval "$(ssh-agent -s)"
fi
ssh-add -q --apple-use-keychain ~/.ssh/id_ed25519 2>/dev/null

Using -q with ssh-add suppresses error messages that would otherwise appear every time the key is already registered. You may need to manually execute ssh-add --apple-use-keychain again if you are setting up for the first time or immediately after replacing your key.

Keep in mind that keys loaded in an agent increase the risk of abuse by anyone capable of logging into the machine or by malware. Consider operational practices such as not using this on shared terminals, or using ssh-add -D to remove keys from the agent when they are no longer needed.

Conclusion

In this article, I summarized how to use ssh-agent to minimize the need to enter your SSH private key passphrase. By using these methods, you can achieve SSH that combines the security of public key authentication with the convenience of being freed from the hassle of entering passwords/passphrases.

If you found this article helpful, I would be encouraged if you could press the "Like" button!