info > ssh-keygen(1)

man perldoc info pydoc3 ri search

Not found locally for ssh-keygen. Try Google search

SSH-KEYGEN(1) — OpenSSH authentication key utility

📛 NAME

ssh-keygen — OpenSSH authentication key utility

🚀 Quick Reference

Use Case	Command	Description
Generate default RSA key	ssh-keygen	Creates an RSA key pair with prompts for file and passphrase
Generate specific key type	ssh-keygen -t ed25519	Generate Ed25519 key pair
Generate key with comment	ssh-keygen -t rsa -C "my-key"	Create RSA key with a descriptive comment
Change passphrase	ssh-keygen -p -f ~/.ssh/id_rsa	Change the passphrase of an existing private key
Show fingerprint	ssh-keygen -l -f ~/.ssh/id_rsa.pub	Display fingerprint of a public key
Export public key	ssh-keygen -e -f ~/.ssh/id_rsa.pub	Export public key in RFC4716 format
Import key from other format	ssh-keygen -i -f key.pub -m PKCS8	Import a PKCS8 format public key
Generate host keys	ssh-keygen -A	Generate missing host keys for all types
Sign a user certificate	ssh-keygen -s ca_key -I key_id user_key.pub	Sign a public key with a CA key to create a certificate
Sign a host certificate	ssh-keygen -s ca_key -I key_id -h host_key.pub	Sign a host key with a CA key
Verify a signature	ssh-keygen -Y verify -f allowed_signers -I user -n namespace -s sigfile	Verify a detached signature created with ssh-keygen -Y sign
Sign a file	ssh-keygen -Y sign -f key -n namespace file	Cryptographically sign a file using SSH key
Generate DH moduli candidates	ssh-keygen -M generate -O bits=2048 moduli.candidates	Generate candidate Diffie-Hellman parameters
Screen DH moduli	ssh-keygen -M screen -f moduli.candidates moduli	Screen candidate DH parameters for safety
Create KRL (revoke keys)	ssh-keygen -k -f krl_file key.pub	Generate a Key Revocation List
Query KRL	ssh-keygen -Q -f krl_file key.pub	Test if a key is revoked in a KRL
Remove host from known_hosts	ssh-keygen -R hostname	Remove all keys for a hostname from known_hosts

📋 SYNOPSIS

ssh-keygen [-q] [-a rounds] [-b bits] [-C comment] [-f output_keyfile]
           [-m format] [-N new_passphrase] [-O option]
           [-t dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa]
           [-w provider] [-Z cipher]
ssh-keygen -p [-a rounds] [-f keyfile] [-m format] [-N new_passphrase]
           [-P old_passphrase] [-Z cipher]
ssh-keygen -i [-f input_keyfile] [-m key_format]
ssh-keygen -e [-f input_keyfile] [-m key_format]
ssh-keygen -y [-f input_keyfile]
ssh-keygen -c [-a rounds] [-C comment] [-f keyfile] [-P passphrase]
ssh-keygen -l [-v] [-E fingerprint_hash] [-f input_keyfile]
ssh-keygen -B [-f input_keyfile]
ssh-keygen -D pkcs11
ssh-keygen -F hostname [-lv] [-f known_hosts_file]
ssh-keygen -H [-f known_hosts_file]
ssh-keygen -K [-a rounds] [-w provider]
ssh-keygen -R hostname [-f known_hosts_file]
ssh-keygen -r hostname [-g] [-f input_keyfile]
ssh-keygen -M generate [-O option] output_file
ssh-keygen -M screen [-f input_file] [-O option] output_file
ssh-keygen -I certificate_identity -s ca_key [-hU] [-D pkcs11_provider]
           [-n principals] [-O option] [-V validity_interval]
           [-z serial_number] file ...
ssh-keygen -L [-f input_keyfile]
ssh-keygen -A [-a rounds] [-f prefix_path]
ssh-keygen -k -f krl_file [-u] [-s ca_public] [-z version_number]
           file ...
