| blob | 6dd6154287aa7ab4caa3ed4d7c3fdfcfd39963ac |
1 .\" $OpenBSD: ssh-keygen.1,v 1.61 2003/12/22 09:16:58 djm Exp $
2 .\"
3 .\" -*- nroff -*-
4 .\"
5 .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
6 .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
7 .\" All rights reserved
8 .\"
9 .\" As far as I am concerned, the code I have written for this software
10 .\" can be used freely for any purpose. Any derived versions of this
11 .\" software must be clearly marked as such, and if the derived work is
12 .\" incompatible with the protocol description in the RFC file, it must be
13 .\" called by a name other than "ssh" or "Secure Shell".
14 .\"
15 .\"
16 .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
17 .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
18 .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
19 .\"
20 .\" Redistribution and use in source and binary forms, with or without
21 .\" modification, are permitted provided that the following conditions
22 .\" are met:
23 .\" 1. Redistributions of source code must retain the above copyright
24 .\" notice, this list of conditions and the following disclaimer.
25 .\" 2. Redistributions in binary form must reproduce the above copyright
26 .\" notice, this list of conditions and the following disclaimer in the
27 .\" documentation and/or other materials provided with the distribution.
28 .\"
29 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
30 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
31 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
32 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
33 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
34 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
35 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
36 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
37 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
38 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39 .\"
40 .Dd September 25, 1999
41 .Dt SSH-KEYGEN 1
42 .Os
43 .Sh NAME
44 .Nm ssh-keygen
45 .Nd authentication key generation, management and conversion
46 .Sh SYNOPSIS
47 .Nm ssh-keygen
48 .Bk -words
49 .Op Fl q
50 .Op Fl b Ar bits
51 .Fl t Ar type
52 .Op Fl N Ar new_passphrase
53 .Op Fl C Ar comment
54 .Op Fl f Ar output_keyfile
55 .Ek
56 .Nm ssh-keygen
57 .Fl p
58 .Op Fl P Ar old_passphrase
59 .Op Fl N Ar new_passphrase
60 .Op Fl f Ar keyfile
61 .Nm ssh-keygen
62 .Fl i
63 .Op Fl f Ar input_keyfile
64 .Nm ssh-keygen
65 .Fl e
66 .Op Fl f Ar input_keyfile
67 .Nm ssh-keygen
68 .Fl y
69 .Op Fl f Ar input_keyfile
70 .Nm ssh-keygen
71 .Fl c
72 .Op Fl P Ar passphrase
73 .Op Fl C Ar comment
74 .Op Fl f Ar keyfile
75 .Nm ssh-keygen
76 .Fl l
77 .Op Fl f Ar input_keyfile
78 .Nm ssh-keygen
79 .Fl B
80 .Op Fl f Ar input_keyfile
81 .Nm ssh-keygen
82 .Fl D Ar reader
83 .Nm ssh-keygen
84 .Fl U Ar reader
85 .Op Fl f Ar input_keyfile
86 .Nm ssh-keygen
87 .Fl r Ar hostname
88 .Op Fl f Ar input_keyfile
89 .Op Fl g
90 .Nm ssh-keygen
91 .Fl G Ar output_file
92 .Op Fl v
93 .Op Fl b Ar bits
94 .Op Fl M Ar memory
95 .Op Fl S Ar start_point
96 .Nm ssh-keygen
97 .Fl T Ar output_file
98 .Fl f Ar input_file
99 .Op Fl v
100 .Op Fl a Ar num_trials
101 .Op Fl W Ar generator
102 .Sh DESCRIPTION
103 .Nm
104 generates, manages and converts authentication keys for
105 .Xr ssh 1 .
106 .Nm
107 can create RSA keys for use by SSH protocol version 1 and RSA or DSA
108 keys for use by SSH protocol version 2.
109 The type of key to be generated is specified with the
110 .Fl t
111 option.
112 .Pp
113 .Nm
114 is also used to generate groups for use in Diffie-Hellman group
115 exchange (DH-GEX).
116 See the
117 .Sx MODULI GENERATION
118 section for details.
119 .Pp
120 Normally each user wishing to use SSH
121 with RSA or DSA authentication runs this once to create the authentication
122 key in
123 .Pa $HOME/.ssh/identity ,
124 .Pa $HOME/.ssh/id_dsa
125 or
126 .Pa $HOME/.ssh/id_rsa .
127 Additionally, the system administrator may use this to generate host keys,
128 as seen in
129 .Pa /etc/rc .
130 .Pp
131 Normally this program generates the key and asks for a file in which
132 to store the private key.
133 The public key is stored in a file with the same name but
134 .Dq .pub
135 appended.
136 The program also asks for a passphrase.
137 The passphrase may be empty to indicate no passphrase
138 (host keys must have an empty passphrase), or it may be a string of
139 arbitrary length.
140 A passphrase is similar to a password, except it can be a phrase with a
141 series of words, punctuation, numbers, whitespace, or any string of
142 characters you want.
143 Good passphrases are 10-30 characters long, are
144 not simple sentences or otherwise easily guessable (English
145 prose has only 1-2 bits of entropy per character, and provides very bad
146 passphrases), and contain a mix of upper and lowercase letters,
147 numbers, and non-alphanumeric characters.
148 The passphrase can be changed later by using the
149 .Fl p
150 option.
151 .Pp
152 There is no way to recover a lost passphrase.
153 If the passphrase is
154 lost or forgotten, a new key must be generated and copied to the
155 corresponding public key to other machines.
156 .Pp
157 For RSA1 keys,
158 there is also a comment field in the key file that is only for
159 convenience to the user to help identify the key.
160 The comment can tell what the key is for, or whatever is useful.
161 The comment is initialized to
162 .Dq user@host
163 when the key is created, but can be changed using the
164 .Fl c
165 option.
166 .Pp
167 After a key is generated, instructions below detail where the keys
168 should be placed to be activated.
169 .Pp
170 The options are as follows:
171 .Bl -tag -width Ds
172 .It Fl a Ar trials
173 Specifies the number of primality tests to perform when screening DH-GEX
174 candidates using the
175 .Fl T
176 command.
177 .It Fl b Ar bits
178 Specifies the number of bits in the key to create.
179 Minimum is 512 bits.
180 Generally, 1024 bits is considered sufficient.
181 The default is 1024 bits.
182 .It Fl c
183 Requests changing the comment in the private and public key files.
184 This operation is only supported for RSA1 keys.
185 The program will prompt for the file containing the private keys, for
186 the passphrase if the key has one, and for the new comment.
187 .It Fl e
188 This option will read a private or public OpenSSH key file and
189 print the key in a
190 .Sq SECSH Public Key File Format
191 to stdout.
192 This option allows exporting keys for use by several commercial
193 SSH implementations.
194 .It Fl g
195 Use generic DNS resource record format.
196 .It Fl f Ar filename
197 Specifies the filename of the key file.
198 .It Fl i
199 This option will read an unencrypted private (or public) key file
200 in SSH2-compatible format and print an OpenSSH compatible private
201 (or public) key to stdout.
202 .Nm
203 also reads the
204 .Sq SECSH Public Key File Format .
205 This option allows importing keys from several commercial
206 SSH implementations.
207 .It Fl l
208 Show fingerprint of specified public key file.
209 Private RSA1 keys are also supported.
210 For RSA and DSA keys
211 .Nm
212 tries to find the matching public key file and prints its fingerprint.
213 .It Fl p
214 Requests changing the passphrase of a private key file instead of
215 creating a new private key.
216 The program will prompt for the file
217 containing the private key, for the old passphrase, and twice for the
218 new passphrase.
219 .It Fl q
220 Silence
221 .Nm ssh-keygen .
222 Used by
223 .Pa /etc/rc
224 when creating a new key.
225 .It Fl y
226 This option will read a private
227 OpenSSH format file and print an OpenSSH public key to stdout.
228 .It Fl t Ar type
229 Specifies the type of the key to create.
230 The possible values are
231 .Dq rsa1
232 for protocol version 1 and
233 .Dq rsa
234 or
235 .Dq dsa
236 for protocol version 2.
237 .It Fl B
238 Show the bubblebabble digest of specified private or public key file.
239 .It Fl C Ar comment
240 Provides the new comment.
241 .It Fl D Ar reader
242 Download the RSA public key stored in the smartcard in
243 .Ar reader .
244 .It Fl G Ar output_file
245 Generate candidate primes for DH-GEX.
246 These primes must be screened for
247 safety (using the
248 .Fl T
249 option) before use.
250 .It Fl M Ar memory
251 Specify the amount of memory to use (in megabytes) when generating
252 candidate moduli for DH-GEX.
253 .It Fl N Ar new_passphrase
254 Provides the new passphrase.
255 .It Fl P Ar passphrase
256 Provides the (old) passphrase.
257 .It Fl S Ar start
258 Specify start point (in hex) when generating candidate moduli for DH-GEX.
259 .It Fl T Ar output_file
260 Test DH group exchange candidate primes (generated using the
261 .Fl G
262 option) for safety.
263 .It Fl W Ar generator
264 Specify desired generator when testing candidate moduli for DH-GEX.
265 .It Fl U Ar reader
266 Upload an existing RSA private key into the smartcard in
267 .Ar reader .
268 .It Fl v
269 Verbose mode.
270 Causes
271 .Nm
272 to print debugging messages about its progress.
273 This is helpful for debugging moduli generation.
274 Multiple
275 .Fl v
276 options increase the verbosity.
277 The maximum is 3.
278 .It Fl r Ar hostname
279 Print DNS resource record with the specified
280 .Ar hostname .
281 .El
282 .Sh MODULI GENERATION
283 .Nm
284 may be used to generate groups for the Diffie-Hellman Group Exchange
285 (DH-GEX) protocol.
286 Generating these groups is a two-step process: first, candidate
287 primes are generated using a fast, but memory intensive process.
288 These candidate primes are then tested for suitability (a CPU-intensive
289 process).
290 .Pp
291 Generation of primes is performed using the
292 .Fl G
293 option.
294 The desired length of the primes may be specified by the
295 .Fl b
296 option.
297 For example:
298 .Pp
299 .Dl ssh-keygen -G moduli-2048.candidates -b 2048
300 .Pp
301 By default, the search for primes begins at a random point in the
302 desired length range.
303 This may be overridden using the
304 .Fl S
305 option, which specifies a different start point (in hex).
306 .Pp
307 Once a set of candidates have been generated, they must be tested for
308 suitability.
309 This may be performed using the
310 .Fl T
311 option.
312 In this mode
313 .Nm
314 will read candidates from standard input (or a file specified using the
315 .Fl f
316 option).
317 For example:
318 .Pp
319 .Dl ssh-keygen -T moduli-2048 -f moduli-2048.candidates
320 .Pp
321 By default, each candidate will be subjected to 100 primality tests.
322 This may be overridden using the
323 .Fl a
324 option.
325 The DH generator value will be chosen automatically for the
326 prime under consideration.
327 If a specific generator is desired, it may be requested using the
328 .Fl W
329 option.
330 Valid generator values are 2, 3 and 5.
331 .Pp
332 Screened DH groups may be installed in
333 .Pa /etc/moduli .
334 It is important that this file contains moduli of a range of bit lengths and
335 that both ends of a connection share common moduli.
336 .Sh FILES
337 .Bl -tag -width Ds
338 .It Pa $HOME/.ssh/identity
339 Contains the protocol version 1 RSA authentication identity of the user.
340 This file should not be readable by anyone but the user.
341 It is possible to
342 specify a passphrase when generating the key; that passphrase will be
343 used to encrypt the private part of this file using 3DES.
344 This file is not automatically accessed by
345 .Nm
346 but it is offered as the default file for the private key.
347 .Xr ssh 1
348 will read this file when a login attempt is made.
349 .It Pa $HOME/.ssh/identity.pub
350 Contains the protocol version 1 RSA public key for authentication.
351 The contents of this file should be added to
352 .Pa $HOME/.ssh/authorized_keys
353 on all machines
354 where the user wishes to log in using RSA authentication.
355 There is no need to keep the contents of this file secret.
356 .It Pa $HOME/.ssh/id_dsa
357 Contains the protocol version 2 DSA authentication identity of the user.
358 This file should not be readable by anyone but the user.
359 It is possible to
360 specify a passphrase when generating the key; that passphrase will be
361 used to encrypt the private part of this file using 3DES.
362 This file is not automatically accessed by
363 .Nm
364 but it is offered as the default file for the private key.
365 .Xr ssh 1
366 will read this file when a login attempt is made.
367 .It Pa $HOME/.ssh/id_dsa.pub
368 Contains the protocol version 2 DSA public key for authentication.
369 The contents of this file should be added to
370 .Pa $HOME/.ssh/authorized_keys
371 on all machines
372 where the user wishes to log in using public key authentication.
373 There is no need to keep the contents of this file secret.
374 .It Pa $HOME/.ssh/id_rsa
375 Contains the protocol version 2 RSA authentication identity of the user.
376 This file should not be readable by anyone but the user.
377 It is possible to
378 specify a passphrase when generating the key; that passphrase will be
379 used to encrypt the private part of this file using 3DES.
380 This file is not automatically accessed by
381 .Nm
382 but it is offered as the default file for the private key.
383 .Xr ssh 1
384 will read this file when a login attempt is made.
385 .It Pa $HOME/.ssh/id_rsa.pub
386 Contains the protocol version 2 RSA public key for authentication.
387 The contents of this file should be added to
388 .Pa $HOME/.ssh/authorized_keys
389 on all machines
390 where the user wishes to log in using public key authentication.
391 There is no need to keep the contents of this file secret.
392 .It Pa /etc/moduli
393 Contains Diffie-Hellman groups used for DH-GEX.
394 The file format is described in
395 .Xr moduli 5 .
396 .El
397 .Sh SEE ALSO
398 .Xr ssh 1 ,
399 .Xr ssh-add 1 ,
400 .Xr ssh-agent 1 ,
401 .Xr moduli 5 ,
402 .Xr sshd 8
403 .Rs
404 .%A J. Galbraith
405 .%A R. Thayer
406 .%T "SECSH Public Key File Format"
407 .%N draft-ietf-secsh-publickeyfile-01.txt
408 .%D March 2001
409 .%O work in progress material
410 .Re
411 .Sh AUTHORS
412 OpenSSH is a derivative of the original and free
413 ssh 1.2.12 release by Tatu Ylonen.
414 Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
415 Theo de Raadt and Dug Song
416 removed many bugs, re-added newer features and
417 created OpenSSH.
418 Markus Friedl contributed the support for SSH
419 protocol versions 1.5 and 2.0.