Man page of SSH-KEYGEN (2024)

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
FILES
EXAMPLES
COPYRIGHT
SEE ALSO

NAME

ssh-keygen - Creation, management, and conversion of keys used for client and server authentication.

SYNOPSIS

ssh-keygen [-7 file] [-b bits] [-c comment] [-D private_key]

[-e private_key] [-f] [-F key] [-h] [-H key] [-i key]

[-k file] [-N new_passphrase] [-o key_name] [-O key]

[-p passphrase] [-P] [-q] [-t key_type] [-V] [-X cert]

DESCRIPTION

Use ssh-keygen to create RSA, DSA and ECDSA keys for public key authentication, to edit the properties of existing keys, and to convert key file formats for compatibility with other Secure Shell implementations.

When no options are specified, ssh-keygen generates a 2048-bit RSA key pair and queries you for a passphrase to protect the private key. If you don't specify a file name on the command line, keys are created in ~/.ssh2/ and given a default name that identifies the key type, size, and host name (for example /home/joe/.ssh2/id_rsa_2048_myhost_a). If you specify a file name, keys are saved to the current working directory unless you include a fully qualified path name. For each private key you create, ssh-keygen also generates a public key. Public keys are given the same base name as the private key, with an added .pub extension (for example id_rsa_2048_myhost_a.pub).

Reflection for Secure IT public keys use RFC 4716 compliant format. Private keys use PEM-encoded PKCS#8 format.

Client keys

If you use Secure Shell public keys to authenticate client users, you need to configure both the client and the server. On the client, generate the key and then add a line for this key to the client identification file (~/.ssh2/identification). This file lists the keys the client presents for authentication. For details see FILES in ssh(1). On the server, copy each client user's public key to that user's Secure Shell directory (~/.ssh2) and add the key to the user's authorization file (~/.ssh2/authorization by default). This file lists the keys the server accepts for user authentication. For details see FILES in sshd(8).

Server keys

The server installation package checks to see if an existing host key pair is already present. If no host key is found, the package creates a new host key pair and the server uses this pair for host authentication. If a host key already exists in /etc/ssh2, Reflection for Secure IT uses this key. If an OpenSSH host key is found in /etc/ssh, Reflection for Secure IT migrates the key to the correct format and location and uses the migrated key. Use ssh-keygen if you need to replace an existing host key. Use the -P option when you create a new host key pair; host keys should not be passphrase-protected. Note that when you replace your host key, the host will no longer be recognized as a trusted host by clients who had the previous host key in their known hosts key list.

OPTIONS

Options are available in both a single-character form (such as -b) and a descriptive equivalent (--bits). Single characters are shown here. To view the descriptive equivalents, use the -h command line option.

-7file: Extracts certificate(s) and CRL(s) from the specified PKCS#7 file.
-bbits: Specifies the key size. Up to a point, a larger key size improves security. Increasing key size slows down the initial connection, but has no effect on the speed of encryption or decryption of the data stream after a successful connection has been made. The length of key you should use depends on many factors, including: the key type, the lifetime of the key, the value of the data being protected, the resources available to a potential attacker, and the size of the symmetric key you use in conjunction with this asymmetric key. To ensure the best choice for your needs, we recommend that you contact your security officer. The default for RSA keys is 2048, the default for DSA keys is 1024 and the default for ECDSA keys is 256. The minimum and maximum values for RSA and DSA keys are 512 and 32768 respectively. The values for ECDSA keys are 256, 384 and 521.
-ccomment: Specifies information for the comment field within the key file. Use quotation marks if the string includes spaces. If you do not specify a comment, a default comment is created that includes the key type, creator, date, and time. Note: The comment is displayed when a passphrase-protected key is used for client authentication. Don't store passphrases or other sensitive information in the comment.
-Dprivate_key: Uses the specified private key to derive a new copy of the public key.
-eprivate_key: Changes the passphrase of the specified private key. When you use this option alone you will be queried for the old and new passphrase for the specified private key. To edit the passphrase without opening an interactive session, you can use this option in combination with -p and -N. To change to a null passphrase, you can use this option in combination with -P.
-f: Enables FIPS mode. This mode enforces key creation using FIPS-approved key strength.
-Fkey: Displays the fingerprint of the specified key in Bubble Babble format.
-h: Displays a brief summary of command options.
-Hkey: Uses the specified Reflection public key to generate a public key in OpenSSH format. The converted key is created using the same base file name with an added .ssh extension. You can use the key that is created to configure public key client authentication on an OpenSSH server.
-ikey: Displays information about the specified key.
-kfile: Extracts certificate(s) and private key(s) from the specified PKCS #12 file.
-Nnew_passphrase: Changes the passphrase to the specified new passphrase. Use this option in combination with -e.
-okey_name: Specifies the filename for the generated private key. (A public key is also created and is always given the same name as the private key plus a .pub file extension.) Note: An alternate way of naming key files is to specify one or more key filenames at the end of the ssh-keygen command.
-Okey: Uses the specified OpenSSH public or private key to create a public or private key in Reflection format. The converted key is created using the same base file name with an added .ssh2 extension.
-ppassphrase: Specifies a passphrase. Use quotation marks if the phrase includes spaces. This option creates the initial passphrase when you generate a new key. If you are managing an existing key, use this option to specify the passphrase that protects that key. If a passphrase is required and you don't use -p, you'll be prompted for the passphrase. Ensure that you follow your company's security policy for password length and complexity.
-P: Creates a key with no passphrase. You can use this option to create keys for server authentication. Passphrases are strongly recommended for client keys. Passphraseless keys should be used only for accounts that require unattended authentication (such as file transfer scripts). Passphraseless private key files should be protected using operating system file access controls (key file = 400, directory containing the key = 700).
-q: Hides the key generation progress indicator.
-tkey_type: Specifies the algorithm used for key generation. Possible values are "rsa", "dsa" and "ecdsa". The default is "rsa".
-V: Displays ssh-keygen version information.
-Xcert: Extracts the public key from the specified X.509 certificate file.
[key_name1 key_name2...]: Specifies the file name (or names) to be used for the generated private key (or keys). The public key is created using the same name with a ".pub" file extension.

FILES

$HOME/.ssh2/id_algorithm_size_hostname_x: The default location and naming convention used for private keys generated by ssh-keygen. For example:
: /home/joe/.ssh2/id_rsa_2048_myhost_a.
$HOME/.ssh2/id_algorithm_size_hostname_x.pub: The default location and naming convention used for public keys generated by ssh-keygen. For example:
: /home/joe/.ssh2/id_rsa_2048_myhost_a.pub.
/etc/ssh2/hostkey: The default private key of the public/private key pair used to identify the server to clients.
/etc/ssh2/hostkey.pub: The default public key of the public/private key pair used to authenticate the server to clients.

EXAMPLES

To generate three 1024-bit dsa key pairs using the specified key names. With this command, you'll be prompted in sequence for passphrases for each key and the key pairs will be created in the current working directory.

: ssh-keygen -b 1024 -t dsa key1 key2 key3

To change the passphrase of the specified protected key without entering into an interactive session:

: ssh-keygen -p "old pass" -N "new pass" -e keyname