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