ssh-keygen -Q [-l] -f krl_file file ...
ssh-keygen -Y find-principals [-O option] -s signature_file -f
           allowed_signers_file
ssh-keygen -Y match-principals -I signer_identity -f allowed_signers_file
ssh-keygen -Y check-novalidate [-O option] -n namespace -s signature_file
ssh-keygen -Y sign [-O option] -f key_file -n namespace file ...
ssh-keygen -Y verify [-O option] -f allowed_signers_file -I
           signer_identity -n namespace -s signature_file
           [-r revocation_file]

📖 DESCRIPTION

ssh-keygen generates, manages and converts authentication keys for ssh(1). ssh-keygen can create keys for use by SSH protocol version 2.

The type of key to be generated is specified with the -t option. If invoked without any arguments, ssh-keygen will generate an RSA key.

ssh-keygen is also used to generate groups for use in Diffie-Hellman group exchange (DH-GEX). See the MODULI GENERATION section for details.

Finally, ssh-keygen can be used to generate and update Key Revocation Lists, and to test whether given keys have been revoked by one. See the KEY REVOCATION LISTS section for details.

Normally each user wishing to use SSH with public key authentication runs this once to create the authentication key in ~/.ssh/id_dsa, ~/.ssh/id_ecdsa, ~/.ssh/id_ecdsa_sk, ~/.ssh/id_ed25519, ~/.ssh/id_ed25519_sk or ~/.ssh/id_rsa. Additionally, the system administrator may use this to generate host keys.

Normally this program generates the key and asks for a file in which to store the private key. The public key is stored in a file with the same name but “.pub” appended. The program also asks for a passphrase. The passphrase may be empty to indicate no passphrase (host keys must have an empty passphrase), or it may be a string of arbitrary length. A passphrase is similar to a password, except it can be a phrase with a series of words, punctuation, numbers, whitespace, or any string of characters you want. Good passphrases are 10-30 characters long, are not simple sentences or otherwise easily guessable (English prose has only 1-2 bits of entropy per character, and provides very bad passphrases), and contain a mix of upper and lowercase letters, numbers, and non-alphanumeric characters. The passphrase can be changed later by using the -p option.

There is no way to recover a lost passphrase. If the passphrase is lost or forgotten, a new key must be generated and the corresponding public key copied to other machines.

ssh-keygen will by default write keys in an OpenSSH-specific format. This format is preferred as it offers better protection for keys at rest as well as allowing storage of key comments within the private key file itself. The key comment may be useful to help identify the key. The comment is initialized to “user@host” when the key is created, but can be changed using the -c option.

It is still possible for ssh-keygen to write the previously-used PEM format private keys using the -m flag. This may be used when generating new keys, and existing new-format keys may be converted using this option in conjunction with the -p (change passphrase) flag.

After a key is generated, ssh-keygen will ask where the keys should be placed to be activated.

🔧 Options

