ssh-keygen Man Page

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 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]

[key_name1 key_name2 ...]

DESCRIPTION

Use ssh-keygen to create RSA and DSA 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 $HOME/.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 ($HOME/.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 ($HOME/.ssh2) and add the key to the user's authorization file ($HOME/.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.

-7 file

Extracts certificate(s) and CRL(s) from the specified PKCS#7 file.

-b bits

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 bits and 1024 bits for DSA keys. The minimum allowed value is 512. The maximum allowed value is 32768.

-c comment

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.

-D private_key

Uses the specified private key to derive a new copy of the public key.

-e private_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 key

Displays the fingerprint of the specified key in Bubble Babble format.

-h

Displays a brief summary of command options.

-H key

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.

-i key

Displays information about the specified key.

-k file

Extracts certificate(s) and private key(s) from the specified PKCS #12 file.

-N new_passphrase

Changes the passphrase to the specified new passphrase. Use this option in combination with -e.

-o key_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.

-O key

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.

-p passphrase

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.

-P

Creates a key with no passphrase. You can use this option to create keys for server authentication. Passphrases are recommended for client keys.

-q

Hides the key generation progress indicator.

-t key_type

Specifies the algorithm used for key generation. Possible values are "rsa" and "dsa". The default is "rsa".

-V

Displays ssh-keygen version information.

-X cert

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/hostkeyThe default private key of the public/private key pair used to identify the server to clients.

/etc/ssh2/hostkey.pubThe 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