Description

ssh-keygen generates, manages, and converts authentication keys for ssh. It can create RSA keys for use by SSH protocol version 1 and RSA, DSA, or ECDSA 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 generates an RSA key for use in SSH protocol 2 connections.

ssh-keygen supports the extraction and conversion of keys that are stored in digital certificates associated with SAF key rings.

ssh-keygen is also used to generate groups for use in Diffie-Hellman Group Exchange (DH-GEX). It is a key agreement method that allows two parties to derive a shared secret key securely over an open (unprotected) network. For more details, check the IETF Internet draft Diffie-Hellman Group Exchange for the SSH Transport Layer Protocol at RFC 4253. For additional information, see Moduli generation.

If not using SAF key rings, each user who wants to use SSH with RSA, DSA, or ECDSA authentication runs ssh-keygen once to create the authentication key in ~/.ssh/identity, ~/.ssh/id_dsa, ~/.ssh/id_ecdsa, or ~/.ssh/id_rsa. The system administrator might also use ssh-keygen to generate host keys.

ssh-keygen can also be used to generate and update key revocation lists, and to test whether given keys have been revoked by one. See Key revocation lists for details.

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 with .pub appended. The program also asks for a passphrase. A passphrase is similar to a password, except it can be a phrase with a series of words, punctuation, numbers, white space, or any string of characters you want. Unless it is empty, the passphrase must be greater than 4 characters long. However, good passphrases are 10 to 30 characters long, are not simple sentences or otherwise guessable (English prose has only 1 or 2 bits of entropy per character and provides very bad passphrases), and contain a mix of uppercase and lowercase letters, numbers, and non-alphanumeric characters. The passphrase length must also be less than 1024 characters, or it will be truncated. The passphrase can be changed later using the –p option.

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

For RSA1 keys, there is also a comment field in the key file that is only for convenience to the user to help identify the key. The comment can tell what the key is for or whatever is useful. The comment is initialized to "user@host" when the key is created, but can be changed using the –c option.

When a change is made to the key (such as a comment or passphrase), the change is applied to the key file only. For the loaded keys in the SSH agent, one has to unload and reload the changed keys.

When attempting to change a key, ssh-keygen first tries to load the key without a passphrase if one is not specified. If that fails, it will prompt for the passphrase.

Tip: To avoid problems when running as a user that shares a UID, the -f option can be used to specify the location of the file to process.