-A 🔑 Generate host keys for all types (rsa, dsa, ecdsa, ed25519) that don't already exist. If -f is specified, its argument is used as a prefix to the default path. -a rounds 🔒 Number of KDF rounds for private key encryption. Higher numbers = slower passphrase verification and stronger resistance to brute-force. Default: 16 rounds. -B 🔤 Show bubblebabble digest of specified key file. -b bits 📏 Number of bits in the key. RSA: min 1024, default 3072. DSA: exactly 1024. ECDSA: 256, 384, or 521. Ignored for ECDSA-SK, Ed25519, Ed25519-SK. -C comment 💬 Provide a new comment. -c ✏️ Change the comment in private and public key files. Prompts for file, passphrase, and new comment. -D pkcs11 📥 Download public keys from a PKCS#11 shared library. With -s, indicates a CA key resides in a PKCS#11 token. -E fingerprint_hash 🔐 Hash algorithm for key fingerprints. Valid: “md5”, “sha256”. Default: “sha256”. -e 📤 Export a private/public OpenSSH key to stdout in format specified by -m. Default export format: “RFC4716”. -F hostname | [hostname]:port 🔍 Search for a hostname in a known_hosts file. Works with hashed hostnames. May be combined with -H for hashed output. -f filename 📁 Specifies the filename of the key file. -g 🌐 Use generic DNS format when printing fingerprint resource records using -r. -H 🔒 Hash a known_hosts file — replaces all hostnames with hashed representations. Original content moved to .old suffix. -h 🖥️ Create a host certificate instead of a user certificate (when signing a key). -I certificate_identity 🆔 Specify the key identity when signing a public key. -i 📥 Import an unencrypted private/public key file in the format specified by -m and print OpenSSH-compatible key to stdout. Default import format: “RFC4716”. -K 🔑 Download resident keys from a FIDO authenticator. Keys written to current directory. -k 🚫 Generate a KRL (Key Revocation List) file. Revokes every key/certificate specified on the command line. -L 📄 Print the contents of one or more certificates. -l 👆 Show fingerprint of specified public key file. With -v, shows visual ASCII art. -M generate 🔢 Generate candidate Diffie-Hellman Group Exchange (DH-GEX) parameters. -M screen ✅ Screen candidate parameters for DH-GEX — tests for safe primes and acceptable group generators. -m key_format 📝 Specify key format for generation, import (-i), export (-e), or passphrase change (-p). Supported: “RFC4716”, “PKCS8”, “PEM”. -N new_passphrase 🔑🔒 Provides the new passphrase. -n principals 👥 Specify one or more principals (user/host names) for a certificate. Comma-separated. -O option ⚙️ Specify key/value options. Operation-specific. See CERTIFICATES, MODULI GENERATION, and FIDO key options below. -P passphrase 🔑 Provides the (old) passphrase. -p 🔄 Change the passphrase of a private key file. Prompts for file, old passphrase, and new passphrase (twice). -Q ✅ Test whether keys have been revoked in a KRL. With -l, prints KRL contents. -q 🔇 Silence ssh-keygen. -R hostname | [hostname]:port 🗑️ Remove all keys for a hostname from a known_hosts file. Useful for deleting hashed hosts. -r hostname 🌐 Print SSHFP fingerprint resource record for hostname. -s ca_key 📜 Certify (sign) a public key using the specified CA key. With KRL generation, specifies CA public key to revoke certificates by ID/serial. -t dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa 🔑 Key type to create. Also used for signature type when signing with RSA CA key. -U 🔑 Indicates CA key resides in ssh-agent(1) (used with -s). -u 🔄 Update a KRL — add keys to existing KRL rather than creating new one. -V validity_interval ⏱️ Specify validity interval for a certificate. Single time or two times separated by colon. -v 📢 Verbose mode. Multiple -v increases verbosity (max 3). -w provider 🔌 Path to library for FIDO authenticator-hosted keys. Overrides internal USB HID support. -Y find-principals 🔍 Find principal(s) associated with a signature's public key in an allowed signers file. -Y match-principals 🔍 Find principal matching the identity provided via -I in the allowed signers file. -Y check-novalidate ✅ Check that a signature has valid structure. Does not validate authorization. -Y sign ✍️ Cryptographically sign a file or data using an SSH key. Signatures written to .sig file. -Y verify ✅ Verify a signature generated with ssh-keygen -Y sign. -y 📤 Read a private OpenSSH format file and print public key to stdout. -Z cipher 🔐 Cipher for encrypting OpenSSH-format private key file. Default: “aes256-ctr”. -z serial_number 🔢 Serial number to embed in certificate. Prefix with ‘+’ to auto-increment. Default: 0.

🔑 FIDO Key Options

application 📝 Override default FIDO application string “ssh:”. Must begin with “ssh:”. challenge=path 🔐 Path to a challenge string for FIDO token during key generation. device 🔌 Explicitly specify a fido(4) device. no-touch-required 👆 Allow signatures without touch events (user presence). sshd(8) refuses these by default. resident 💾 Store key on the FIDO authenticator itself. Requires PIN on token. user 👤 Username for resident key, overriding empty default. verify-required 🔐 Require user verification for each signature. Currently PIN only. write-attestation=path 📝 Record attestation data from FIDO tokens at key generation time.

