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