ssh-add is a command for adding SSH private keys into the SSH authentication agent for implementing single sign-on with SSH. The agent process is called ssh-agent; see that page to see how to run it.
The cool thing about ssh-agent and ssh-add is that they allow the user to use any number of servers, spread across any number of organizations, without having to type in a password every time when moving between servers. This is commonly used by system administrators to move among the machine they administer. It is also widely used in universities and research institutions for accessing computing resources. However, it has also lead to proliferation of SSH keys in enterprises, and that is something administrators should be aware of and audit should take steps to address.
Contents
Adding Default Keys Adding an Arbitrary Key Keys with Passphrasesssh-add Command Line Options
Adding Default Keys
In the simplest form, ssh-add can be run without arguments. Used this way, it adds the default keys ~/.ssh/id_rsa, ~/.ssh/id_dsa, ~/.ssh/id_ecdsa. ~/ssh/id_ed25519, and ~/.ssh/identity, if they exist.
Adding an Arbitrary Key
To add an arbitrary private key, give the path of the key file as an argument to ssh-add. For example,
ssh-add ~/.ssh/tatu-aws-keywould add the file ~/.ssh/tatu-aws-key.
Keys with Passphrases
If the key being added has a passphrase, ssh-add will run the ssh-askpass program to obtain the passphrase from the user. If the SSH_ASKPASS environment variable is set, the program given by that environment variable is used instead.
Some people use the SSH_ASKPASS environment variable in scripts to provide a passphrase for a key. The passphrase might then be hard-coded into the script, or the script might fetch it from a password vault. However, use of passphrases in this manner does not eliminate the need for proper key lifecycle management and rotation. Instead, we recommend looking at the PrivX On-Demand Access Manager on how to completely eliminate SSH keys in such applications and replace them by short-lived certificates issued on-demand based on centrally managed access policies.
ssh-add Command Line Options
ssh-add accepts the following command line options.
-c Causes a confirmation to be requested from the user every time the added identities are used for authentication. The confirmation is requested using ssh-askpass.
-D Deletes all identities from the agent.
-d Deletes the given identities from the agent. The private key files for the identities to be deleted should be listed on the command line.
-E Specifies the hash algorithm for displaying key fingerprints. Valid options include md5 and sha256.
-e pkcs11path Remove identities provided using a PKCS#11 interface, identified by the given path to its shared library. PKCS#11 interfaces are typically used for accessing keys on smartcards and hardware security modules (HSM).
-k When loading keys into or deleting keys from the agent, process plain private keys onmly, skipping certificates.
-L Lists public key parameters of all identities currently represented by the agent.
-l Lists fingerprints of all identities currently represented by the agent.
-s pkcs11path Adds identities provided by the PKCS#11 shared library at pkcs11path. This is can be used for adding keys on smartcards or in hardware security modules (HSM).
-t life Sets the maximum time the agent will keep the given key. After the timeout expires, the key will be automatically removed from the agent. The value is seconds, but can be suffixed for m for minutes, h for hours, d for days, or w for weeks.
-X Unlocks the agent. This asks for a password to unlock.
-x Locks the agent. This asks for a password; the password is required for unlocking the agent. When the agent is locked, it cannot be used for authentication.