🔏 Signature Verification Options

hashalg=algorithm 🔐 Select hash algorithm for signing. Valid: “sha256”, “sha512”. Default: “sha512”. print-pubkey 🖨️ Print full public key to stdout after signature verification. verify-time=timestamp ⏱️ Specify a time for signature validation instead of current time. Format: YYYYMMDD or YYYYMMDDHHMM[SS].

🔢 MODULI GENERATION

ssh-keygen may be used to generate groups for the Diffie-Hellman Group Exchange (DH-GEX) protocol. Two-step process: candidate primes generated (fast, memory-intensive), then tested for suitability (CPU-intensive).

Generate candidates:

# ssh-keygen -M generate -O bits=2048 moduli-2048.candidates

Screen candidates:

# ssh-keygen -M screen -f moduli-2048.candidates moduli-2048

Screened DH groups may be installed in /etc/ssh/moduli.

⚙️ Moduli Generation/Screening Options

lines=number 📏 Exit after screening specified number of lines. start-line=line-number 📌 Start screening at specified line number. checkpoint=filename 💾 Write last processed line to file for resumable screening. memory=mbytes 🧠 Memory in MB for generating candidate moduli. start=hex-value 🎯 Start point (hex) for candidate generation. generator=value 🔢 Desired generator (2, 3, or 5) for testing. bits=bits 📏 Desired prime length in bits. prime-tests=number 🧪 Number of primality tests per candidate (default: 100).

📜 CERTIFICATES

ssh-keygen supports signing keys to produce certificates for user or host authentication. Certificates are signed by a Certification Authority (CA) key. Note: OpenSSH certificates are different from X.509 certificates.

Generate a user certificate:

$ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub

Generate a host certificate:

$ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub

Sign with CA key in PKCS#11 token:

$ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id user_key.pub

Sign with CA key in ssh-agent(1):

$ ssh-keygen -Us ca_key.pub -I key_id user_key.pub

Generate certificate for specific principals:

$ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
$ ssh-keygen -s ca_key -I key_id -h -n host.domain host_key.pub

🔏 User Certificate Options

clear 🧹 Clear all enabled permissions. critical:name[=contents] ⚠️ Include an arbitrary certificate critical option. Unknown critical options cause certificate refusal. extension:name[=contents] ➕ Include an arbitrary certificate extension. May be ignored by clients/servers that don't recognize it. force-command=command ⛓️ Force execution of a specific command instead of user-specified command. no-agent-forwarding 🚫 Disable ssh-agent(1) forwarding. no-port-forwarding 🚫 Disable port forwarding. no-pty 🚫 Disable PTY allocation. no-user-rc 🚫 Disable execution of ~/.ssh/rc. no-x11-forwarding 🚫 Disable X11 forwarding. permit-agent-forwarding ✅ Allow ssh-agent(1) forwarding. permit-port-forwarding ✅ Allow port forwarding. permit-pty ✅ Allow PTY allocation. permit-user-rc ✅ Allow execution of ~/.ssh/rc. permit-X11-forwarding ✅ Allow X11 forwarding. no-touch-required 👆 Do not require user presence demonstration (FIDO keys only). source-address=address_list 🌐 Restrict source addresses (CIDR format, comma-separated). verify-required 🔐 Require user verification (FIDO keys only).

Use -V to specify certificate validity lifetime. Certificates are valid from UNIX Epoch to distant future by default.

🚫 KEY REVOCATION LISTS

ssh-keygen manages OpenSSH format Key Revocation Lists (KRLs) — binary files specifying revoked keys/certificates.

Generate KRL:

$ ssh-keygen -k -f krl_file key.pub

Update KRL (add keys):

$ ssh-keygen -k -u -f krl_file key.pub

