1 | SSH-KEYGEN(1) OpenBSD Reference Manual SSH-KEYGEN(1) |
---|
2 | |
---|
3 | NAME |
---|
4 | ssh-keygen - authentication key generation, management and conversion |
---|
5 | |
---|
6 | SYNOPSIS |
---|
7 | ssh-keygen [-q] [-b bits] -t type [-N new_passphrase] [-C comment] |
---|
8 | [-f output_keyfile] |
---|
9 | ssh-keygen -p [-P old_passphrase] [-N new_passphrase] [-f keyfile] |
---|
10 | ssh-keygen -i [-f input_keyfile] |
---|
11 | ssh-keygen -e [-f input_keyfile] |
---|
12 | ssh-keygen -y [-f input_keyfile] |
---|
13 | ssh-keygen -c [-P passphrase] [-C comment] [-f keyfile] |
---|
14 | ssh-keygen -l [-f input_keyfile] |
---|
15 | ssh-keygen -B [-f input_keyfile] |
---|
16 | ssh-keygen -D reader |
---|
17 | ssh-keygen -F hostname [-f known_hosts_file] |
---|
18 | ssh-keygen -H [-f known_hosts_file] |
---|
19 | ssh-keygen -R hostname [-f known_hosts_file] |
---|
20 | ssh-keygen -U reader [-f input_keyfile] |
---|
21 | ssh-keygen -r hostname [-f input_keyfile] [-g] |
---|
22 | ssh-keygen -G output_file [-v] [-b bits] [-M memory] [-S start_point] |
---|
23 | ssh-keygen -T output_file -f input_file [-v] [-a num_trials] [-W |
---|
24 | generator] |
---|
25 | |
---|
26 | DESCRIPTION |
---|
27 | ssh-keygen generates, manages and converts authentication keys for |
---|
28 | ssh(1). ssh-keygen can create RSA keys for use by SSH protocol version 1 |
---|
29 | and RSA or DSA keys for use by SSH protocol version 2. The type of key |
---|
30 | to be generated is specified with the -t option. |
---|
31 | |
---|
32 | ssh-keygen is also used to generate groups for use in Diffie-Hellman |
---|
33 | group exchange (DH-GEX). See the MODULI GENERATION section for details. |
---|
34 | |
---|
35 | Normally each user wishing to use SSH with RSA or DSA authentication runs |
---|
36 | this once to create the authentication key in ~/.ssh/identity, |
---|
37 | ~/.ssh/id_dsa or ~/.ssh/id_rsa. Additionally, the system administrator |
---|
38 | may use this to generate host keys, as seen in /etc/rc. |
---|
39 | |
---|
40 | Normally this program generates the key and asks for a file in which to |
---|
41 | store the private key. The public key is stored in a file with the same |
---|
42 | name but ``.pub'' appended. The program also asks for a passphrase. The |
---|
43 | passphrase may be empty to indicate no passphrase (host keys must have an |
---|
44 | empty passphrase), or it may be a string of arbitrary length. A |
---|
45 | passphrase is similar to a password, except it can be a phrase with a se- |
---|
46 | ries of words, punctuation, numbers, whitespace, or any string of charac- |
---|
47 | ters you want. Good passphrases are 10-30 characters long, are not sim- |
---|
48 | ple sentences or otherwise easily guessable (English prose has only 1-2 |
---|
49 | bits of entropy per character, and provides very bad passphrases), and |
---|
50 | contain a mix of upper and lowercase letters, numbers, and non-alphanu- |
---|
51 | meric characters. The passphrase can be changed later by using the -p |
---|
52 | option. |
---|
53 | |
---|
54 | There is no way to recover a lost passphrase. If the passphrase is lost |
---|
55 | or forgotten, a new key must be generated and copied to the corresponding |
---|
56 | public key to other machines. |
---|
57 | |
---|
58 | For RSA1 keys, there is also a comment field in the key file that is only |
---|
59 | for convenience to the user to help identify the key. The comment can |
---|
60 | tell what the key is for, or whatever is useful. The comment is initial- |
---|
61 | ized to ``user@host'' when the key is created, but can be changed using |
---|
62 | the -c option. |
---|
63 | |
---|
64 | After a key is generated, instructions below detail where the keys should |
---|
65 | be placed to be activated. |
---|
66 | |
---|
67 | The options are as follows: |
---|
68 | |
---|
69 | -a trials |
---|
70 | Specifies the number of primality tests to perform when screening |
---|
71 | DH-GEX candidates using the -T command. |
---|
72 | |
---|
73 | -B Show the bubblebabble digest of specified private or public key |
---|
74 | file. |
---|
75 | |
---|
76 | -b bits |
---|
77 | Specifies the number of bits in the key to create. Minimum is |
---|
78 | 512 bits. Generally, 2048 bits is considered sufficient. The |
---|
79 | default is 2048 bits. |
---|
80 | |
---|
81 | -C comment |
---|
82 | Provides a new comment. |
---|
83 | |
---|
84 | -c Requests changing the comment in the private and public key |
---|
85 | files. This operation is only supported for RSA1 keys. The pro- |
---|
86 | gram will prompt for the file containing the private keys, for |
---|
87 | the passphrase if the key has one, and for the new comment. |
---|
88 | |
---|
89 | -D reader |
---|
90 | Download the RSA public key stored in the smartcard in reader. |
---|
91 | |
---|
92 | -e This option will read a private or public OpenSSH key file and |
---|
93 | print the key in a `SECSH Public Key File Format' to stdout. |
---|
94 | This option allows exporting keys for use by several commercial |
---|
95 | SSH implementations. |
---|
96 | |
---|
97 | -F hostname |
---|
98 | Search for the specified hostname in a known_hosts file, listing |
---|
99 | any occurrences found. This option is useful to find hashed host |
---|
100 | names or addresses and may also be used in conjunction with the |
---|
101 | -H option to print found keys in a hashed format. |
---|
102 | |
---|
103 | -f filename |
---|
104 | Specifies the filename of the key file. |
---|
105 | |
---|
106 | -G output_file |
---|
107 | Generate candidate primes for DH-GEX. These primes must be |
---|
108 | screened for safety (using the -T option) before use. |
---|
109 | |
---|
110 | -g Use generic DNS format when printing fingerprint resource records |
---|
111 | using the -r command. |
---|
112 | |
---|
113 | -H Hash a known_hosts file. This replaces all hostnames and ad- |
---|
114 | dresses with hashed representations within the specified file; |
---|
115 | the original content is moved to a file with a .old suffix. |
---|
116 | These hashes may be used normally by ssh and sshd, but they do |
---|
117 | not reveal identifying information should the file's contents be |
---|
118 | disclosed. This option will not modify existing hashed hostnames |
---|
119 | and is therefore safe to use on files that mix hashed and non- |
---|
120 | hashed names. |
---|
121 | |
---|
122 | -i This option will read an unencrypted private (or public) key file |
---|
123 | in SSH2-compatible format and print an OpenSSH compatible private |
---|
124 | (or public) key to stdout. ssh-keygen also reads the `SECSH |
---|
125 | Public Key File Format'. This option allows importing keys from |
---|
126 | several commercial SSH implementations. |
---|
127 | |
---|
128 | -l Show fingerprint of specified public key file. Private RSA1 keys |
---|
129 | are also supported. For RSA and DSA keys ssh-keygen tries to |
---|
130 | find the matching public key file and prints its fingerprint. |
---|
131 | |
---|
132 | -M memory |
---|
133 | Specify the amount of memory to use (in megabytes) when generat- |
---|
134 | ing candidate moduli for DH-GEX. |
---|
135 | |
---|
136 | -N new_passphrase |
---|
137 | Provides the new passphrase. |
---|
138 | |
---|
139 | -P passphrase |
---|
140 | Provides the (old) passphrase. |
---|
141 | |
---|
142 | -p Requests changing the passphrase of a private key file instead of |
---|
143 | creating a new private key. The program will prompt for the file |
---|
144 | containing the private key, for the old passphrase, and twice for |
---|
145 | the new passphrase. |
---|
146 | |
---|
147 | -q Silence ssh-keygen. Used by /etc/rc when creating a new key. |
---|
148 | |
---|
149 | -R hostname |
---|
150 | Removes all keys belonging to hostname from a known_hosts file. |
---|
151 | This option is useful to delete hashed hosts (see the -H option |
---|
152 | above). |
---|
153 | |
---|
154 | -r hostname |
---|
155 | Print the SSHFP fingerprint resource record named hostname for |
---|
156 | the specified public key file. |
---|
157 | |
---|
158 | -S start |
---|
159 | Specify start point (in hex) when generating candidate moduli for |
---|
160 | DH-GEX. |
---|
161 | |
---|
162 | -T output_file |
---|
163 | Test DH group exchange candidate primes (generated using the -G |
---|
164 | option) for safety. |
---|
165 | |
---|
166 | -t type |
---|
167 | Specifies the type of key to create. The possible values are |
---|
168 | ``rsa1'' for protocol version 1 and ``rsa'' or ``dsa'' for proto- |
---|
169 | col version 2. |
---|
170 | |
---|
171 | -U reader |
---|
172 | Upload an existing RSA private key into the smartcard in reader. |
---|
173 | |
---|
174 | -v Verbose mode. Causes ssh-keygen to print debugging messages |
---|
175 | about its progress. This is helpful for debugging moduli genera- |
---|
176 | tion. Multiple -v options increase the verbosity. The maximum |
---|
177 | is 3. |
---|
178 | |
---|
179 | -W generator |
---|
180 | Specify desired generator when testing candidate moduli for DH- |
---|
181 | GEX. |
---|
182 | |
---|
183 | -y This option will read a private OpenSSH format file and print an |
---|
184 | OpenSSH public key to stdout. |
---|
185 | |
---|
186 | MODULI GENERATION |
---|
187 | ssh-keygen may be used to generate groups for the Diffie-Hellman Group |
---|
188 | Exchange (DH-GEX) protocol. Generating these groups is a two-step pro- |
---|
189 | cess: first, candidate primes are generated using a fast, but memory in- |
---|
190 | tensive process. These candidate primes are then tested for suitability |
---|
191 | (a CPU-intensive process). |
---|
192 | |
---|
193 | Generation of primes is performed using the -G option. The desired |
---|
194 | length of the primes may be specified by the -b option. For example: |
---|
195 | |
---|
196 | # ssh-keygen -G moduli-2048.candidates -b 2048 |
---|
197 | |
---|
198 | By default, the search for primes begins at a random point in the desired |
---|
199 | length range. This may be overridden using the -S option, which speci- |
---|
200 | fies a different start point (in hex). |
---|
201 | |
---|
202 | Once a set of candidates have been generated, they must be tested for |
---|
203 | suitability. This may be performed using the -T option. In this mode |
---|
204 | ssh-keygen will read candidates from standard input (or a file specified |
---|
205 | using the -f option). For example: |
---|
206 | |
---|
207 | # ssh-keygen -T moduli-2048 -f moduli-2048.candidates |
---|
208 | |
---|
209 | By default, each candidate will be subjected to 100 primality tests. |
---|
210 | This may be overridden using the -a option. The DH generator value will |
---|
211 | be chosen automatically for the prime under consideration. If a specific |
---|
212 | generator is desired, it may be requested using the -W option. Valid |
---|
213 | generator values are 2, 3, and 5. |
---|
214 | |
---|
215 | Screened DH groups may be installed in /etc/moduli. It is important that |
---|
216 | this file contains moduli of a range of bit lengths and that both ends of |
---|
217 | a connection share common moduli. |
---|
218 | |
---|
219 | FILES |
---|
220 | ~/.ssh/identity |
---|
221 | Contains the protocol version 1 RSA authentication identity of |
---|
222 | the user. This file should not be readable by anyone but the us- |
---|
223 | er. It is possible to specify a passphrase when generating the |
---|
224 | key; that passphrase will be used to encrypt the private part of |
---|
225 | this file using 3DES. This file is not automatically accessed by |
---|
226 | ssh-keygen but it is offered as the default file for the private |
---|
227 | key. ssh(1) will read this file when a login attempt is made. |
---|
228 | |
---|
229 | ~/.ssh/identity.pub |
---|
230 | Contains the protocol version 1 RSA public key for authentica- |
---|
231 | tion. The contents of this file should be added to |
---|
232 | ~/.ssh/authorized_keys on all machines where the user wishes to |
---|
233 | log in using RSA authentication. There is no need to keep the |
---|
234 | contents of this file secret. |
---|
235 | |
---|
236 | ~/.ssh/id_dsa |
---|
237 | Contains the protocol version 2 DSA authentication identity of |
---|
238 | the user. This file should not be readable by anyone but the us- |
---|
239 | er. It is possible to specify a passphrase when generating the |
---|
240 | key; that passphrase will be used to encrypt the private part of |
---|
241 | this file using 3DES. This file is not automatically accessed by |
---|
242 | ssh-keygen but it is offered as the default file for the private |
---|
243 | key. ssh(1) will read this file when a login attempt is made. |
---|
244 | |
---|
245 | ~/.ssh/id_dsa.pub |
---|
246 | Contains the protocol version 2 DSA public key for authentica- |
---|
247 | tion. The contents of this file should be added to |
---|
248 | ~/.ssh/authorized_keys on all machines where the user wishes to |
---|
249 | log in using public key authentication. There is no need to keep |
---|
250 | the contents of this file secret. |
---|
251 | |
---|
252 | ~/.ssh/id_rsa |
---|
253 | Contains the protocol version 2 RSA authentication identity of |
---|
254 | the user. This file should not be readable by anyone but the us- |
---|
255 | er. It is possible to specify a passphrase when generating the |
---|
256 | key; that passphrase will be used to encrypt the private part of |
---|
257 | this file using 3DES. This file is not automatically accessed by |
---|
258 | ssh-keygen but it is offered as the default file for the private |
---|
259 | key. ssh(1) will read this file when a login attempt is made. |
---|
260 | |
---|
261 | ~/.ssh/id_rsa.pub |
---|
262 | Contains the protocol version 2 RSA public key for authentica- |
---|
263 | tion. The contents of this file should be added to |
---|
264 | ~/.ssh/authorized_keys on all machines where the user wishes to |
---|
265 | log in using public key authentication. There is no need to keep |
---|
266 | the contents of this file secret. |
---|
267 | |
---|
268 | /etc/moduli |
---|
269 | Contains Diffie-Hellman groups used for DH-GEX. The file format |
---|
270 | is described in moduli(5). |
---|
271 | |
---|
272 | SEE ALSO |
---|
273 | ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8) |
---|
274 | |
---|
275 | J. Galbraith and R. Thayer, SECSH Public Key File Format, draft-ietf- |
---|
276 | secsh-publickeyfile-01.txt, March 2001, work in progress material. |
---|
277 | |
---|
278 | AUTHORS |
---|
279 | OpenSSH is a derivative of the original and free ssh 1.2.12 release by |
---|
280 | Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo |
---|
281 | de Raadt and Dug Song removed many bugs, re-added newer features and |
---|
282 | created OpenSSH. Markus Friedl contributed the support for SSH protocol |
---|
283 | versions 1.5 and 2.0. |
---|
284 | |
---|
285 | OpenBSD 3.8 September 25, 1999 5 |
---|