ssh-keygen
ssh-keygen is a command-line utility in the OpenSSH suite designed to generate, manage, and convert authentication keys for the Secure Shell (SSH) protocol version 2, enabling secure public key-based authentication for remote logins and file transfers.[1] Developed as part of OpenSSH, which originated from the OpenBSD project in 1999 as an open-source reimplementation of the original SSH software, ssh-keygen has become a standard tool for key management in Unix-like operating systems and has been integrated into Windows via OpenSSH for Windows.[2][3] The tool supports generating key pairs in various types, including RSA (with a default size of 3072 bits), ECDSA, ECDSA-SK (security key variant), Ed25519 (the default type for its efficiency and security), and Ed25519-SK, while DSA support has been deprecated due to vulnerabilities.[1] Key functionalities of ssh-keygen extend beyond generation to include changing passphrases on existing keys, modifying key comments, converting between formats such as OpenSSH (default for better protection), PEM, PKCS#8, and RFC 4716, displaying key fingerprints for verification, screening known hosts files, generating Diffie-Hellman groups for key exchange, and managing Key Revocation Lists (KRLs) to revoke compromised keys.[1] By default, generated private keys are stored in~/.ssh/id_<type> with corresponding public keys in ~/.ssh/id_<type>.pub, and users are prompted to set an optional passphrase to encrypt the private key, enhancing security against unauthorized access.[1] This comprehensive capability makes ssh-keygen essential for setting up secure, passwordless SSH access in both personal and enterprise environments.[4]
Introduction
Overview
ssh-keygen is a command-line utility within the OpenSSH suite designed for generating, managing, and converting pairs of public and private authentication keys used in the Secure Shell (SSH) protocol to enable passwordless authentication.[5] It supports the creation of key pairs in various formats suitable for SSH version 2, the current standard, allowing users to establish secure remote connections without transmitting passwords over the network.[6] Among its primary functions, ssh-keygen facilitates the addition of passphrases to protect private keys, modification of existing keys including type changes, and inspection of key details such as fingerprints for verification purposes.[5] As an integral component of OpenSSH, ssh-keygen is widely available on Unix-like operating systems including Linux and macOS, and has been integrated into Windows starting with version 10 build 1809 in October 2018, providing cross-platform compatibility for secure access.[7][8] It is commonly employed in development workflows, such as with Git for authenticating secure repository cloning and pushing over SSH without requiring repeated credential entry.[9] The tool is included in the latest OpenSSH release, version 10.2, distributed in October 2025, ensuring ongoing support for modern security practices across diverse environments.[7] In a typical workflow, a user invokes ssh-keygen to produce a private key file and its corresponding public key, which is then appended to the server's authorized_keys file for access permission; subsequent SSH client connections leverage the private key for seamless, encrypted authentication.[5] This process underpins secure remote administration, file transfers, and automated scripting in networked systems.[4]History
ssh-keygen was developed as part of the original Secure Shell (SSH) protocol implementation by Tatu Ylönen in 1995, following a password-sniffing incident on the Helsinki University of Technology network that prompted the creation of a secure alternative to tools like Telnet and rsh.[10] The tool enabled the generation of RSA keys for authentication in SSH-1, which was the sole supported protocol at the time and relied exclusively on RSA for public-key cryptography.[11] The open-source OpenSSH project, initiated in 1999 by the OpenBSD team as a free alternative to the proprietary SSH implementation, incorporated ssh-keygen from its early releases, with version 2.5 in 2001 introducing support for DSA keys alongside RSA for the emerging SSH-2 protocol.[12] SSH-2, standardized in 2006, marked a significant evolution by enhancing security through stronger key exchange and integrity mechanisms, while ssh-keygen adapted to generate keys for these improvements, phasing out SSH-1's RSA-only limitations by 2006 in most implementations.[13] Key milestones in ssh-keygen's development include the addition of Ed25519 support in OpenSSH 6.5 (2014), providing faster and more secure elliptic curve keys resistant to certain side-channel attacks. Ed25519 was made the default key type for ssh-keygen in OpenSSH 9.5 (October 2023) due to its efficiency and security advantages.[12] DSA keys were disabled by default in OpenSSH 7.0 (2015) due to vulnerabilities like weak random number generation, with full removal occurring in version 10.0 (April 2025).[12] FIDO/U2F hardware key support, via ecdsa-sk and ed25519-sk types, was introduced in OpenSSH 8.2 (2020), enabling security key authentication with options for resident keys and touch requirements.[12] Recent advancements focus on post-quantum resilience and deprecations: OpenSSH 9.0 (2022) set a post-quantum hybrid key exchange (sntrup761x25519-sha512) as the default for connections, though ssh-keygen's authentication key generation did not yet incorporate post-quantum algorithms.[12] OpenSSH 10.0 (April 2025) updated the default to the mlkem768x25519-sha256 hybrid post-quantum key exchange for connections, while ssh-keygen gained support for inspecting and generating keys with custom hash algorithms like SHA-256 for RSA, alongside improved FIDO2 enrollment handling.[12][14] Deprecations include discouraging RSA keys below 2048 bits since 2015 per NIST guidelines, reflected in ssh-keygen's default size increase to 3072 bits in OpenSSH 8.0 (2019), and the removal of SHA-1 signatures from default algorithms in OpenSSH 8.2 (2020), with further disabling in later versions like 8.8 (2021).[12] Platform expansion came with native OpenSSH integration in Windows 10 version 1809 (October 2018), allowing ssh-keygen to generate and manage keys directly on Windows without third-party tools, extending its use to Microsoft ecosystems.[8][15]Supported Key Types
Classical Algorithms
The Rivest-Shamir-Adleman (RSA) algorithm, introduced in 1977 by Ron Rivest, Adi Shamir, and Leonard Adleman, served as the foundational public-key cryptography method for SSH key generation in ssh-keygen, particularly as the default for many years across both SSH protocol versions 1 and 2. In the RSA key generation process, two large prime numbers p and q are selected, and the modulus n = p \times q is computed, along with Euler's totient \phi(n) = (p-1)(q-1). A public exponent e is chosen such that $1 < e < \phi(n) and \gcd(e, \phi(n)) = 1, and the private exponent d is derived to satisfy the equation e \cdot d \equiv 1 \pmod{\phi(n)}, ensuring the private key d can decrypt messages encrypted with the public key (n, e).[16] Since OpenSSH 7.8, ssh-keygen defaults to generating 3072-bit RSA keys for enhanced security against factoring attacks, though users can specify larger sizes like 4096 bits via the-b option. RSA keys maintain universal compatibility in SSH implementations due to their long-standing support and lack of deprecation.
The Digital Signature Algorithm (DSA), standardized by NIST in 1994 based on earlier 1991 proposals, was incorporated into ssh-keygen primarily for SSH protocol version 2 to provide an alternative to RSA amid patent concerns. DSA keys in ssh-keygen are fixed at 1024 bits, limiting their scalability compared to variable-length RSA, and the generation command ssh-keygen -t dsa produces a private key in PEM format alongside a public key in the SSH wire format for authentication. However, DSA's reliance on a per-signature random nonce k makes it particularly susceptible to vulnerabilities from weak random number generation, where predictable k values can expose the private key after just a few signatures. NIST deprecated 1024-bit DSA in its 2013 guidance (SP 800-131A Revision 1), recommending transition away by the end of 2013 due to insufficient security margins against modern computational threats.[17]
Historically, RSA dominated initial SSH-1 deployments for its robust encryption and signature capabilities, while DSA gained traction in early SSH-2 implementations as a patent-free option until RSA patents expired in 2000. Compatibility for DSA has progressively declined; OpenSSH disabled it by default in version 7.0 (2015) due to its weaknesses, and full removal occurred in OpenSSH 10.0 (2025), rendering DSA keys unusable in modern clients without legacy reconfiguration. For classical key generation, commands like ssh-keygen -t rsa -b 4096 or ssh-keygen -t dsa (prior to deprecation) output files suitable for SSH authentication, with the private key protected by optional passphrase encryption in PEM or OpenSSH formats.
Modern and Elliptic Curve Algorithms
ssh-keygen supports modern elliptic curve-based algorithms for generating more efficient and secure key pairs compared to classical methods, with a focus on ECDSA, ECDSA-SK, Ed25519, and Ed25519-SK. These algorithms leverage the mathematical properties of elliptic curves to achieve equivalent security levels with significantly smaller key sizes, reducing computational overhead and storage requirements.[18] ECDSA, or Elliptic Curve Digital Signature Algorithm, utilizes standardized NIST curves such as P-256, P-384, and P-521 for key generation. To create an ECDSA key pair, the commandssh-keygen -t ecdsa -b 256 specifies the type and bit length, where the -b option selects from the supported curve sizes corresponding to approximately 128, 192, or 256 bits of security. These keys are notably smaller than equivalent-strength RSA keys—for instance, a 256-bit ECDSA key provides security comparable to a 3072-bit RSA key—making them suitable for resource-constrained environments. However, ECDSA implementations are susceptible to flaws such as nonce reuse, where repeating the random nonce across signatures can compromise the private key, as demonstrated in real-world incidents like the Sony PlayStation 3 breach.[19][18][20]
Ed25519, based on the Edwards-curve Digital Signature Algorithm, employs a fixed 256-bit key size and is generated using ssh-keygen -t ed25519, with the -b option ignored due to the fixed length. It is the recommended default for new keys in modern OpenSSH implementations owing to its superior performance and security profile. Signing operations with Ed25519 are significantly faster—up to 20 times in cycle counts compared to ECDSA on NIST P-256—translating to 2-3 times faster practical signing speeds in typical SSH scenarios, while verification remains efficient. Ed25519's design uses deterministic nonce generation derived from the private key and message, resisting side-channel attacks and nonce reuse vulnerabilities that could compromise the key from past signatures, unlike random nonces in ECDSA.[19][21][20]
The mathematics underlying Ed25519 key generation derives from Curve25519, performing scalar multiplication on the twisted Edwards curve defined by the equation y^2 = x^3 + 486662 x^2 + x over the finite field \mathbb{F}_p where p = 2^{255} - 19. This curve selection ensures high-speed arithmetic and provable security properties without reliance on patented algorithms, unlike some aspects of earlier elliptic curve methods. While ECDSA remains supported for compatibility, Ed25519 is preferred for new deployments due to its balance of speed, security, and simplicity. Both algorithms are exclusively compatible with the SSH-2 protocol. The SK variants (ECDSA-SK and Ed25519-SK) provide hardware-backed options generated with ssh-keygen -t ecdsa-sk or -t ed25519-sk.[20][20]
Command Syntax and Options
Basic Usage
Thessh-keygen utility is invoked with the general syntax ssh-keygen followed by optional flags such as [-q] for quiet mode, [-b bits] to specify key size in bits, [-t type] to select the key algorithm type, [-f file] to set the output file path, [-C comment] to add a descriptive comment, and [-N passphrase] to provide a passphrase non-interactively.[1]
For basic key pair generation, the command ssh-keygen -t ed25519 creates an Ed25519 key pair, prompting the user for a file location (defaulting to ~/.ssh/id_ed25519 for the private key and ~/.ssh/id_ed25519.pub for the public key) and an optional passphrase for encryption.[1] If no type is specified, ssh-keygen defaults to Ed25519 keys since OpenSSH version 9.5 released in October 2023, due to their compact size and strong security properties established in RFC 8709 and supported since OpenSSH 6.5.[22]
The generated output consists of a private key file, which must remain confidential and is never shared, and a corresponding public key file, which can be distributed to remote servers by appending its contents to the server's ~/.ssh/authorized_keys file to enable passwordless authentication.[1]
Simple management tasks include changing a key's passphrase with ssh-keygen -p, which prompts for the old passphrase, a new one, and confirmation while optionally specifying the key file with -f; or removing a host's entry from the known_hosts file using ssh-keygen -R hostname to clear cached host keys, such as after a server's key change.[1]
To support non-interactive scripting, the -q flag enables quiet mode, suppressing prompts and output except for errors, while the default Ed25519 type in modern OpenSSH versions reduces the need for explicit -t specification in basic scenarios.[1][22]
A typical workflow begins with generating a key pair via ssh-keygen -t ed25519, followed by copying the public key to a remote server using ssh-copy-id user@hostname (which appends the key to the server's authorized_keys after password authentication), and verifying access with ssh -i ~/.ssh/id_ed25519 user@hostname to connect using the private key.[1][23]
Key Generation and Management Options
ssh-keygen provides a range of command-line options to customize the generation, modification, and inspection of SSH keys, allowing users to specify key types, sizes, file locations, and security parameters during creation or management. These options enable flexible key handling while adhering to modern cryptographic standards, with defaults optimized for security and compatibility.[1] The-t flag selects the key type during generation, supporting ecdsa, ecdsa-sk, ed25519, ed25519-sk, or rsa, where -sk variants indicate security key (FIDO/U2F) backed keys for enhanced hardware protection; DSA support was removed in OpenSSH 10.0 due to its weaknesses, with modern deployments favoring RSA, ECDSA, or Ed25519; the default type is ed25519 for its efficiency and fixed 256-bit security level.[1][24][25]
Key size and strength are controlled via the -b flag, specifying bit lengths such as 1024, 2048, 3072, or 4096 for RSA and ECDSA keys, with RSA defaulting to 3072 bits and ECDSA to 256, 384, or 521 bits corresponding to NIST curves; Ed25519 keys use a fixed size and ignore this option. Larger bit lengths increase computational resistance to attacks but may impact performance, so 3072+ bits for RSA is recommended for long-term use.[1]
File handling options include -f to specify a custom path for the output or input key file, overriding defaults like ~/.ssh/id_<type>, and -C to add a comment such as "user@host-2025" for metadata like identification or generation date, which aids in key organization without affecting cryptography.[1]
Passphrase management uses -N to set a new passphrase directly (e.g., for batch mode without prompts) and -P to provide an existing passphrase, such as -P "" for no passphrase, though the latter is insecure and exposes keys to theft risks if files are compromised. Passphrases should combine uppercase, lowercase, numbers, and symbols for strength, as lost ones require regenerating keys.[1]
Additional generation flags encompass -o to enforce the new OpenSSH private key format, introduced in 2014 with bcrypt-based key derivation for stronger passphrase protection and better comment preservation compared to legacy PEM. The -a option sets key derivation function (KDF) rounds, defaulting to 16 for Ed25519 and adjustable (e.g., -a 32) to heighten resistance against brute-force attacks on passphrases.[1][25]
For key management, -y reads a private key file and outputs the corresponding public key to stdout, useful for extracting publics without manual editing. The -l flag displays a key's fingerprint, defaulting to SHA256 hash (e.g., SHA256:abc123...) for verification, while -B produces a bubblebabble-encoded digest for human-readable, error-resistant key identification.[1]
Version-specific enhancements include -K (with -w provider for the library path, e.g., -w /path/to/lib) in OpenSSH 8.9 and later, which facilitates FIDO PIN handling and key enrollment from hardware authenticators. As of OpenSSH 10.2 (released October 2025), the supported options and defaults remain consistent with prior versions, emphasizing modern key types.[1][26][12]
Key Files and Storage
Default Locations and Permissions
SSH keys generated byssh-keygen are stored by default in the user's home directory under a .ssh subdirectory, which is created automatically if it does not exist.[1] The default filenames for private keys include id_rsa for RSA, id_ecdsa for ECDSA, and id_ed25519 for Ed25519, with corresponding public keys appended with .pub, such as id_rsa.pub.[1] These locations ensure that keys are isolated per user for security.[27]
On the server side, public keys for authentication are appended to the ~/.ssh/authorized_keys file, where each key occupies one line, optionally preceded by space-separated options like from="192.168.1.0/24" to restrict access by IP address or network.[28] This file allows multiple keys to be managed centrally for a user account.[28]
Strict file permissions are enforced to prevent unauthorized access. The .ssh directory must have permissions of 0700 (owner read, write, execute only), private key files require 0600 (owner read/write only), and the authorized_keys file should be 0600 or 0644 but not writable by group or others; sshd will refuse authentication if these are lax unless StrictModes is disabled.[27] Similarly, ssh ignores private keys with overly permissive settings, issuing warnings like "Permissions for 'id_rsa' are too open."[27]
On Windows systems using OpenSSH, the default location mirrors Unix-like systems at %USERPROFILE%\.ssh\, with equivalent strict permissions enforced via NTFS ACLs: the .ssh folder accessible only by the user, and private keys readable/writable solely by the owner.[3]
Users can override default paths with the -f option in ssh-keygen, specifying a custom filename, but the resulting files must still adhere to the same permission requirements to avoid authentication failures.[1]
For client-side host verification, ssh-keygen -H hashes hostnames and addresses in the ~/.ssh/known_hosts file to enhance privacy by obscuring visited hosts, maintaining the default location while applying the same 0600 permissions.[1][27]
File Formats and Contents
ssh-keygen generates public keys in a compact, single-line ASCII format suitable for use in files like authorized_keys. This format begins with the key type identifier (e.g., "ssh-rsa" for RSA keys or "ssh-ed25519" for Ed25519 keys), followed by a space, then the base64-encoded representation of the public key blob, and optionally ends with a space and a comment such as the user's hostname or email.[6] The public key blob is the binary serialization of the key data in SSH wire format, which for RSA consists of the exponent e and modulus n as multi-precision integers, while for Ed25519 it is simply the 32-byte public point on the curve. This base64 encoding uses the standard alphabet without line breaks, ensuring the entire public key fits on one line.[5] Private keys produced by ssh-keygen can be in two primary formats: the legacy PEM format or the newer OpenSSH format. The PEM format, selected via the-m PEM option, uses base64-encoded DER (Distinguished Encoding Rules) ASN.1 structures wrapped in headers like -----BEGIN [RSA](/page/RSA) PRIVATE KEY----- and -----END [RSA](/page/RSA) PRIVATE KEY-----, compatible with tools like OpenSSL.[5] In contrast, the default OpenSSH format (enabled with -o), introduced in OpenSSH 6.5, begins with -----BEGIN OPENSSH PRIVATE KEY----- and employs a structured binary layout prefixed by the magic string "openssh-key-v1\0". This format supports multiple keys per file, uses bcrypt as the key derivation function (PBKDF) for passphrase protection with configurable salt and rounds, and encrypts the private key data using AES in CBC or GCM mode if a passphrase is set.[29] Unencrypted private keys use "none" for cipher and KDF, allowing direct access to the contents.[29]
The contents of private key files vary by algorithm but include all components necessary for key operations, along with an optional trailing comment. For RSA private keys, both PEM and OpenSSH formats contain the modulus n, public exponent e, private exponent d, prime factors p and q, and the CRT exponents d_p, d_q, and inverse q_inv.[5] ECDSA and Ed25519 private keys include the curve parameters (e.g., "nistp256" for secp256r1), the private scalar or seed, and the corresponding public key point. Ed25519 specifically uses a 32-byte seed from which the private scalar is generated.[29] In the OpenSSH format, these are stored as binary blobs within an encrypted or unencrypted list, padded to the cipher block size, and followed by per-key comments.[29]
ssh-keygen supports conversion between formats using the -m option, such as exporting to PEM (PKCS#1), PKCS#8, or RFC 4716 (SSH2 public key file format), and importing from compatible sources like PuTTY or other SSH implementations.[5] For instance, -e -f key.pub -m RFC4716 outputs a multi-line PEM-like structure with headers for interoperability.[30]
The authorized_keys file, typically located in ~/.ssh/authorized_keys, stores multiple public keys in concatenated single-line format, one per line, for server authentication. Each line may prepend options in the form option=value (e.g., command="script.sh", no-port-forwarding), followed by optional principals, the key type, base64 blob, and comment; blank lines and comments starting with # are ignored.
Fingerprints of keys, used for verification, are computed by ssh-keygen with the -l option on a key file and output as hexadecimal or base64 strings. By default, it uses SHA-256 (per RFC 6594), but MD5 can be specified with -E [md5](/page/MD5); for example, ssh-keygen -l -f id_rsa displays 256 SHA256:abc123... user@host ([RSA](/page/RSA)).[5][31]
Security Considerations
Passphrase Protection
When generating an SSH key pair withssh-keygen, users are prompted interactively for a passphrase to encrypt the private key file, or it can be specified non-interactively using the -N option. An empty passphrase can be provided to skip encryption entirely, resulting in an unencrypted private key that remains usable but offers no additional protection beyond file permissions.[19]
The passphrase serves as input to a key derivation function (KDF) that generates encryption keys for the private key file. In the traditional (legacy) format, compatible with older OpenSSH versions and specified via the -m PEM option, the private key is encrypted using AES-128-CBC with a simple, single-iteration MD5-based KDF (EVP_BytesToKey) that provides limited resistance to brute-force attacks.[32] In contrast, the newer OpenSSH format—enabled by default since OpenSSH 7.8 in 2018 or explicitly via the -o option—employs AES-256-CBC (or configurable ciphers like the current default aes256-ctr) for encryption, paired with a more robust bcrypt_pbkdf KDF. This KDF incorporates a random 16-byte salt and a configurable number of rounds (default 16, adjustable via the -a flag), where higher rounds exponentially increase computational cost to deter offline attacks; for example, the default equates to approximately 2^{10} bcrypt operations for enhanced security. The derived key is computed as derived_key = bcrypt_pbkdf(passphrase, salt, rounds, key_length, salt_length), providing significantly better protection against dictionary and brute-force attempts compared to the legacy method.[33][19][34]
Upon attempting to use an encrypted private key, the SSH client (ssh) prompts the user for the passphrase to decrypt it in memory for the authentication session. To avoid repeated entry, the unlocked key can be added to ssh-agent for caching during the session, configurable via the AddKeysToAgent yes directive in ssh_config.
Weak passphrases in either format remain susceptible to dictionary attacks, especially in the legacy setup due to its inefficient KDF, potentially allowing recovery of the key if the file is compromised. Omitting a passphrase entirely exposes the private key to immediate use by anyone gaining file access, underscoring the importance of strong passphrase selection despite agent caching conveniences.[33][19]
Best Practices for Key Management
When generating SSH keys with ssh-keygen, it is recommended to prefer Ed25519 keys due to their strong security properties, compact size, and efficient performance compared to older algorithms.[1] Ed25519 provides equivalent security to a roughly 3000-bit RSA key while resisting certain side-channel attacks that affect other elliptic curve variants.[4] For environments requiring compatibility with legacy systems, use RSA keys of at least 3072 bits, as this size meets current security standards without excessive computational overhead.[1] DSA keys should be avoided entirely, as they are deprecated and no longer supported in modern OpenSSH versions, while ECDSA is supported but inferior to Ed25519 in terms of security margins and resistance to implementation flaws.[1] Key rotation is a critical practice to limit the impact of potential compromises, with recommendations to generate new keys periodically (e.g., annually, based on organizational policy) or immediately following any suspected breach.[35] To rotate, use ssh-keygen with the appropriate type, such asssh-keygen -t ed25519 -C "new-2025", then distribute the new public key to authorized_keys files on target hosts and revoke old keys by removing them from those files.[4] For FIDO2 hardware keys, revocation can be performed using ssh-keygen -K to manage credentials on the token.[1] This process ensures that access is promptly restricted without disrupting ongoing operations, aligning with NIST guidelines for credential lifecycle management.[35]
Regular auditing helps detect weak or unauthorized keys by computing fingerprints with ssh-keygen -l -E sha256 on public key files, which generates a verifiable hash for comparison against known values.[1] To scan remote hosts for potential weak keys or mismatches, employ ssh-keyscan to collect and verify host fingerprints, ensuring they match expected values stored in known_hosts. These steps facilitate proactive identification of anomalies, such as duplicated or expired keys, as part of routine security hygiene.[35]
For secure storage, leverage ssh-agent to cache passphrases in memory, reducing the need for repeated entry while adding keys with a lifetime limit via ssh-add -t 1h to prevent indefinite exposure.[36] Private keys should be backed up in encrypted form and stored offline, such as on removable media, to protect against theft or system compromise.[37] Always maintain strict file permissions (e.g., 600 for private keys) in the default ~/.ssh/ directory.[1]
Common pitfalls include accidentally committing private keys to version control repositories, which can expose them to unauthorized access; always use .gitignore rules to exclude id_* files without .pub extensions.[37] Assign unique comments to keys during generation (e.g., via the -C option) to track ownership and purpose, aiding in audits.[1] Once key-based authentication is operational, disable password authentication in sshd_config by setting PasswordAuthentication no and restarting the service to eliminate weaker fallback methods.
As of 2025, with the release of OpenSSH 10.0, organizations should rotate to configurations supporting post-quantum key exchange algorithms by default, such as those enabled via KexAlgorithms to mitigate "harvest now, decrypt later" threats from quantum adversaries.[38] Classical key types like RSA and ECDSA remain vulnerable to quantum attacks, so monitor advisories for emerging post-quantum signing algorithms and plan migrations accordingly.[12]
Advanced Features
FIDO2 and Hardware Key Support
Support for FIDO2 and hardware security keys was introduced in OpenSSH 8.2, released in February 2020, enabling the generation of keys backed by FIDO/U2F authenticators such as YubiKeys.[39] These keys use specialized types, includinged25519-sk (based on the Ed25519 elliptic curve algorithm) and ecdsa-sk (using ECDSA over the NIST P-256 curve), which integrate with hardware tokens to perform cryptographic operations without exposing private keys. The -t option in ssh-keygen specifies these types, for example, ssh-keygen -t ed25519-sk prompts the user to insert and touch the device during generation.
Key generation for resident keys, which are stored directly on the hardware device, employs options like -O [resident](/page/Resident) to persist the key handle on the authenticator and -O verify-required to mandate user verification (such as a PIN or biometric touch) for each signature operation. During the process, ssh-keygen interacts with the attached FIDO2 device via libraries like libfido2, generating a key pair where the private key remains confined to the hardware—never leaving the device—and the public key is extracted for placement in files like authorized_keys.[39] For instance, running ssh-keygen -t ed25519-sk -O [resident](/page/Resident) -O verify-required requires device insertion, user touch confirmation, and optional PIN entry, resulting in a private key file containing only metadata (the key handle) that is passphrase-protected on disk. Multiple credentials can be enrolled on a single device, allowing support for various applications or users.[40]
To manage resident keys, the -K option imports them from a specified device path, downloading key handles to the current directory for use with SSH clients; for example, ssh-keygen -K /dev/hidraw0 lists and retrieves available keys. Additional options include -O applications=ssh to set the FIDO application ID specifically for SSH, ensuring compatibility with the protocol's credential requirements. The resulting setup enhances security by requiring physical interaction, rendering the keys phishing-resistant through bound user verification that ties authentication to the specific relying party. If the device supports PIN protection, no additional passphrase is needed on the local key file, simplifying management while maintaining strong safeguards.[39]
In OpenSSH 10.0, released on April 9, 2025, improvements include a work-in-progress tool for verifying FIDO attestation blobs during enrollment (regress/misc/ssh-verify-attestation), providing better logging and validation of hardware authenticity to aid in auditing key generation processes.[12] Additionally, compatibility with hybrid post-quantum key exchange algorithms, such as the default mlkem768x25519-sha256, extends to FIDO2 sessions, combining classical elliptic curve methods with quantum-resistant mechanisms for future-proof authentication.[12][38] In OpenSSH 10.2, released on October 10, 2025, ssh-keygen fixes include proper CA signing operations when the CA key is held in a FIDO token and improved download of keys from PKCS#11 tokens, enhancing reliability for hardware-backed key management.[12] These enhancements ensure that hardware-backed keys align with evolving cryptographic standards without compromising performance or usability.[38]
Key Inspection and Conversion
ssh-keygen provides several options for inspecting the properties of existing SSH keys without modifying them. The-l option displays key details such as the number of bits, fingerprint (using SHA256 by default), and key type when given a private or public key file with the -f flag. For example, running ssh-keygen -l -f ~/.ssh/id_rsa outputs the key's size, MD5 and SHA256 fingerprints, and random art visualization if verbose mode (-v) is enabled. This is useful for verifying key strength or matching fingerprints during authentication setup.[19]
To extract the public key from a private key file, the -y option reads the private key and prints the corresponding public key to standard output, requiring the -f flag to specify the private key path; for instance, ssh-keygen -y -f ~/.ssh/id_rsa outputs the public key in OpenSSH format. Additionally, the -L option prints the contents of SSH certificates, including validity periods, serial numbers, and principal names, aiding in certificate management and validation.[19]
For key conversion, ssh-keygen supports changing passphrases and formats using the -p option, which prompts for the old passphrase and a new one while optionally converting the output format via the -m flag (e.g., to PEM or PKCS#8). The -m option alone specifies formats like RFC4716 (SSH.com format) during generation or conversion, ensuring compatibility across different SSH implementations. The -i option imports unencrypted keys in RFC4716 format (including PuTTY's .ppk for RSA keys) and outputs an OpenSSH-compatible version, facilitating migration from tools like PuTTY. An example export to PKCS#8 is ssh-keygen -e -m PKCS8 -f id_rsa.pub, which converts the public key to PEM-encoded PKCS#8 format. Supported output formats include PEM, PKCS#8, and OpenSSH proprietary, allowing interoperability with libraries like OpenSSL.[19]
Advanced inspection features include the -r option, which generates DNS SSHFP resource records from a public key for a given hostname; since OpenSSH 10.1 (released October 6, 2025), it produces only SHA256 records by default, with SHA1 records deprecated and ignored due to security weaknesses.[12] For smartcard keys, the -D option downloads public keys from a PKCS#11 token or reader, enabling inspection of hardware-stored credentials without extraction. These tools support use cases like verifying key integrity after backups—by recomputing fingerprints—or preparing DNS records for host key verification in automated deployments.[12][19]
However, ssh-keygen has limitations in conversion capabilities; it cannot transform between incompatible key types, such as converting an RSA key to Ed25519, as this would require regenerating the key pair with the desired algorithm. Conversions are restricted to format changes within the same key type and algorithm.[19]