Query KRL:

$ ssh-keygen -Q -f krl_file key.pub

📝 KRL Specification Directives

serial: serial_number[-serial_number] 🔢 Revoke certificates by serial number (64-bit, decimal/hex/octal). Range supported with hyphen. id: key_id 🆔 Revoke certificates by key ID string. key: public_key 🔑 Revoke the specified key. sha1: public_key 🔐 Revoke key by SHA1 hash. sha256: public_key 🔐 Revoke key by SHA256 hash (not supported in OpenSSH < 7.9). hash: fingerprint 🔐 Revoke key by SHA256 fingerprint hash (not supported in OpenSSH < 7.9).

👤 ALLOWED SIGNERS

When verifying signatures, ssh-keygen uses an "allowed signers" file. Format per line: principals options key-type base64-key. Empty lines and lines starting with ‘#’ are ignored.

Options (case-insensitive, comma-separated):

cert-authority 📜 Key is accepted as a certificate authority — certificates signed by this CA may be accepted. namespaces=namespace-list 🏷️ Pattern-list of accepted namespaces for this key. valid-after=timestamp ⏱️ Key valid at or after this timestamp. Format: YYYYMMDD or YYYYMMDDHHMM[SS]. valid-before=timestamp ⏱️ Key valid at or before this timestamp.

Example allowed signers file:

# Comments allowed at start of line
user1@example.com,user2@example.com ssh-rsa AAAAX1...
# A certificate authority, trusted for all principals in a domain.
*@example.com cert-authority ssh-ed25519 AAAB4...
# A key that is accepted only for file signing.
user2@example.com namespaces="file" ssh-ed25519 AAA41...

🌍 ENVIRONMENT

SSH_SK_PROVIDER 🔌 Path to a library for loading FIDO authenticator-hosted keys, overriding built-in USB HID support.

📁 FILES

~/.ssh/id_dsa 🔑 DSA private key. ~/.ssh/id_ecdsa 🔑 ECDSA private key. ~/.ssh/id_ecdsa_sk 🔑 Authenticator-hosted ECDSA private key. ~/.ssh/id_ed25519 🔑 Ed25519 private key. ~/.ssh/id_ed25519_sk 🔑 Authenticator-hosted Ed25519 private key. ~/.ssh/id_rsa 🔑 RSA private key. Should not be readable by anyone but the user. Can be encrypted with a passphrase (128-bit AES). ~/.ssh/id_dsa.pub 🔓 DSA public key. ~/.ssh/id_ecdsa.pub 🔓 ECDSA public key. ~/.ssh/id_ecdsa_sk.pub 🔓 Authenticator-hosted ECDSA public key. ~/.ssh/id_ed25519.pub 🔓 Ed25519 public key. ~/.ssh/id_ed25519_sk.pub 🔓 Authenticator-hosted Ed25519 public key. ~/.ssh/id_rsa.pub 🔓 RSA public key. Contents should be added to ~/.ssh/authorized_keys on target machines. /etc/ssh/moduli 🔢 Contains Diffie-Hellman groups for DH-GEX. Format described in moduli(5).

📚 SEE ALSO

• ssh(1)
• ssh-add(1)
• ssh-agent(1)
• moduli(5)
• sshd(8)

The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006.

👥 AUTHORS

OpenSSH is a derivative of the original and free ssh 1.2.12 release by Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo de Raadt and Dug Song removed many bugs, re-added newer features and created OpenSSH. Markus Friedl contributed the support for SSH protocol versions 1.5 and 2.0.

SSH-KEYGEN(1) — OpenSSH authentication key utility 📛 NAME 🚀 Quick Reference 📋 SYNOPSIS 📖 DESCRIPTION 🔢 MODULI GENERATION 📜 CERTIFICATES 🚫 KEY REVOCATION LISTS 👤 ALLOWED SIGNERS 🌍 ENVIRONMENT 📁 FILES 📚 SEE ALSO 👥 AUTHORS