summaryrefslogtreecommitdiff
path: root/ssh-keygen.0
diff options
context:
space:
mode:
Diffstat (limited to 'ssh-keygen.0')
-rw-r--r--ssh-keygen.0566
1 files changed, 566 insertions, 0 deletions
diff --git a/ssh-keygen.0 b/ssh-keygen.0
new file mode 100644
index 000000000..07a45b36b
--- /dev/null
+++ b/ssh-keygen.0
@@ -0,0 +1,566 @@
1SSH-KEYGEN(1) General Commands Manual SSH-KEYGEN(1)
2
3NAME
4 ssh-keygen M-bM-^@M-^S authentication key generation, management and conversion
5
6SYNOPSIS
7 ssh-keygen [-q] [-b bits] [-t dsa | ecdsa | ed25519 | rsa | rsa1]
8 [-N new_passphrase] [-C comment] [-f output_keyfile]
9 ssh-keygen -p [-P old_passphrase] [-N new_passphrase] [-f keyfile]
10 ssh-keygen -i [-m key_format] [-f input_keyfile]
11 ssh-keygen -e [-m key_format] [-f input_keyfile]
12 ssh-keygen -y [-f input_keyfile]
13 ssh-keygen -c [-P passphrase] [-C comment] [-f keyfile]
14 ssh-keygen -l [-v] [-E fingerprint_hash] [-f input_keyfile]
15 ssh-keygen -B [-f input_keyfile]
16 ssh-keygen -D pkcs11
17 ssh-keygen -F hostname [-f known_hosts_file] [-l]
18 ssh-keygen -H [-f known_hosts_file]
19 ssh-keygen -R hostname [-f known_hosts_file]
20 ssh-keygen -r hostname [-f input_keyfile] [-g]
21 ssh-keygen -G output_file [-v] [-b bits] [-M memory] [-S start_point]
22 ssh-keygen -T output_file -f input_file [-v] [-a rounds] [-J num_lines]
23 [-j start_line] [-K checkpt] [-W generator]
24 ssh-keygen -s ca_key -I certificate_identity [-h] [-n principals]
25 [-O option] [-V validity_interval] [-z serial_number] file ...
26 ssh-keygen -L [-f input_keyfile]
27 ssh-keygen -A
28 ssh-keygen -k -f krl_file [-u] [-s ca_public] [-z version_number]
29 file ...
30 ssh-keygen -Q -f krl_file file ...
31
32DESCRIPTION
33 ssh-keygen generates, manages and converts authentication keys for
34 ssh(1). ssh-keygen can create RSA keys for use by SSH protocol version 1
35 and DSA, ECDSA, Ed25519 or RSA keys for use by SSH protocol version 2.
36 The type of key to be generated is specified with the -t option. If
37 invoked without any arguments, ssh-keygen will generate an RSA key for
38 use in SSH protocol 2 connections.
39
40 ssh-keygen is also used to generate groups for use in Diffie-Hellman
41 group exchange (DH-GEX). See the MODULI GENERATION section for details.
42
43 Finally, ssh-keygen can be used to generate and update Key Revocation
44 Lists, and to test whether given keys have been revoked by one. See the
45 KEY REVOCATION LISTS section for details.
46
47 Normally each user wishing to use SSH with public key authentication runs
48 this once to create the authentication key in ~/.ssh/identity,
49 ~/.ssh/id_dsa, ~/.ssh/id_ecdsa, ~/.ssh/id_ed25519 or ~/.ssh/id_rsa.
50 Additionally, the system administrator may use this to generate host
51 keys, as seen in /etc/rc.
52
53 Normally this program generates the key and asks for a file in which to
54 store the private key. The public key is stored in a file with the same
55 name but M-bM-^@M-^\.pubM-bM-^@M-^] appended. The program also asks for a passphrase. The
56 passphrase may be empty to indicate no passphrase (host keys must have an
57 empty passphrase), or it may be a string of arbitrary length. A
58 passphrase is similar to a password, except it can be a phrase with a
59 series of words, punctuation, numbers, whitespace, or any string of
60 characters you want. Good passphrases are 10-30 characters long, are not
61 simple sentences or otherwise easily guessable (English prose has only
62 1-2 bits of entropy per character, and provides very bad passphrases),
63 and contain a mix of upper and lowercase letters, numbers, and non-
64 alphanumeric characters. The passphrase can be changed later by using
65 the -p option.
66
67 There is no way to recover a lost passphrase. If the passphrase is lost
68 or forgotten, a new key must be generated and the corresponding public
69 key copied to other machines.
70
71 For RSA1 keys, there is also a comment field in the key file that is only
72 for convenience to the user to help identify the key. The comment can
73 tell what the key is for, or whatever is useful. The comment is
74 initialized to M-bM-^@M-^\user@hostM-bM-^@M-^] when the key is created, but can be changed
75 using the -c option.
76
77 After a key is generated, instructions below detail where the keys should
78 be placed to be activated.
79
80 The options are as follows:
81
82 -A For each of the key types (rsa1, rsa, dsa, ecdsa and ed25519) for
83 which host keys do not exist, generate the host keys with the
84 default key file path, an empty passphrase, default bits for the
85 key type, and default comment. This is used by /etc/rc to
86 generate new host keys.
87
88 -a rounds
89 When saving a new-format private key (i.e. an ed25519 key or any
90 SSH protocol 2 key when the -o flag is set), this option
91 specifies the number of KDF (key derivation function) rounds
92 used. Higher numbers result in slower passphrase verification
93 and increased resistance to brute-force password cracking (should
94 the keys be stolen).
95
96 When screening DH-GEX candidates ( using the -T command). This
97 option specifies the number of primality tests to perform.
98
99 -B Show the bubblebabble digest of specified private or public key
100 file.
101
102 -b bits
103 Specifies the number of bits in the key to create. For RSA keys,
104 the minimum size is 1024 bits and the default is 2048 bits.
105 Generally, 2048 bits is considered sufficient. DSA keys must be
106 exactly 1024 bits as specified by FIPS 186-2. For ECDSA keys,
107 the -b flag determines the key length by selecting from one of
108 three elliptic curve sizes: 256, 384 or 521 bits. Attempting to
109 use bit lengths other than these three values for ECDSA keys will
110 fail. Ed25519 keys have a fixed length and the -b flag will be
111 ignored.
112
113 -C comment
114 Provides a new comment.
115
116 -c Requests changing the comment in the private and public key
117 files. This operation is only supported for RSA1 keys. The
118 program will prompt for the file containing the private keys, for
119 the passphrase if the key has one, and for the new comment.
120
121 -D pkcs11
122 Download the RSA public keys provided by the PKCS#11 shared
123 library pkcs11. When used in combination with -s, this option
124 indicates that a CA key resides in a PKCS#11 token (see the
125 CERTIFICATES section for details).
126
127 -E fingerprint_hash
128 Specifies the hash algorithm used when displaying key
129 fingerprints. Valid options are: M-bM-^@M-^\md5M-bM-^@M-^] and M-bM-^@M-^\sha256M-bM-^@M-^]. The
130 default is M-bM-^@M-^\sha256M-bM-^@M-^].
131
132 -e This option will read a private or public OpenSSH key file and
133 print to stdout the key in one of the formats specified by the -m
134 option. The default export format is M-bM-^@M-^\RFC4716M-bM-^@M-^]. This option
135 allows exporting OpenSSH keys for use by other programs,
136 including several commercial SSH implementations.
137
138 -F hostname
139 Search for the specified hostname in a known_hosts file, listing
140 any occurrences found. This option is useful to find hashed host
141 names or addresses and may also be used in conjunction with the
142 -H option to print found keys in a hashed format.
143
144 -f filename
145 Specifies the filename of the key file.
146
147 -G output_file
148 Generate candidate primes for DH-GEX. These primes must be
149 screened for safety (using the -T option) before use.
150
151 -g Use generic DNS format when printing fingerprint resource records
152 using the -r command.
153
154 -H Hash a known_hosts file. This replaces all hostnames and
155 addresses with hashed representations within the specified file;
156 the original content is moved to a file with a .old suffix.
157 These hashes may be used normally by ssh and sshd, but they do
158 not reveal identifying information should the file's contents be
159 disclosed. This option will not modify existing hashed hostnames
160 and is therefore safe to use on files that mix hashed and non-
161 hashed names.
162
163 -h When signing a key, create a host certificate instead of a user
164 certificate. Please see the CERTIFICATES section for details.
165
166 -I certificate_identity
167 Specify the key identity when signing a public key. Please see
168 the CERTIFICATES section for details.
169
170 -i This option will read an unencrypted private (or public) key file
171 in the format specified by the -m option and print an OpenSSH
172 compatible private (or public) key to stdout. This option allows
173 importing keys from other software, including several commercial
174 SSH implementations. The default import format is M-bM-^@M-^\RFC4716M-bM-^@M-^].
175
176 -J num_lines
177 Exit after screening the specified number of lines while
178 performing DH candidate screening using the -T option.
179
180 -j start_line
181 Start screening at the specified line number while performing DH
182 candidate screening using the -T option.
183
184 -K checkpt
185 Write the last line processed to the file checkpt while
186 performing DH candidate screening using the -T option. This will
187 be used to skip lines in the input file that have already been
188 processed if the job is restarted.
189
190 -k Generate a KRL file. In this mode, ssh-keygen will generate a
191 KRL file at the location specified via the -f flag that revokes
192 every key or certificate presented on the command line.
193 Keys/certificates to be revoked may be specified by public key
194 file or using the format described in the KEY REVOCATION LISTS
195 section.
196
197 -L Prints the contents of a certificate.
198
199 -l Show fingerprint of specified public key file. Private RSA1 keys
200 are also supported. For RSA and DSA keys ssh-keygen tries to
201 find the matching public key file and prints its fingerprint. If
202 combined with -v, an ASCII art representation of the key is
203 supplied with the fingerprint.
204
205 -M memory
206 Specify the amount of memory to use (in megabytes) when
207 generating candidate moduli for DH-GEX.
208
209 -m key_format
210 Specify a key format for the -i (import) or -e (export)
211 conversion options. The supported key formats are: M-bM-^@M-^\RFC4716M-bM-^@M-^]
212 (RFC 4716/SSH2 public or private key), M-bM-^@M-^\PKCS8M-bM-^@M-^] (PEM PKCS8 public
213 key) or M-bM-^@M-^\PEMM-bM-^@M-^] (PEM public key). The default conversion format is
214 M-bM-^@M-^\RFC4716M-bM-^@M-^].
215
216 -N new_passphrase
217 Provides the new passphrase.
218
219 -n principals
220 Specify one or more principals (user or host names) to be
221 included in a certificate when signing a key. Multiple
222 principals may be specified, separated by commas. Please see the
223 CERTIFICATES section for details.
224
225 -O option
226 Specify a certificate option when signing a key. This option may
227 be specified multiple times. Please see the CERTIFICATES section
228 for details. The options that are valid for user certificates
229 are:
230
231 clear Clear all enabled permissions. This is useful for
232 clearing the default set of permissions so permissions
233 may be added individually.
234
235 force-command=command
236 Forces the execution of command instead of any shell or
237 command specified by the user when the certificate is
238 used for authentication.
239
240 no-agent-forwarding
241 Disable ssh-agent(1) forwarding (permitted by default).
242
243 no-port-forwarding
244 Disable port forwarding (permitted by default).
245
246 no-pty Disable PTY allocation (permitted by default).
247
248 no-user-rc
249 Disable execution of ~/.ssh/rc by sshd(8) (permitted by
250 default).
251
252 no-x11-forwarding
253 Disable X11 forwarding (permitted by default).
254
255 permit-agent-forwarding
256 Allows ssh-agent(1) forwarding.
257
258 permit-port-forwarding
259 Allows port forwarding.
260
261 permit-pty
262 Allows PTY allocation.
263
264 permit-user-rc
265 Allows execution of ~/.ssh/rc by sshd(8).
266
267 permit-x11-forwarding
268 Allows X11 forwarding.
269
270 source-address=address_list
271 Restrict the source addresses from which the certificate
272 is considered valid. The address_list is a comma-
273 separated list of one or more address/netmask pairs in
274 CIDR format.
275
276 At present, no options are valid for host keys.
277
278 -o Causes ssh-keygen to save SSH protocol 2 private keys using the
279 new OpenSSH format rather than the more compatible PEM format.
280 The new format has increased resistance to brute-force password
281 cracking but is not supported by versions of OpenSSH prior to
282 6.5. Ed25519 keys always use the new private key format.
283
284 -P passphrase
285 Provides the (old) passphrase.
286
287 -p Requests changing the passphrase of a private key file instead of
288 creating a new private key. The program will prompt for the file
289 containing the private key, for the old passphrase, and twice for
290 the new passphrase.
291
292 -Q Test whether keys have been revoked in a KRL.
293
294 -q Silence ssh-keygen.
295
296 -R hostname
297 Removes all keys belonging to hostname from a known_hosts file.
298 This option is useful to delete hashed hosts (see the -H option
299 above).
300
301 -r hostname
302 Print the SSHFP fingerprint resource record named hostname for
303 the specified public key file.
304
305 -S start
306 Specify start point (in hex) when generating candidate moduli for
307 DH-GEX.
308
309 -s ca_key
310 Certify (sign) a public key using the specified CA key. Please
311 see the CERTIFICATES section for details.
312
313 When generating a KRL, -s specifies a path to a CA public key
314 file used to revoke certificates directly by key ID or serial
315 number. See the KEY REVOCATION LISTS section for details.
316
317 -T output_file
318 Test DH group exchange candidate primes (generated using the -G
319 option) for safety.
320
321 -t dsa | ecdsa | ed25519 | rsa | rsa1
322 Specifies the type of key to create. The possible values are
323 M-bM-^@M-^\rsa1M-bM-^@M-^] for protocol version 1 and M-bM-^@M-^\dsaM-bM-^@M-^], M-bM-^@M-^\ecdsaM-bM-^@M-^], M-bM-^@M-^\ed25519M-bM-^@M-^], or
324 M-bM-^@M-^\rsaM-bM-^@M-^] for protocol version 2.
325
326 -u Update a KRL. When specified with -k, keys listed via the
327 command line are added to the existing KRL rather than a new KRL
328 being created.
329
330 -V validity_interval
331 Specify a validity interval when signing a certificate. A
332 validity interval may consist of a single time, indicating that
333 the certificate is valid beginning now and expiring at that time,
334 or may consist of two times separated by a colon to indicate an
335 explicit time interval. The start time may be specified as a
336 date in YYYYMMDD format, a time in YYYYMMDDHHMMSS format or a
337 relative time (to the current time) consisting of a minus sign
338 followed by a relative time in the format described in the TIME
339 FORMATS section of sshd_config(5). The end time may be specified
340 as a YYYYMMDD date, a YYYYMMDDHHMMSS time or a relative time
341 starting with a plus character.
342
343 For example: M-bM-^@M-^\+52w1dM-bM-^@M-^] (valid from now to 52 weeks and one day
344 from now), M-bM-^@M-^\-4w:+4wM-bM-^@M-^] (valid from four weeks ago to four weeks
345 from now), M-bM-^@M-^\20100101123000:20110101123000M-bM-^@M-^] (valid from 12:30 PM,
346 January 1st, 2010 to 12:30 PM, January 1st, 2011), M-bM-^@M-^\-1d:20110101M-bM-^@M-^]
347 (valid from yesterday to midnight, January 1st, 2011).
348
349 -v Verbose mode. Causes ssh-keygen to print debugging messages
350 about its progress. This is helpful for debugging moduli
351 generation. Multiple -v options increase the verbosity. The
352 maximum is 3.
353
354 -W generator
355 Specify desired generator when testing candidate moduli for DH-
356 GEX.
357
358 -y This option will read a private OpenSSH format file and print an
359 OpenSSH public key to stdout.
360
361 -z serial_number
362 Specifies a serial number to be embedded in the certificate to
363 distinguish this certificate from others from the same CA. The
364 default serial number is zero.
365
366 When generating a KRL, the -z flag is used to specify a KRL
367 version number.
368
369MODULI GENERATION
370 ssh-keygen may be used to generate groups for the Diffie-Hellman Group
371 Exchange (DH-GEX) protocol. Generating these groups is a two-step
372 process: first, candidate primes are generated using a fast, but memory
373 intensive process. These candidate primes are then tested for
374 suitability (a CPU-intensive process).
375
376 Generation of primes is performed using the -G option. The desired
377 length of the primes may be specified by the -b option. For example:
378
379 # ssh-keygen -G moduli-2048.candidates -b 2048
380
381 By default, the search for primes begins at a random point in the desired
382 length range. This may be overridden using the -S option, which
383 specifies a different start point (in hex).
384
385 Once a set of candidates have been generated, they must be screened for
386 suitability. This may be performed using the -T option. In this mode
387 ssh-keygen will read candidates from standard input (or a file specified
388 using the -f option). For example:
389
390 # ssh-keygen -T moduli-2048 -f moduli-2048.candidates
391
392 By default, each candidate will be subjected to 100 primality tests.
393 This may be overridden using the -a option. The DH generator value will
394 be chosen automatically for the prime under consideration. If a specific
395 generator is desired, it may be requested using the -W option. Valid
396 generator values are 2, 3, and 5.
397
398 Screened DH groups may be installed in /etc/moduli. It is important that
399 this file contains moduli of a range of bit lengths and that both ends of
400 a connection share common moduli.
401
402CERTIFICATES
403 ssh-keygen supports signing of keys to produce certificates that may be
404 used for user or host authentication. Certificates consist of a public
405 key, some identity information, zero or more principal (user or host)
406 names and a set of options that are signed by a Certification Authority
407 (CA) key. Clients or servers may then trust only the CA key and verify
408 its signature on a certificate rather than trusting many user/host keys.
409 Note that OpenSSH certificates are a different, and much simpler, format
410 to the X.509 certificates used in ssl(8).
411
412 ssh-keygen supports two types of certificates: user and host. User
413 certificates authenticate users to servers, whereas host certificates
414 authenticate server hosts to users. To generate a user certificate:
415
416 $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
417
418 The resultant certificate will be placed in /path/to/user_key-cert.pub.
419 A host certificate requires the -h option:
420
421 $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
422
423 The host certificate will be output to /path/to/host_key-cert.pub.
424
425 It is possible to sign using a CA key stored in a PKCS#11 token by
426 providing the token library using -D and identifying the CA key by
427 providing its public half as an argument to -s:
428
429 $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id user_key.pub
430
431 In all cases, key_id is a "key identifier" that is logged by the server
432 when the certificate is used for authentication.
433
434 Certificates may be limited to be valid for a set of principal
435 (user/host) names. By default, generated certificates are valid for all
436 users or hosts. To generate a certificate for a specified set of
437 principals:
438
439 $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
440 $ ssh-keygen -s ca_key -I key_id -h -n host.domain host_key.pub
441
442 Additional limitations on the validity and use of user certificates may
443 be specified through certificate options. A certificate option may
444 disable features of the SSH session, may be valid only when presented
445 from particular source addresses or may force the use of a specific
446 command. For a list of valid certificate options, see the documentation
447 for the -O option above.
448
449 Finally, certificates may be defined with a validity lifetime. The -V
450 option allows specification of certificate start and end times. A
451 certificate that is presented at a time outside this range will not be
452 considered valid. By default, certificates are valid from UNIX Epoch to
453 the distant future.
454
455 For certificates to be used for user or host authentication, the CA
456 public key must be trusted by sshd(8) or ssh(1). Please refer to those
457 manual pages for details.
458
459KEY REVOCATION LISTS
460 ssh-keygen is able to manage OpenSSH format Key Revocation Lists (KRLs).
461 These binary files specify keys or certificates to be revoked using a
462 compact format, taking as little as one bit per certificate if they are
463 being revoked by serial number.
464
465 KRLs may be generated using the -k flag. This option reads one or more
466 files from the command line and generates a new KRL. The files may
467 either contain a KRL specification (see below) or public keys, listed one
468 per line. Plain public keys are revoked by listing their hash or
469 contents in the KRL and certificates revoked by serial number or key ID
470 (if the serial is zero or not available).
471
472 Revoking keys using a KRL specification offers explicit control over the
473 types of record used to revoke keys and may be used to directly revoke
474 certificates by serial number or key ID without having the complete
475 original certificate on hand. A KRL specification consists of lines
476 containing one of the following directives followed by a colon and some
477 directive-specific information.
478
479 serial: serial_number[-serial_number]
480 Revokes a certificate with the specified serial number. Serial
481 numbers are 64-bit values, not including zero and may be
482 expressed in decimal, hex or octal. If two serial numbers are
483 specified separated by a hyphen, then the range of serial numbers
484 including and between each is revoked. The CA key must have been
485 specified on the ssh-keygen command line using the -s option.
486
487 id: key_id
488 Revokes a certificate with the specified key ID string. The CA
489 key must have been specified on the ssh-keygen command line using
490 the -s option.
491
492 key: public_key
493 Revokes the specified key. If a certificate is listed, then it
494 is revoked as a plain public key.
495
496 sha1: public_key
497 Revokes the specified key by its SHA1 hash.
498
499 KRLs may be updated using the -u flag in addition to -k. When this
500 option is specified, keys listed via the command line are merged into the
501 KRL, adding to those already there.
502
503 It is also possible, given a KRL, to test whether it revokes a particular
504 key (or keys). The -Q flag will query an existing KRL, testing each key
505 specified on the commandline. If any key listed on the command line has
506 been revoked (or an error encountered) then ssh-keygen will exit with a
507 non-zero exit status. A zero exit status will only be returned if no key
508 was revoked.
509
510FILES
511 ~/.ssh/identity
512 Contains the protocol version 1 RSA authentication identity of
513 the user. This file should not be readable by anyone but the
514 user. It is possible to specify a passphrase when generating the
515 key; that passphrase will be used to encrypt the private part of
516 this file using 3DES. This file is not automatically accessed by
517 ssh-keygen but it is offered as the default file for the private
518 key. ssh(1) will read this file when a login attempt is made.
519
520 ~/.ssh/identity.pub
521 Contains the protocol version 1 RSA public key for
522 authentication. The contents of this file should be added to
523 ~/.ssh/authorized_keys on all machines where the user wishes to
524 log in using RSA authentication. There is no need to keep the
525 contents of this file secret.
526
527 ~/.ssh/id_dsa
528 ~/.ssh/id_ecdsa
529 ~/.ssh/id_ed25519
530 ~/.ssh/id_rsa
531 Contains the protocol version 2 DSA, ECDSA, Ed25519 or RSA
532 authentication identity of the user. This file should not be
533 readable by anyone but the user. It is possible to specify a
534 passphrase when generating the key; that passphrase will be used
535 to encrypt the private part of this file using 128-bit AES. This
536 file is not automatically accessed by ssh-keygen but it is
537 offered as the default file for the private key. ssh(1) will
538 read this file when a login attempt is made.
539
540 ~/.ssh/id_dsa.pub
541 ~/.ssh/id_ecdsa.pub
542 ~/.ssh/id_ed25519.pub
543 ~/.ssh/id_rsa.pub
544 Contains the protocol version 2 DSA, ECDSA, Ed25519 or RSA public
545 key for authentication. The contents of this file should be
546 added to ~/.ssh/authorized_keys on all machines where the user
547 wishes to log in using public key authentication. There is no
548 need to keep the contents of this file secret.
549
550 /etc/moduli
551 Contains Diffie-Hellman groups used for DH-GEX. The file format
552 is described in moduli(5).
553
554SEE ALSO
555 ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8)
556
557 The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006.
558
559AUTHORS
560 OpenSSH is a derivative of the original and free ssh 1.2.12 release by
561 Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo
562 de Raadt and Dug Song removed many bugs, re-added newer features and
563 created OpenSSH. Markus Friedl contributed the support for SSH protocol
564 versions 1.5 and 2.0.
565
566OpenBSD 5.8 August 20, 2015 OpenBSD 5.8