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