1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
1 |
SSH-KEYGEN(1) OpenBSD Reference Manual SSH-KEYGEN(1) |
2 |
||
3 |
NAME
|
|
4 |
ssh-keygen - authentication key generation, management and conversion |
|
5 |
||
6 |
SYNOPSIS
|
|
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 |
|
1.13.4
by Colin Watson
Import upstream version 5.2p1 |
17 |
ssh-keygen -F hostname [-f known_hosts_file] [-l] |
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
18 |
ssh-keygen -H [-f known_hosts_file] |
19 |
ssh-keygen -R hostname [-f known_hosts_file] |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
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 |
||
26 |
DESCRIPTION
|
|
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 |
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
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. |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
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 |
|
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
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. |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
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 |
||
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
75 |
-B Show the bubblebabble digest of specified private or public key |
76 |
file. |
|
77 |
||
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
78 |
-b bits |
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
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. |
|
1.2.1
by Martin Pitt
Import upstream version 4.2p1 |
83 |
|
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
84 |
-C comment |
85 |
Provides a new comment. |
|
86 |
||
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
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 |
||
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
92 |
-D reader |
93 |
Download the RSA public key stored in the smartcard in reader. |
|
94 |
||
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
95 |
-e This option will read a private or public OpenSSH key file and |
1.13.1
by Colin Watson
Import upstream version 4.6p1 |
96 |
print the key in RFC 4716 SSH Public Key File Format to stdout. |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
97 |
This option allows exporting keys for use by several commercial |
98 |
SSH implementations. |
|
99 |
||
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
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 |
||
1.1.1
by Colin Watson
Import upstream version 3.9p1 |
113 |
-g Use generic DNS format when printing fingerprint resource records |
114 |
using the -r command. |
|
1.2.1
by Martin Pitt
Import upstream version 4.2p1 |
115 |
|
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
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.
|
|
1.2.1
by Martin Pitt
Import upstream version 4.2p1 |
124 |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
125 |
-i This option will read an unencrypted private (or public) key file
|
126 |
in SSH2-compatible format and print an OpenSSH compatible private
|
|
1.13.1
by Colin Watson
Import upstream version 4.6p1 |
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.
|
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
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
|
|
1.13.3
by Colin Watson
Import upstream version 5.1p1 |
133 |
find the matching public key file and prints its fingerprint. If
|
134 |
combined with -v, an ASCII art representation of the key is sup-
|
|
135 |
plied with the fingerprint.
|
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
136 |
|
137 |
-M memory
|
|
138 |
Specify the amount of memory to use (in megabytes) when generat-
|
|
139 |
ing candidate moduli for DH-GEX.
|
|
140 |
||
141 |
-N new_passphrase
|
|
142 |
Provides the new passphrase.
|
|
143 |
||
144 |
-P passphrase
|
|
145 |
Provides the (old) passphrase.
|
|
146 |
||
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
147 |
-p Requests changing the passphrase of a private key file instead of
|
148 |
creating a new private key. The program will prompt for the file
|
|
149 |
containing the private key, for the old passphrase, and twice for
|
|
150 |
the new passphrase.
|
|
151 |
||
152 |
-q Silence ssh-keygen. Used by /etc/rc when creating a new key.
|
|
153 |
||
154 |
-R hostname
|
|
155 |
Removes all keys belonging to hostname from a known_hosts file.
|
|
156 |
This option is useful to delete hashed hosts (see the -H option
|
|
157 |
above).
|
|
158 |
||
159 |
-r hostname
|
|
160 |
Print the SSHFP fingerprint resource record named hostname for
|
|
161 |
the specified public key file.
|
|
162 |
||
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
163 |
-S start
|
164 |
Specify start point (in hex) when generating candidate moduli for
|
|
165 |
DH-GEX.
|
|
166 |
||
167 |
-T output_file
|
|
168 |
Test DH group exchange candidate primes (generated using the -G
|
|
169 |
option) for safety.
|
|
170 |
||
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
171 |
-t type
|
172 |
Specifies the type of key to create. The possible values are
|
|
173 |
``rsa1'' for protocol version 1 and ``rsa'' or ``dsa'' for proto- |
|
174 |
col version 2. |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
175 |
|
176 |
-U reader |
|
177 |
Upload an existing RSA private key into the smartcard in reader. |
|
178 |
||
179 |
-v Verbose mode. Causes ssh-keygen to print debugging messages |
|
180 |
about its progress. This is helpful for debugging moduli genera- |
|
181 |
tion. Multiple -v options increase the verbosity. The maximum |
|
182 |
is 3. |
|
183 |
||
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
184 |
-W generator |
185 |
Specify desired generator when testing candidate moduli for DH- |
|
186 |
GEX. |
|
187 |
||
188 |
-y This option will read a private OpenSSH format file and print an |
|
189 |
OpenSSH public key to stdout. |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
190 |
|
191 |
MODULI GENERATION |
|
192 |
ssh-keygen may be used to generate groups for the Diffie-Hellman Group |
|
193 |
Exchange (DH-GEX) protocol. Generating these groups is a two-step pro- |
|
194 |
cess: first, candidate primes are generated using a fast, but memory in- |
|
195 |
tensive process. These candidate primes are then tested for suitability |
|
196 |
(a CPU-intensive process). |
|
197 |
||
198 |
Generation of primes is performed using the -G option. The desired |
|
199 |
length of the primes may be specified by the -b option. For example: |
|
200 |
||
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
201 |
# ssh-keygen -G moduli-2048.candidates -b 2048 |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
202 |
|
203 |
By default, the search for primes begins at a random point in the desired |
|
204 |
length range. This may be overridden using the -S option, which speci- |
|
205 |
fies a different start point (in hex). |
|
206 |
||
207 |
Once a set of candidates have been generated, they must be tested for |
|
208 |
suitability. This may be performed using the -T option. In this mode |
|
209 |
ssh-keygen will read candidates from standard input (or a file specified |
|
210 |
using the -f option). For example: |
|
211 |
||
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
212 |
# ssh-keygen -T moduli-2048 -f moduli-2048.candidates |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
213 |
|
214 |
By default, each candidate will be subjected to 100 primality tests. |
|
215 |
This may be overridden using the -a option. The DH generator value will |
|
216 |
be chosen automatically for the prime under consideration. If a specific |
|
217 |
generator is desired, it may be requested using the -W option. Valid |
|
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
218 |
generator values are 2, 3, and 5. |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
219 |
|
220 |
Screened DH groups may be installed in /etc/moduli. It is important that |
|
221 |
this file contains moduli of a range of bit lengths and that both ends of |
|
222 |
a connection share common moduli. |
|
223 |
||
224 |
FILES
|
|
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
225 |
~/.ssh/identity |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
226 |
Contains the protocol version 1 RSA authentication identity of |
227 |
the user. This file should not be readable by anyone but the us- |
|
228 |
er. It is possible to specify a passphrase when generating the |
|
229 |
key; that passphrase will be used to encrypt the private part of |
|
230 |
this file using 3DES. This file is not automatically accessed by |
|
231 |
ssh-keygen but it is offered as the default file for the private |
|
232 |
key. ssh(1) will read this file when a login attempt is made. |
|
233 |
||
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
234 |
~/.ssh/identity.pub |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
235 |
Contains the protocol version 1 RSA public key for authentica- |
236 |
tion. The contents of this file should be added to |
|
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
237 |
~/.ssh/authorized_keys on all machines where the user wishes to |
238 |
log in using RSA authentication. There is no need to keep the |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
239 |
contents of this file secret. |
240 |
||
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
241 |
~/.ssh/id_dsa |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
242 |
Contains the protocol version 2 DSA authentication identity of |
243 |
the user. This file should not be readable by anyone but the us- |
|
244 |
er. It is possible to specify a passphrase when generating the |
|
245 |
key; that passphrase will be used to encrypt the private part of |
|
246 |
this file using 3DES. This file is not automatically accessed by |
|
247 |
ssh-keygen but it is offered as the default file for the private |
|
248 |
key. ssh(1) will read this file when a login attempt is made. |
|
249 |
||
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
250 |
~/.ssh/id_dsa.pub |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
251 |
Contains the protocol version 2 DSA public key for authentica- |
252 |
tion. The contents of this file should be added to |
|
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
253 |
~/.ssh/authorized_keys on all machines where the user wishes to |
254 |
log in using public key authentication. There is no need to keep |
|
255 |
the contents of this file secret. |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
256 |
|
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
257 |
~/.ssh/id_rsa |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
258 |
Contains the protocol version 2 RSA authentication identity of |
259 |
the user. This file should not be readable by anyone but the us- |
|
260 |
er. It is possible to specify a passphrase when generating the |
|
261 |
key; that passphrase will be used to encrypt the private part of |
|
262 |
this file using 3DES. This file is not automatically accessed by |
|
263 |
ssh-keygen but it is offered as the default file for the private |
|
264 |
key. ssh(1) will read this file when a login attempt is made. |
|
265 |
||
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
266 |
~/.ssh/id_rsa.pub |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
267 |
Contains the protocol version 2 RSA public key for authentica- |
268 |
tion. The contents of this file should be added to |
|
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
269 |
~/.ssh/authorized_keys on all machines where the user wishes to |
270 |
log in using public key authentication. There is no need to keep |
|
271 |
the contents of this file secret. |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
272 |
|
273 |
/etc/moduli |
|
274 |
Contains Diffie-Hellman groups used for DH-GEX. The file format |
|
275 |
is described in moduli(5). |
|
276 |
||
277 |
SEE ALSO |
|
278 |
ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8) |
|
279 |
||
1.13.1
by Colin Watson
Import upstream version 4.6p1 |
280 |
The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006. |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
281 |
|
282 |
AUTHORS
|
|
283 |
OpenSSH is a derivative of the original and free ssh 1.2.12 release by |
|
284 |
Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo |
|
285 |
de Raadt and Dug Song removed many bugs, re-added newer features and |
|
286 |
created OpenSSH. Markus Friedl contributed the support for SSH protocol |
|
287 |
versions 1.5 and 2.0. |
|
288 |
||
1.13.5
by Colin Watson
Import upstream version 5.3p1 |
289 |
OpenBSD 4.6 July 24, 2008 5 |