1SSH-KEYGEN(1) BSD General Commands Manual SSH-KEYGEN(1)
2
4 ssh-keygen — authentication key generation, management and conversion
5
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]
24 [-W generator]
25
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 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 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 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
48 series of words, punctuation, numbers, whitespace, or any string of char‐
49 acters you want. Good passphrases are 10-30 characters long, are not
50 simple sentences or otherwise easily guessable (English prose has only
51 1-2 bits of entropy per character, and provides very bad passphrases),
52 and contain a mix of upper and lowercase letters, numbers, and non-
53 alphanumeric characters. The passphrase can be changed later by using
54 the -p option.
55 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 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 the
64 -c option.
65 After a key is generated, instructions below detail where the keys should
67 be placed to be activated.
68 The options are as follows:
70 -a trials
72 Specifies the number of primality tests to perform when screening
73 DH-GEX candidates using the -T command.
74 -B Show the bubblebabble digest of specified private or public key
76 file.
77 -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
82 exactly 1024 bits as specified by FIPS 186-2.
83 -C comment
85 Provides a new comment.
86 -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 -D reader
93 Download the RSA public key stored in the smartcard in reader.
94 -e This option will read a private or public OpenSSH key file and
96 print the key in a ‘SECSH Public Key File Format’ to stdout.
97 This option allows exporting keys for use by several commercial
98 SSH implementations.
99 -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 -f filename
107 Specifies the filename of the key file.
108 -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 -g Use generic DNS format when printing fingerprint resource records
114 using the -r command.
115 -H Hash a known_hosts file. This replaces all hostnames and
117 addresses 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 -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 ‘SECSH
128 Public Key File Format’. This option allows importing keys from
129 several commercial SSH implementations.
130 -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 -M memory
136 Specify the amount of memory to use (in megabytes) when generat‐
137 ing candidate moduli for DH-GEX.
138 -N new_passphrase
140 Provides the new passphrase.
141 -P passphrase
143 Provides the (old) passphrase.
144 -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 -q Silence ssh-keygen. Used by /etc/rc when creating a new key.
151 -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 -r hostname
158 Print the SSHFP fingerprint resource record named hostname for
159 the specified public key file.
160 -S start
162 Specify start point (in hex) when generating candidate moduli for
163 DH-GEX.
164 -T output_file
166 Test DH group exchange candidate primes (generated using the -G
167 option) for safety.
168 -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 protocol
172 version 2.
173 -U reader
175 Upload an existing RSA private key into the smartcard in reader.
176 -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 -W generator
183 Specify desired generator when testing candidate moduli for DH-
184 GEX.
185 -y This option will read a private OpenSSH format file and print an
187 OpenSSH public key to stdout.
188
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
192 process: first, candidate primes are generated using a fast, but memory
193 intensive process. These candidate primes are then tested for suitabil‐
194 ity (a CPU-intensive process).
195 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 # ssh-keygen -G moduli-2048.candidates -b 2048
200 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 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 # ssh-keygen -T moduli-2048 -f moduli-2048.candidates
211 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 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
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
226 user. 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 ~/.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 ~/.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
242 user. 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 ~/.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 ~/.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
258 user. 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 ~/.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 /etc/moduli
272 Contains Diffie-Hellman groups used for DH-GEX. The file format
273 is described in moduli(5).
274
276 ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8)
277 J. Galbraith and R. Thayer, SECSH Public Key File Format, draft-ietf-
279 secsh-publickeyfile-01.txt, March 2001, work in progress material.
280
282 OpenSSH is a derivative of the original and free ssh 1.2.12 release by
283 Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo
284 de Raadt and Dug Song removed many bugs, re-added newer features and cre‐
285 ated OpenSSH. Markus Friedl contributed the support for SSH protocol
286 versions 1.5 and 2.0.
287BSD September 25, 1999 BSD