| 1 | |
|---|
| 2 | SSH-KEYGEN(1) System Reference Manual SSH-KEYGEN(1) |
|---|
| 3 | |
|---|
| 4 | NAME |
|---|
| 5 | ssh-keygen - authentication key generation, management and conversion |
|---|
| 6 | |
|---|
| 7 | SYNOPSIS |
|---|
| 8 | ssh-keygen [-q] [-b bits] [-t type] [-N new_passphrase] [-C comment] [-f |
|---|
| 9 | output_keyfile] |
|---|
| 10 | ssh-keygen -p [-P old_passphrase] [-N new_passphrase] [-f keyfile] |
|---|
| 11 | ssh-keygen -i [-f input_keyfile] |
|---|
| 12 | ssh-keygen -e [-f input_keyfile] |
|---|
| 13 | ssh-keygen -y [-f input_keyfile] |
|---|
| 14 | ssh-keygen -c [-P passphrase] [-C comment] [-f keyfile] |
|---|
| 15 | ssh-keygen -l [-f input_keyfile] |
|---|
| 16 | ssh-keygen -B [-f input_keyfile] |
|---|
| 17 | ssh-keygen -D reader |
|---|
| 18 | ssh-keygen -U reader [-f input_keyfile] |
|---|
| 19 | |
|---|
| 20 | DESCRIPTION |
|---|
| 21 | ssh-keygen generates, manages and converts authentication keys for |
|---|
| 22 | ssh(1). ssh-keygen defaults to generating a RSA1 key for use by SSH proM-- |
|---|
| 23 | tocol version 1. Specifying the -t option instead creates a key for use |
|---|
| 24 | by SSH protocol version 2. |
|---|
| 25 | |
|---|
| 26 | Normally each user wishing to use SSH with RSA or DSA authentication runs |
|---|
| 27 | this once to create the authentication key in $HOME/.ssh/identity, |
|---|
| 28 | $HOME/.ssh/id_dsa or $HOME/.ssh/id_rsa. Additionally, the system adminisM-- |
|---|
| 29 | trator may use this to generate host keys, as seen in /etc/rc. |
|---|
| 30 | |
|---|
| 31 | Normally this program generates the key and asks for a file in which to |
|---|
| 32 | store the private key. The public key is stored in a file with the same |
|---|
| 33 | name but ``.pub'' appended. The program also asks for a passphrase. The |
|---|
| 34 | passphrase may be empty to indicate no passphrase (host keys must have an |
|---|
| 35 | empty passphrase), or it may be a string of arbitrary length. Good |
|---|
| 36 | passphrases are 10-30 characters long and are not simple sentences or |
|---|
| 37 | otherwise easily guessable (English prose has only 1-2 bits of entropy |
|---|
| 38 | per character, and provides very bad passphrases). The passphrase can be |
|---|
| 39 | changed later by using the -p option. |
|---|
| 40 | |
|---|
| 41 | There is no way to recover a lost passphrase. If the passphrase is lost |
|---|
| 42 | or forgotten, a new key must be generated and copied to the corresponding |
|---|
| 43 | public key to other machines. |
|---|
| 44 | |
|---|
| 45 | For RSA1 keys, there is also a comment field in the key file that is only |
|---|
| 46 | for convenience to the user to help identify the key. The comment can |
|---|
| 47 | tell what the key is for, or whatever is useful. The comment is initialM-- |
|---|
| 48 | ized to ``user@host'' when the key is created, but can be changed using |
|---|
| 49 | the -c option. |
|---|
| 50 | |
|---|
| 51 | After a key is generated, instructions below detail where the keys should |
|---|
| 52 | be placed to be activated. |
|---|
| 53 | |
|---|
| 54 | The options are as follows: |
|---|
| 55 | |
|---|
| 56 | -b bits |
|---|
| 57 | Specifies the number of bits in the key to create. Minimum is |
|---|
| 58 | 512 bits. Generally 1024 bits is considered sufficient, and key |
|---|
| 59 | sizes above that no longer improve security but make things slowM-- |
|---|
| 60 | er. The default is 1024 bits. |
|---|
| 61 | |
|---|
| 62 | -c Requests changing the comment in the private and public key |
|---|
| 63 | files. The program will prompt for the file containing the priM-- |
|---|
| 64 | vate keys, for the passphrase if the key has one, and for the new |
|---|
| 65 | |
|---|
| 66 | comment. |
|---|
| 67 | |
|---|
| 68 | -e This option will read a private or public OpenSSH key file and |
|---|
| 69 | print the key in a `SECSH Public Key File Format' to stdout. |
|---|
| 70 | This option allows exporting keys for use by several commercial |
|---|
| 71 | SSH implementations. |
|---|
| 72 | |
|---|
| 73 | -f filename |
|---|
| 74 | Specifies the filename of the key file. |
|---|
| 75 | |
|---|
| 76 | -i This option will read an unencrypted private (or public) key file |
|---|
| 77 | in SSH2-compatible format and print an OpenSSH compatible private |
|---|
| 78 | (or public) key to stdout. ssh-keygen also reads the `SECSH |
|---|
| 79 | Public Key File Format'. This option allows importing keys from |
|---|
| 80 | several commercial SSH implementations. |
|---|
| 81 | |
|---|
| 82 | -l Show fingerprint of specified private or public key file. |
|---|
| 83 | |
|---|
| 84 | -p Requests changing the passphrase of a private key file instead of |
|---|
| 85 | creating a new private key. The program will prompt for the file |
|---|
| 86 | containing the private key, for the old passphrase, and twice for |
|---|
| 87 | the new passphrase. |
|---|
| 88 | |
|---|
| 89 | -q Silence ssh-keygen. Used by /etc/rc when creating a new key. |
|---|
| 90 | |
|---|
| 91 | -y This option will read a private OpenSSH format file and print an |
|---|
| 92 | OpenSSH public key to stdout. |
|---|
| 93 | |
|---|
| 94 | -t type |
|---|
| 95 | Specifies the type of the key to create. The possible values are |
|---|
| 96 | ``rsa1'' for protocol version 1 and ``rsa'' or ``dsa'' for protoM-- |
|---|
| 97 | col version 2. The default is ``rsa1''. |
|---|
| 98 | |
|---|
| 99 | -B Show the bubblebabble digest of specified private or public key |
|---|
| 100 | file. |
|---|
| 101 | |
|---|
| 102 | -C comment |
|---|
| 103 | Provides the new comment. |
|---|
| 104 | |
|---|
| 105 | -D reader |
|---|
| 106 | Download the RSA public key stored in the smartcard in reader. |
|---|
| 107 | |
|---|
| 108 | -N new_passphrase |
|---|
| 109 | Provides the new passphrase. |
|---|
| 110 | |
|---|
| 111 | -P passphrase |
|---|
| 112 | Provides the (old) passphrase. |
|---|
| 113 | |
|---|
| 114 | -U reader |
|---|
| 115 | Upload an existing RSA private key into the smartcard in reader. |
|---|
| 116 | |
|---|
| 117 | FILES |
|---|
| 118 | $HOME/.ssh/identity |
|---|
| 119 | Contains the protocol version 1 RSA authentication identity of |
|---|
| 120 | the user. This file should not be readable by anyone but the usM-- |
|---|
| 121 | er. It is possible to specify a passphrase when generating the |
|---|
| 122 | key; that passphrase will be used to encrypt the private part of |
|---|
| 123 | this file using 3DES. This file is not automatically accessed by |
|---|
| 124 | ssh-keygen but it is offered as the default file for the private |
|---|
| 125 | key. ssh(1) will read this file when a login attempt is made. |
|---|
| 126 | |
|---|
| 127 | $HOME/.ssh/identity.pub |
|---|
| 128 | Contains the protocol version 1 RSA public key for authenticaM-- |
|---|
| 129 | tion. The contents of this file should be added to |
|---|
| 130 | $HOME/.ssh/authorized_keys on all machines where the user wishes |
|---|
| 131 | to log in using RSA authentication. There is no need to keep the |
|---|
| 132 | |
|---|
| 133 | contents of this file secret. |
|---|
| 134 | |
|---|
| 135 | $HOME/.ssh/id_dsa |
|---|
| 136 | Contains the protocol version 2 DSA authentication identity of |
|---|
| 137 | the user. This file should not be readable by anyone but the usM-- |
|---|
| 138 | er. It is possible to specify a passphrase when generating the |
|---|
| 139 | key; that passphrase will be used to encrypt the private part of |
|---|
| 140 | this file using 3DES. This file is not automatically accessed by |
|---|
| 141 | ssh-keygen but it is offered as the default file for the private |
|---|
| 142 | key. ssh(1) will read this file when a login attempt is made. |
|---|
| 143 | |
|---|
| 144 | $HOME/.ssh/id_dsa.pub |
|---|
| 145 | Contains the protocol version 2 DSA public key for authenticaM-- |
|---|
| 146 | tion. The contents of this file should be added to |
|---|
| 147 | $HOME/.ssh/authorized_keys on all machines where the user wishes |
|---|
| 148 | to log in using public key authentication. There is no need to |
|---|
| 149 | keep the contents of this file secret. |
|---|
| 150 | |
|---|
| 151 | $HOME/.ssh/id_rsa |
|---|
| 152 | Contains the protocol version 2 RSA authentication identity of |
|---|
| 153 | the user. This file should not be readable by anyone but the usM-- |
|---|
| 154 | er. It is possible to specify a passphrase when generating the |
|---|
| 155 | key; that passphrase will be used to encrypt the private part of |
|---|
| 156 | this file using 3DES. This file is not automatically accessed by |
|---|
| 157 | ssh-keygen but it is offered as the default file for the private |
|---|
| 158 | key. ssh(1) will read this file when a login attempt is made. |
|---|
| 159 | |
|---|
| 160 | $HOME/.ssh/id_rsa.pub |
|---|
| 161 | Contains the protocol version 2 RSA public key for authenticaM-- |
|---|
| 162 | tion. The contents of this file should be added to |
|---|
| 163 | $HOME/.ssh/authorized_keys on all machines where the user wishes |
|---|
| 164 | to log in using public key authentication. There is no need to |
|---|
| 165 | keep the contents of this file secret. |
|---|
| 166 | |
|---|
| 167 | AUTHORS |
|---|
| 168 | OpenSSH is a derivative of the original and free ssh 1.2.12 release by |
|---|
| 169 | Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo |
|---|
| 170 | de Raadt and Dug Song removed many bugs, re-added newer features and creM-- |
|---|
| 171 | ated OpenSSH. Markus Friedl contributed the support for SSH protocol |
|---|
| 172 | versions 1.5 and 2.0. |
|---|
| 173 | |
|---|
| 174 | SEE ALSO |
|---|
| 175 | ssh(1), ssh-add(1), ssh-agent(1), sshd(8) |
|---|
| 176 | |
|---|
| 177 | J. Galbraith, and R. Thayer, SECSH Public Key File Format, draft-ietf- |
|---|
| 178 | secsh-publickeyfile-01.txt, March 2001, work in progress material. |
|---|
| 179 | |
|---|
| 180 | BSD Experimental September 25, 1999 3 |
|---|
