How to use the command ssh-keygen (with examples)
ssh-keygen is a command-line utility used for generating, configuring, and managing SSH keys. These keys are primarily used for secure shell protocol (SSH) connections, providing a means of encrypting communications while allowing for password-less logins between systems. By using SSH keys, you can enhance security, reduce the risk of brute-force attacks, and improve the user experience by eliminating the need to enter passwords repeatedly.
Use case 1: Generate a key interactively
Code:
ssh-keygen
Motivation:
Running ssh-keygen without any options is the simplest and most interactive way of creating a pair of SSH keys. This approach is suitable when you want to quickly generate a key with default settings and provides prompts to guide you through the process. It’s great for beginners or when you do not require specific customizations.
Explanation:
ssh-keygen: This is the command invoked to start the key generation process. Without additional arguments, it defaults to generating an RSA key pair and uses typical settings for security.
Example output:
Generating public/private rsa key pair.
Enter file in which to save the key (/home/username/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/username/.ssh/id_rsa.
Your public key has been saved in /home/username/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:ThisIsAnExampleOfAFingerprint username@hostname
The key's randomart image is:
+---[RSA 3072]----+
| .. |
| o o . |
| .. . * ..E*+. |
|. o o.o.o+*.o. |
|. . ..Soo . |
| o o. |
| . . ... |
| ...o o. |
| . .. + |
+----[SHA256]-----+
Use case 2: Generate an ed25519 key with 32 key derivation function rounds and save the key to a specific file
Code:
ssh-keygen -t ed25519 -a 32 -f ~/.ssh/filename
Motivation:
Using the ed25519 algorithm is often preferred for its speed and strong security properties. Specifying key derivation function (KDF) rounds strengthens the protection of the private key if it is encrypted. You might choose this use case if you need a highly secure key stored in a specific location.
Explanation:
-t ed25519: Specifies the type of key to create. ed25519 is a modern elliptic curve algorithm that offers high security at smaller key sizes.-a 32: Sets the number of KDF rounds. This makes it computationally harder to crack the passphrase.-f ~/.ssh/filename: Designates the filename where the private key will be saved.
Example output:
Generating public/private ed25519 key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/username/.ssh/filename.
Your public key has been saved in /home/username/.ssh/filename.pub.
The key fingerprint is:
SHA256:SampleFingerprint username@hostname
The key's randomart image is:
+--[ED25519 256]--+
| . ooo+. |
| o o ..=.. |
|o * * + . |
| + * * o |
| . = oS. |
| o . |
| E.. o |
| ..o+ |
| .o. |
+----[SHA256]-----+
Use case 3: Generate an RSA 4096-bit key with email as a comment
Code:
ssh-keygen -t rsa -b 4096 -C "comment|email"
Motivation:
Generating an RSA key with an increased bit size of 4096 provides enhanced security due to the increased complexity of the key. This can be especially important for environments requiring stringent security standards. Adding a comment, such as an email address, can help in identifying and organizing multiple keys.
Explanation:
-t rsa: Specifies the RSA algorithm for key generation.-b 4096: Sets the key to be 4096 bits long, significantly improving security over the default 2048-bit size.-C "comment|email": Adds a comment to the key file, often your email or a descriptive string, aiding in key management.
Example output:
Generating public/private rsa key pair.
Enter file in which to save the key (/home/username/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/username/.ssh/id_rsa.
Your public key has been saved in /home/username/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:AnotherFingerprint comment|email
The key's randomart image is:
+---[RSA 4096]----+
| |
| .o+ ooo |
| .. =-Eo |
| o +o.o |
| o.S o . |
| ... |
| .= |
| . *= |
| o..@ |
+----[SHA256]-----+
Use case 4: Remove the keys of a host from the known_hosts file
Code:
ssh-keygen -R remote_host
Motivation:
Occasionally, the SSH keys for a known host might change—perhaps due to a server rebuild or reconfiguration. Continued attempts to connect to the host will result in a warning and potentially the connection being blocked. You use this command to remove the old key entry and allow trust to be re-established with the host.
Explanation:
-R remote_host: Specifies the removal of all keys associated with the specified host from the known_hosts file.
Example output:
# Host remote_host found: line 12
/Users/username/.ssh/known_hosts updated.
Original contents retained as /Users/username/.ssh/known_hosts.old
Use case 5: Retrieve the fingerprint of a key in MD5 Hex
Code:
ssh-keygen -l -E md5 -f ~/.ssh/filename
Motivation:
Viewing the fingerprint of an SSH key helps verify its integrity and authenticity, often essential for confirming the correct key when troubleshooting or setting up new secure connections. Selecting the MD5 format is useful when interoperating with systems or processes that use this hashing algorithm.
Explanation:
-l: Lists the fingerprint of the specified private key or public key.-E md5: Specifies MD5 as the hashing algorithm to use for generating the key’s fingerprint.-f ~/.ssh/filename: Points to the file that contains the private or public key for which the fingerprint is to be retrieved.
Example output:
2048 MD5:aa:bb:cc:dd:ee:ff:gg:hh:ii:jj:kk:ll:mm:nn:oo:ss filename (RSA)
Use case 6: Change the password of a key
Code:
ssh-keygen -p -f ~/.ssh/filename
Motivation:
You might need to update the passphrase on an SSH key to enhance security or comply with updated security policies. Changing the passphrase ensures that the key retains its security even if the old passphrase has been compromised.
Explanation:
-p: Prompts for a new passphrase to be associated with the key.-f ~/.ssh/filename: Indicates the file location of the key whose passphrase you wish to change.
Example output:
Enter old passphrase:
Enter new passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved with the new passphrase.
Use case 7: Change the type of the key format
Code:
ssh-keygen -p -N "" -m PEM -f ~/.ssh/OpenSSH_private_key
Motivation:
In some cases, specific systems or applications require keys in a particular format, such as PEM. Converting keys to the necessary format ensures compatibility. This command helps you convert and save the private key in the desired format.
Explanation:
-p: Starts the process of changing a key’s properties.-N "": Assigns no passphrase to the key (an empty string).-m PEM: Converts the key to PEM format.-f ~/.ssh/OpenSSH_private_key: Indicates the private key file that should be converted.
Example output:
Key has been saved with no passphrase.
Use case 8: Retrieve public key from secret key
Code:
ssh-keygen -y -f ~/.ssh/OpenSSH_private_key
Motivation:
Sometimes, only the private key is available, and the corresponding public key is missing or needed for distribution. This command retrieves the public key directly from the private key, facilitating tasks such as setting up new trusted systems or servers.
Explanation:
-y: Outputs the public key.-f ~/.ssh/OpenSSH_private_key: Points to the private key file used to derive the public key.
Example output:
ssh-rsa AAAAB3... rest of public key ... user@hostname
Conclusion:
ssh-keygen is a powerful and versatile tool crucial for managing SSH keys and enhancing system security through encrypted communications. The above use cases provide valuable insight into various scenarios where ssh-keygen can be leveraged to perform key generation, management, and conversion tasks, all of which are essential for secure and efficient server operations. By understanding and applying these use cases, users can significantly improve their system’s security posture and operational efficiency.
