ssh-keygen
Generate SSH key pairs
TLDR
Generate a key interactively
Generate an ed25519 key with 32 key derivation function rounds and save the key to a specific file
Generate an RSA 4096-bit key with email as a comment
Remove the keys of a host from the known_hosts file (useful when a known host has a new key)
Retrieve the fingerprint of a key in MD5 Hex
Change the password of a key
Change the type of the key format (for example from OPENSSH format to PEM), the file will be rewritten in-place
Retrieve public key from secret key
SYNOPSIS
ssh-keygen [options]
Common usage examples:
ssh-keygen (interactive RSA key generation)
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa_new -C "user@host"
ssh-keygen -y -f ~/.ssh/id_rsa > ~/.ssh/id_rsa.pub
ssh-keygen -p -f ~/.ssh/id_rsa
PARAMETERS
-b bits
Specifies the number of bits in the key. For RSA keys, a minimum of 2048 bits is recommended, with 4096 being common. For DSA, 1024 bits is standard. ECDSA and Ed25519 have fixed sizes.
-t type
Specifies the type of key to create. Valid types include rsa, dsa, ecdsa, and ed25519. Ed25519 and ECDSA are generally preferred for modern security.
-f filename
Specifies the filename of the key file to generate or operate on. By default, keys are saved in ~/.ssh/id_rsa (or similar based on type).
-P passphrase
Provides the old passphrase for a key file. Used with -p to change a key's passphrase.
-N new_passphrase
Provides the new passphrase for a key file. Used with -p to set or change a key's passphrase.
-C comment
Provides a new comment for the key file. The comment is typically an identifier like 'user@host' and is stored within the public key.
-p
Changes the passphrase of a private key file. Requires either interactive input or -P and -N options.
-y
Reads a private OpenSSH format key file and prints the corresponding OpenSSH public key to standard output. Useful for extracting the public key part.
-l
Shows the fingerprint of a public key file. This is often used to verify key authenticity, displaying it as an MD5 or SHA256 hash.
-R hostname
Removes all keys belonging to hostname from a known_hosts file. Useful when a remote host's key changes.
-F hostname
Searches for a specified hostname in a known_hosts file and prints any matching entries. Helps verify if a host's key is already known.
-A
For each of the standard key types (rsa, ecdsa, ed25519), generate the host keys if they do not exist. Commonly used by system administrators to initialize host keys.
-q
Suppresses ssh-keygen's progress meters and warnings, making the output quieter. Useful in scripts.
DESCRIPTION
ssh-keygen is a utility for generating, managing, and converting authentication keys for the SSH protocol. Its primary use is to create cryptographic key pairs (public and private keys) for secure, passwordless login to remote systems.
It supports various key types including RSA, DSA, ECDSA, and Ed25519. Beyond key generation, ssh-keygen can perform operations such as changing key passphrases, converting key formats, displaying public key fingerprints, and managing host keys in known_hosts files. It is a fundamental tool for setting up and maintaining secure SSH access.
CAVEATS
Private Key Security: The private key must be kept absolutely secret and secure. Never share it.
Passphrase Importance: A strong passphrase encrypts the private key, adding a crucial layer of security, especially if the key is compromised.
File Permissions: Incorrect file permissions (e.g., 644 for private key) will prevent SSH from using the key. Private keys should be 600 (read/write by owner only), public keys 644.
Key Type Recommendations: Older key types like DSA are discouraged due to cryptographic weaknesses. Prefer Ed25519 or ECDSA, or RSA with at least 2048 (preferably 4096) bits.
KEY TYPES AND RECOMMENDATIONS
ssh-keygen supports several cryptographic key types:
RSA: Widely used, generally secure with 2048-bit or 4096-bit keys. Good compatibility.
DSA: Older, generally discouraged due to design flaws and fixed 1024-bit size. Avoid if possible.
ECDSA: Elliptic Curve Digital Signature Algorithm. More modern, offers similar security with smaller key sizes. Requires OpenSSL support.
Ed25519: An EdDSA variant. Considered highly secure and efficient, resistant to side-channel attacks. Recommended for new keys.
PASSPHRASES AND SSH-AGENT
Encrypting your private key with a strong passphrase adds a vital layer of security. However, repeatedly entering the passphrase can be cumbersome.
The ssh-agent(1) utility can be used to load your decrypted private key into memory once per session, allowing subsequent SSH connections to authenticate without re-entering the passphrase. This is a highly recommended practice for both security and convenience.
HOST KEY MANAGEMENT
When connecting to a new SSH server, its public host key is typically added to your ~/.ssh/known_hosts file. ssh-keygen can help manage this file:
Use -F hostname to check if a host's key is already known.
Use -R hostname to remove a host's key if it changes, preventing 'man-in-the-middle' warnings.
HISTORY
SSH (Secure Shell) was originally developed by Tatu Ylönen in 1995. ssh-keygen has been an integral component of the OpenSSH suite since its inception, providing the means to create and manage the cryptographic keys fundamental for secure, passwordless authentication. Its capabilities have expanded over time, incorporating newer, more robust cryptographic algorithms like ECDSA and Ed25519, and adapting to evolving security standards and best practices.
SEE ALSO
ssh(1), sshd(8), ssh-copy-id(1), ssh-agent(1), sshd_config(5)
