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, as seen in /etc/rc.
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.
The options are as follows:
-A For each of the key types (rsa, dsa, ecdsa and ed25519) for
which host keys do not exist, generate the host keys with
the default key file path, an empty passphrase, default
bits for the key type, and default comment. If -f has also
been specified, its argument is used as a prefix to the
default path for the resulting host key files. This is
used by /etc/rc to generate new host keys.
-a rounds
When saving a private key, this option specifies the number
of KDF (key derivation function, currently bcrypt_pbkdf(3))
rounds used. Higher numbers result in slower passphrase
verification and increased resistance to brute-force
password cracking (should the keys be stolen). The default
is 16 rounds.
-B Show the bubblebabble digest of specified private or public
key file.
-b bits
Specifies the number of bits in the key to create. For RSA
keys, the minimum size is 1024 bits and the default is 3072
bits. Generally, 3072 bits is considered sufficient. DSA
keys must be exactly 1024 bits as specified by FIPS 186-2.
For ECDSA keys, the -b flag determines the key length by
selecting from one of three elliptic curve sizes: 256, 384
or 521 bits. Attempting to use bit lengths other than
these three values for ECDSA keys will fail. ECDSA-SK,
Ed25519 and Ed25519-SK keys have a fixed length and the -b
flag will be ignored.
-C comment
Provides a new comment.
-c Requests changing the comment in the private and public key
files. The program will prompt for the file containing the
private keys, for the passphrase if the key has one, and
for the new comment.
-D pkcs11
Download the public keys provided by the PKCS#11 shared
library pkcs11. When used in combination with -s, this
option indicates that a CA key resides in a PKCS#11 token
(see the CERTIFICATES section for details).
-E fingerprint_hash
Specifies the hash algorithm used when displaying key
fingerprints. Valid options are: 'md5' and 'sha256'. The
default is 'sha256'.
-e This option will read a private or public OpenSSH key file
and print to stdout a public key in one of the formats
specified by the -m option. The default export format is
'RFC4716'. This option allows exporting OpenSSH keys for
use by other programs, including several commercial SSH
implementations.
-F hostname | [hostname]:port
Search for the specified hostname (with optional port
number) in a known_hosts file, listing any occurrences
found. This option is useful to find hashed host names or
addresses and may also be used in conjunction with the -H
option to print found keys in a hashed format.
-f filename
Specifies the filename of the key file.
-g Use generic DNS format when printing fingerprint resource
records using the -r command.
-H Hash a known_hosts file. This replaces all hostnames and
addresses with hashed representations within the specified
file; the original content is moved to a file with a .old
suffix. These hashes may be used normally by ssh and sshd,
but they do not reveal identifying information should the
file's contents be disclosed. This option will not modify
existing hashed hostnames and is therefore safe to use on
files that mix hashed and non-hashed names.
-h When signing a key, create a host certificate instead of a
user certificate. Please see the CERTIFICATES section for
details.
-I certificate_identity
Specify the key identity when signing a public key. Please
see the CERTIFICATES section for details.
-i This option will read an unencrypted private (or public)
key file in the format specified by the -m option and print
an OpenSSH compatible private (or public) key to stdout.
This option allows importing keys from other software,
including several commercial SSH implementations. The
default import format is 'RFC4716'.
-K Download resident keys from a FIDO authenticator. Public
and private key files will be written to the current
directory for each downloaded key. If multiple FIDO
authenticators are attached, keys will be downloaded from
the first touched authenticator.
-k Generate a KRL file. In this mode, ssh-keygen will
generate a KRL file at the location specified via the -f
flag that revokes every key or certificate presented on the
command line. Keys/certificates to be revoked may be
specified by public key file or using the format described
in the KEY REVOCATION LISTS section.
-L Prints the contents of one or more certificates.
-l Show fingerprint of specified public key file. For RSA and
DSA keys ssh-keygen tries to find the matching public key
file and prints its fingerprint. If combined with -v, a
visual ASCII art representation of the key is supplied with
the fingerprint.
-M generate
Generate candidate Diffie-Hellman Group Exchange (DH-GEX)
parameters for eventual use by the
'diffie-hellman-group-exchange-*' key exchange methods.
The numbers generated by this operation must be further
screened before use. See the MODULI GENERATION section for
more information.
-M screen
Screen candidate parameters for Diffie-Hellman Group
Exchange. This will accept a list of candidate numbers and
test that they are safe (Sophie Germain) primes with
acceptable group generators. The results of this operation
may be added to the /etc/moduli file. See the MODULI
GENERATION section for more information.
-m key_format
Specify a key format for key generation, the -i (import),
-e (export) conversion options, and the -p change
passphrase operation. The latter may be used to convert
between OpenSSH private key and PEM private key formats.
The supported key formats are: 'RFC4716' (RFC 4716/SSH2
public or private key), 'PKCS8' (PKCS8 public or private
key) or 'PEM' (PEM public key). By default OpenSSH will
write newly-generated private keys in its own format, but
when converting public keys for export the default format
is 'RFC4716'. Setting a format of 'PEM' when generating or
updating a supported private key type will cause the key to
be stored in the legacy PEM private key format.
-N new_passphrase
Provides the new passphrase.
-n principals
Specify one or more principals (user or host names) to be
included in a certificate when signing a key. Multiple
principals may be specified, separated by commas. Please
see the CERTIFICATES section for details.
-O option
Specify a key/value option. These are specific to the
operation that ssh-keygen has been requested to perform.
When signing certificates, one of the options listed in the
CERTIFICATES section may be specified here.
When performing moduli generation or screening, one of the
options listed in the MODULI GENERATION section may be
specified.
When generating a key that will be hosted on a FIDO
authenticator, this flag may be used to specify key-
specific options. Those supported at present are:
application
Override the default FIDO application/origin string
of 'ssh:'. This may be useful when generating host
or domain-specific resident keys. The specified
application string must begin with 'ssh:'.
challenge=path
Specifies a path to a challenge string that will be
passed to the FIDO token during key generation.
The challenge string may be used as part of an out-
of-band protocol for key enrollment (a random
challenge is used by default).
device Explicitly specify a fido(4) device to use, rather
than letting the token middleware select one.
no-touch-required
Indicate that the generated private key should not
require touch events (user presence) when making
signatures. Note that sshd(8) will refuse such
signatures by default, unless overridden via an
authorized_keys option.
resident
Indicate that the key should be stored on the FIDO
authenticator itself. Resident keys may be
supported on FIDO2 tokens and typically require
that a PIN be set on the token prior to generation.
Resident keys may be loaded off the token using
ssh-add(1).
user A username to be associated with a resident key,
overriding the empty default username. Specifying
a username may be useful when generating multiple
resident keys for the same application name.
verify-required
Indicate that this private key should require user
verification for each signature. Not all FIDO
tokens support this option. Currently PIN
authentication is the only supported verification
method, but other methods may be supported in the
future.
write-attestation=path
May be used at key generation time to record the
attestation data returned from FIDO tokens during
key generation. Please note that this information
is potentially sensitive. By default, this
information is discarded.
When performing signature-related options using the -Y
flag, the following options are accepted:
print-pubkey
Print the full public key to standard output after
signature verification.
verify-time=timestamp
Specifies a time to use when validating signatures
instead of the current time. The time may be
specified as a date in YYYYMMDD format or a time in
YYYYMMDDHHMM[SS] format.
The -O option may be specified multiple times.
-P passphrase
Provides the (old) passphrase.
-p Requests changing the passphrase of a private key file
instead of creating a new private key. The program will
prompt for the file containing the private key, for the old
passphrase, and twice for the new passphrase.
-Q Test whether keys have been revoked in a KRL. If the -l
option is also specified then the contents of the KRL will
be printed.
-q Silence ssh-keygen.
-R hostname | [hostname]:port
Removes all keys belonging to the specified hostname (with
optional port number) from a known_hosts file. This option
is useful to delete hashed hosts (see the -H option above).
-r hostname
Print the SSHFP fingerprint resource record named hostname
for the specified public key file.
-s ca_key
Certify (sign) a public key using the specified CA key.
Please see the CERTIFICATES section for details.
When generating a KRL, -s specifies a path to a CA public
key file used to revoke certificates directly by key ID or
serial number. See the KEY REVOCATION LISTS section for
details.
-t dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa
Specifies the type of key to create. The possible values
are 'dsa', 'ecdsa', 'ecdsa-sk', 'ed25519', 'ed25519-sk', or
'rsa'.
This flag may also be used to specify the desired signature
type when signing certificates using an RSA CA key. The
available RSA signature variants are 'ssh-rsa' (SHA1
signatures, not recommended), 'rsa-sha2-256', and
'rsa-sha2-512' (the default).
-U When used in combination with -s, this option indicates
that a CA key resides in a ssh-agent(1). See the
CERTIFICATES section for more information.
-u Update a KRL. When specified with -k, keys listed via the
command line are added to the existing KRL rather than a
new KRL being created.
-V validity_interval
Specify a validity interval when signing a certificate. A
validity interval may consist of a single time, indicating
that the certificate is valid beginning now and expiring at
that time, or may consist of two times separated by a colon
to indicate an explicit time interval.
The start time may be specified as the string 'always' to
indicate the certificate has no specified start time, a
date in YYYYMMDD format, a time in YYYYMMDDHHMM[SS] format,
a relative time (to the current time) consisting of a minus
sign followed by an interval in the format described in the
TIME FORMATS section of sshd_config(5).
The end time may be specified as a YYYYMMDD date, a
YYYYMMDDHHMM[SS] time, a relative time starting with a plus
character or the string 'forever' to indicate that the
certificate has no expiry date.
For example: '+52w1d' (valid from now to 52 weeks and one
day from now), '-4w:+4w' (valid from four weeks ago to four
weeks from now), '20100101123000:20110101123000' (valid
from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st,
2011), '-1d:20110101' (valid from yesterday to midnight,
January 1st, 2011), '-1m:forever' (valid from one minute
ago and never expiring).
-v Verbose mode. Causes ssh-keygen to print debugging
messages about its progress. This is helpful for debugging
moduli generation. Multiple -v options increase the
verbosity. The maximum is 3.
-w provider
Specifies a path to a library that will be used when
creating FIDO authenticator-hosted keys, overriding the
default of using the internal USB HID support.
-Y find-principals
Find the principal(s) associated with the public key of a
signature, provided using the -s flag in an authorized
signers file provided using the -f flag. The format of the
allowed signers file is documented in the ALLOWED SIGNERS
section below. If one or more matching principals are
found, they are returned on standard output.
-Y check-novalidate
Checks that a signature generated using ssh-keygen -Y sign
has a valid structure. This does not validate if a
signature comes from an authorized signer. When testing a
signature, ssh-keygen accepts a message on standard input
and a signature namespace using -n. A file containing the
corresponding signature must also be supplied using the -s
flag. Successful testing of the signature is signalled by
ssh-keygen returning a zero exit status.
-Y sign
Cryptographically sign a file or some data using a SSH key.
When signing, ssh-keygen accepts zero or more files to sign
on the command-line - if no files are specified then
ssh-keygen will sign data presented on standard input.
Signatures are written to the path of the input file with
'.sig' appended, or to standard output if the message to be
signed was read from standard input.
The key used for signing is specified using the -f option
and may refer to either a private key, or a public key with
the private half available via ssh-agent(1). An additional
signature namespace, used to prevent signature confusion
across different domains of use (e.g. file signing vs email
signing) must be provided via the -n flag. Namespaces are
arbitrary strings, and may include: 'file' for file
signing, 'email' for email signing. For custom uses, it is
recommended to use names following a NAMESPACE@YOUR.DOMAIN
pattern to generate unambiguous namespaces.
-Y verify
Request to verify a signature generated using ssh-keygen -Y
sign as described above. When verifying a signature,
ssh-keygen accepts a message on standard input and a
signature namespace using -n. A file containing the
corresponding signature must also be supplied using the -s
flag, along with the identity of the signer using -I and a
list of allowed signers via the -f flag. The format of the
allowed signers file is documented in the ALLOWED SIGNERS
section below. A file containing revoked keys can be
passed using the -r flag. The revocation file may be a KRL
or a one-per-line list of public keys. Successful
verification by an authorized signer is signalled by
ssh-keygen returning a zero exit status.
-y This option will read a private OpenSSH format file and
print an OpenSSH public key to stdout.
-Z cipher
Specifies the cipher to use for encryption when writing an
OpenSSH-format private key file. The list of available
ciphers may be obtained using "ssh -Q cipher". The default
is 'aes256-ctr'.
-z serial_number
Specifies a serial number to be embedded in the certificate
to distinguish this certificate from others from the same
CA. If the serial_number is prefixed with a '+' character,
then the serial number will be incremented for each
certificate signed on a single command-line. The default
serial number is zero.
When generating a KRL, the -z flag is used to specify a KRL
version number.
