| blob | 9e59c16f7bda91258f7daefbff5b487ecf38a975 |
1 .\" $OpenBSD: ssh-keygen.1,v 1.80 2009/10/24 00:48:34 dtucker 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 $Mdocdate: October 24 2009 $
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 F Ar hostname
85 .Op Fl f Ar known_hosts_file
86 .Op Fl l
87 .Nm ssh-keygen
88 .Fl H
89 .Op Fl f Ar known_hosts_file
90 .Nm ssh-keygen
91 .Fl R Ar hostname
92 .Op Fl f Ar known_hosts_file
93 .Nm ssh-keygen
94 .Fl U Ar reader
95 .Op Fl f Ar input_keyfile
96 .Nm ssh-keygen
97 .Fl r Ar hostname
98 .Op Fl f Ar input_keyfile
99 .Op Fl g
100 .Nm ssh-keygen
101 .Fl G Ar output_file
102 .Op Fl v
103 .Op Fl b Ar bits
104 .Op Fl M Ar memory
105 .Op Fl S Ar start_point
106 .Nm ssh-keygen
107 .Fl T Ar output_file
108 .Fl f Ar input_file
109 .Op Fl v
110 .Op Fl a Ar num_trials
111 .Op Fl W Ar generator
112 .Sh DESCRIPTION
113 .Nm
114 generates, manages and converts authentication keys for
115 .Xr ssh 1 .
116 .Nm
117 can create RSA keys for use by SSH protocol version 1 and RSA or DSA
118 keys for use by SSH protocol version 2.
119 The type of key to be generated is specified with the
120 .Fl t
121 option.
122 If invoked without any arguments,
123 .Nm
124 will generate an RSA key for use in SSH protocol 2 connections.
125 .Pp
126 .Nm
127 is also used to generate groups for use in Diffie-Hellman group
128 exchange (DH-GEX).
129 See the
130 .Sx MODULI GENERATION
131 section for details.
132 .Pp
133 Normally each user wishing to use SSH
134 with RSA or DSA authentication runs this once to create the authentication
135 key in
136 .Pa ~/.ssh/identity ,
137 .Pa ~/.ssh/id_dsa
138 or
139 .Pa ~/.ssh/id_rsa .
140 Additionally, the system administrator may use this to generate host keys,
141 as seen in
142 .Pa /etc/rc .
143 .Pp
144 Normally this program generates the key and asks for a file in which
145 to store the private key.
146 The public key is stored in a file with the same name but
147 .Dq .pub
148 appended.
149 The program also asks for a passphrase.
150 The passphrase may be empty to indicate no passphrase
151 (host keys must have an empty passphrase), or it may be a string of
152 arbitrary length.
153 A passphrase is similar to a password, except it can be a phrase with a
154 series of words, punctuation, numbers, whitespace, or any string of
155 characters you want.
156 Good passphrases are 10-30 characters long, are
157 not simple sentences or otherwise easily guessable (English
158 prose has only 1-2 bits of entropy per character, and provides very bad
159 passphrases), and contain a mix of upper and lowercase letters,
160 numbers, and non-alphanumeric characters.
161 The passphrase can be changed later by using the
162 .Fl p
163 option.
164 .Pp
165 There is no way to recover a lost passphrase.
166 If the passphrase is
167 lost or forgotten, a new key must be generated and copied to the
168 corresponding public key to other machines.
169 .Pp
170 For RSA1 keys,
171 there is also a comment field in the key file that is only for
172 convenience to the user to help identify the key.
173 The comment can tell what the key is for, or whatever is useful.
174 The comment is initialized to
175 .Dq user@host
176 when the key is created, but can be changed using the
177 .Fl c
178 option.
179 .Pp
180 After a key is generated, instructions below detail where the keys
181 should be placed to be activated.
182 .Pp
183 The options are as follows:
184 .Bl -tag -width Ds
185 .It Fl a Ar trials
186 Specifies the number of primality tests to perform when screening DH-GEX
187 candidates using the
188 .Fl T
189 command.
190 .It Fl B
191 Show the bubblebabble digest of specified private or public key file.
192 .It Fl b Ar bits
193 Specifies the number of bits in the key to create.
194 For RSA keys, the minimum size is 768 bits and the default is 2048 bits.
195 Generally, 2048 bits is considered sufficient.
196 DSA keys must be exactly 1024 bits as specified by FIPS 186-2.
197 .It Fl C Ar comment
198 Provides a new comment.
199 .It Fl c
200 Requests changing the comment in the private and public key files.
201 This operation is only supported for RSA1 keys.
202 The program will prompt for the file containing the private keys, for
203 the passphrase if the key has one, and for the new comment.
204 .It Fl D Ar reader
205 Download the RSA public key stored in the smartcard in
206 .Ar reader .
207 .It Fl e
208 This option will read a private or public OpenSSH key file and
209 print the key in
210 RFC 4716 SSH Public Key File Format
211 to stdout.
212 This option allows exporting keys for use by several commercial
213 SSH implementations.
214 .It Fl F Ar hostname
215 Search for the specified
216 .Ar hostname
217 in a
218 .Pa known_hosts
219 file, listing any occurrences found.
220 This option is useful to find hashed host names or addresses and may also be
221 used in conjunction with the
222 .Fl H
223 option to print found keys in a hashed format.
224 .It Fl f Ar filename
225 Specifies the filename of the key file.
226 .It Fl G Ar output_file
227 Generate candidate primes for DH-GEX.
228 These primes must be screened for
229 safety (using the
230 .Fl T
231 option) before use.
232 .It Fl g
233 Use generic DNS format when printing fingerprint resource records using the
234 .Fl r
235 command.
236 .It Fl H
237 Hash a
238 .Pa known_hosts
239 file.
240 This replaces all hostnames and addresses with hashed representations
241 within the specified file; the original content is moved to a file with
242 a .old suffix.
243 These hashes may be used normally by
244 .Nm ssh
245 and
246 .Nm sshd ,
247 but they do not reveal identifying information should the file's contents
248 be disclosed.
249 This option will not modify existing hashed hostnames and is therefore safe
250 to use on files that mix hashed and non-hashed names.
251 .It Fl i
252 This option will read an unencrypted private (or public) key file
253 in SSH2-compatible format and print an OpenSSH compatible private
254 (or public) key to stdout.
255 .Nm
256 also reads the
257 RFC 4716 SSH Public Key File Format.
258 This option allows importing keys from several commercial
259 SSH implementations.
260 .It Fl l
261 Show fingerprint of specified public key file.
262 Private RSA1 keys are also supported.
263 For RSA and DSA keys
264 .Nm
265 tries to find the matching public key file and prints its fingerprint.
266 If combined with
267 .Fl v ,
268 an ASCII art representation of the key is supplied with the fingerprint.
269 .It Fl M Ar memory
270 Specify the amount of memory to use (in megabytes) when generating
271 candidate moduli for DH-GEX.
272 .It Fl N Ar new_passphrase
273 Provides the new passphrase.
274 .It Fl P Ar passphrase
275 Provides the (old) passphrase.
276 .It Fl p
277 Requests changing the passphrase of a private key file instead of
278 creating a new private key.
279 The program will prompt for the file
280 containing the private key, for the old passphrase, and twice for the
281 new passphrase.
282 .It Fl q
283 Silence
284 .Nm ssh-keygen .
285 Used by
286 .Pa /etc/rc
287 when creating a new key.
288 .It Fl R Ar hostname
289 Removes all keys belonging to
290 .Ar hostname
291 from a
292 .Pa known_hosts
293 file.
294 This option is useful to delete hashed hosts (see the
295 .Fl H
296 option above).
297 .It Fl r Ar hostname
298 Print the SSHFP fingerprint resource record named
299 .Ar hostname
300 for the specified public key file.
301 .It Fl S Ar start
302 Specify start point (in hex) when generating candidate moduli for DH-GEX.
303 .It Fl T Ar output_file
304 Test DH group exchange candidate primes (generated using the
305 .Fl G
306 option) for safety.
307 .It Fl t Ar type
308 Specifies the type of key to create.
309 The possible values are
310 .Dq rsa1
311 for protocol version 1 and
312 .Dq rsa
313 or
314 .Dq dsa
315 for protocol version 2.
316 .It Fl U Ar reader
317 Upload an existing RSA private key into the smartcard in
318 .Ar reader .
319 .It Fl v
320 Verbose mode.
321 Causes
322 .Nm
323 to print debugging messages about its progress.
324 This is helpful for debugging moduli generation.
325 Multiple
326 .Fl v
327 options increase the verbosity.
328 The maximum is 3.
329 .It Fl W Ar generator
330 Specify desired generator when testing candidate moduli for DH-GEX.
331 .It Fl y
332 This option will read a private
333 OpenSSH format file and print an OpenSSH public key to stdout.
334 .El
335 .Sh MODULI GENERATION
336 .Nm
337 may be used to generate groups for the Diffie-Hellman Group Exchange
338 (DH-GEX) protocol.
339 Generating these groups is a two-step process: first, candidate
340 primes are generated using a fast, but memory intensive process.
341 These candidate primes are then tested for suitability (a CPU-intensive
342 process).
343 .Pp
344 Generation of primes is performed using the
345 .Fl G
346 option.
347 The desired length of the primes may be specified by the
348 .Fl b
349 option.
350 For example:
351 .Pp
352 .Dl # ssh-keygen -G moduli-2048.candidates -b 2048
353 .Pp
354 By default, the search for primes begins at a random point in the
355 desired length range.
356 This may be overridden using the
357 .Fl S
358 option, which specifies a different start point (in hex).
359 .Pp
360 Once a set of candidates have been generated, they must be tested for
361 suitability.
362 This may be performed using the
363 .Fl T
364 option.
365 In this mode
366 .Nm
367 will read candidates from standard input (or a file specified using the
368 .Fl f
369 option).
370 For example:
371 .Pp
372 .Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates
373 .Pp
374 By default, each candidate will be subjected to 100 primality tests.
375 This may be overridden using the
376 .Fl a
377 option.
378 The DH generator value will be chosen automatically for the
379 prime under consideration.
380 If a specific generator is desired, it may be requested using the
381 .Fl W
382 option.
383 Valid generator values are 2, 3, and 5.
384 .Pp
385 Screened DH groups may be installed in
386 .Pa /etc/moduli .
387 It is important that this file contains moduli of a range of bit lengths and
388 that both ends of a connection share common moduli.
389 .Sh FILES
390 .Bl -tag -width Ds
391 .It Pa ~/.ssh/identity
392 Contains the protocol version 1 RSA authentication identity of the user.
393 This file should not be readable by anyone but the user.
394 It is possible to
395 specify a passphrase when generating the key; that passphrase will be
396 used to encrypt the private part of this file using 128-bit AES.
397 This file is not automatically accessed by
398 .Nm
399 but it is offered as the default file for the private key.
400 .Xr ssh 1
401 will read this file when a login attempt is made.
402 .It Pa ~/.ssh/identity.pub
403 Contains the protocol version 1 RSA public key for authentication.
404 The contents of this file should be added to
405 .Pa ~/.ssh/authorized_keys
406 on all machines
407 where the user wishes to log in using RSA authentication.
408 There is no need to keep the contents of this file secret.
409 .It Pa ~/.ssh/id_dsa
410 Contains the protocol version 2 DSA authentication identity of the user.
411 This file should not be readable by anyone but the user.
412 It is possible to
413 specify a passphrase when generating the key; that passphrase will be
414 used to encrypt the private part of this file using 128-bit AES.
415 This file is not automatically accessed by
416 .Nm
417 but it is offered as the default file for the private key.
418 .Xr ssh 1
419 will read this file when a login attempt is made.
420 .It Pa ~/.ssh/id_dsa.pub
421 Contains the protocol version 2 DSA public key for authentication.
422 The contents of this file should be added to
423 .Pa ~/.ssh/authorized_keys
424 on all machines
425 where the user wishes to log in using public key authentication.
426 There is no need to keep the contents of this file secret.
427 .It Pa ~/.ssh/id_rsa
428 Contains the protocol version 2 RSA authentication identity of the user.
429 This file should not be readable by anyone but the user.
430 It is possible to
431 specify a passphrase when generating the key; that passphrase will be
432 used to encrypt the private part of this file using 128-bit AES.
433 This file is not automatically accessed by
434 .Nm
435 but it is offered as the default file for the private key.
436 .Xr ssh 1
437 will read this file when a login attempt is made.
438 .It Pa ~/.ssh/id_rsa.pub
439 Contains the protocol version 2 RSA public key for authentication.
440 The contents of this file should be added to
441 .Pa ~/.ssh/authorized_keys
442 on all machines
443 where the user wishes to log in using public key authentication.
444 There is no need to keep the contents of this file secret.
445 .It Pa /etc/moduli
446 Contains Diffie-Hellman groups used for DH-GEX.
447 The file format is described in
448 .Xr moduli 5 .
449 .El
450 .Sh SEE ALSO
451 .Xr ssh 1 ,
452 .Xr ssh-add 1 ,
453 .Xr ssh-agent 1 ,
454 .Xr moduli 5 ,
455 .Xr sshd 8
456 .Rs
457 .%R RFC 4716
458 .%T "The Secure Shell (SSH) Public Key File Format"
459 .%D 2006
460 .Re
461 .Sh AUTHORS
462 OpenSSH is a derivative of the original and free
463 ssh 1.2.12 release by Tatu Ylonen.
464 Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
465 Theo de Raadt and Dug Song
466 removed many bugs, re-added newer features and
467 created OpenSSH.
468 Markus Friedl contributed the support for SSH
469 protocol versions 1.5 and 2.0.