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