diff options
Diffstat (limited to 'ssh-keygen.1')
-rw-r--r-- | ssh-keygen.1 | 210 |
1 files changed, 194 insertions, 16 deletions
diff --git a/ssh-keygen.1 b/ssh-keygen.1 index 3596cc174..6557f9336 100644 --- a/ssh-keygen.1 +++ b/ssh-keygen.1 | |||
@@ -1,4 +1,4 @@ | |||
1 | .\" $OpenBSD: ssh-keygen.1,v 1.79 2008/07/24 23:55:30 sthen Exp $ | 1 | .\" $OpenBSD: ssh-keygen.1,v 1.88 2010/03/08 00:28:55 djm Exp $ |
2 | .\" | 2 | .\" |
3 | .\" -*- nroff -*- | 3 | .\" -*- nroff -*- |
4 | .\" | 4 | .\" |
@@ -37,7 +37,7 @@ | |||
37 | .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF | 37 | .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
38 | .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | 38 | .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
39 | .\" | 39 | .\" |
40 | .Dd $Mdocdate: July 24 2008 $ | 40 | .Dd $Mdocdate: March 8 2010 $ |
41 | .Dt SSH-KEYGEN 1 | 41 | .Dt SSH-KEYGEN 1 |
42 | .Os | 42 | .Os |
43 | .Sh NAME | 43 | .Sh NAME |
@@ -52,7 +52,6 @@ | |||
52 | .Op Fl N Ar new_passphrase | 52 | .Op Fl N Ar new_passphrase |
53 | .Op Fl C Ar comment | 53 | .Op Fl C Ar comment |
54 | .Op Fl f Ar output_keyfile | 54 | .Op Fl f Ar output_keyfile |
55 | .Ek | ||
56 | .Nm ssh-keygen | 55 | .Nm ssh-keygen |
57 | .Fl p | 56 | .Fl p |
58 | .Op Fl P Ar old_passphrase | 57 | .Op Fl P Ar old_passphrase |
@@ -79,7 +78,7 @@ | |||
79 | .Fl B | 78 | .Fl B |
80 | .Op Fl f Ar input_keyfile | 79 | .Op Fl f Ar input_keyfile |
81 | .Nm ssh-keygen | 80 | .Nm ssh-keygen |
82 | .Fl D Ar reader | 81 | .Fl D Ar pkcs11 |
83 | .Nm ssh-keygen | 82 | .Nm ssh-keygen |
84 | .Fl F Ar hostname | 83 | .Fl F Ar hostname |
85 | .Op Fl f Ar known_hosts_file | 84 | .Op Fl f Ar known_hosts_file |
@@ -91,9 +90,6 @@ | |||
91 | .Fl R Ar hostname | 90 | .Fl R Ar hostname |
92 | .Op Fl f Ar known_hosts_file | 91 | .Op Fl f Ar known_hosts_file |
93 | .Nm ssh-keygen | 92 | .Nm ssh-keygen |
94 | .Fl U Ar reader | ||
95 | .Op Fl f Ar input_keyfile | ||
96 | .Nm ssh-keygen | ||
97 | .Fl r Ar hostname | 93 | .Fl r Ar hostname |
98 | .Op Fl f Ar input_keyfile | 94 | .Op Fl f Ar input_keyfile |
99 | .Op Fl g | 95 | .Op Fl g |
@@ -109,6 +105,18 @@ | |||
109 | .Op Fl v | 105 | .Op Fl v |
110 | .Op Fl a Ar num_trials | 106 | .Op Fl a Ar num_trials |
111 | .Op Fl W Ar generator | 107 | .Op Fl W Ar generator |
108 | .Nm ssh-keygen | ||
109 | .Fl s Ar ca_key | ||
110 | .Fl I Ar certificate_identity | ||
111 | .Op Fl h | ||
112 | .Op Fl n Ar principals | ||
113 | .Op Fl O Ar constraint | ||
114 | .Op Fl V Ar validity_interval | ||
115 | .Ar | ||
116 | .Nm ssh-keygen | ||
117 | .Fl L | ||
118 | .Op Fl f Ar input_keyfile | ||
119 | .Ek | ||
112 | .Sh DESCRIPTION | 120 | .Sh DESCRIPTION |
113 | .Nm | 121 | .Nm |
114 | generates, manages and converts authentication keys for | 122 | generates, manages and converts authentication keys for |
@@ -201,9 +209,9 @@ Requests changing the comment in the private and public key files. | |||
201 | This operation is only supported for RSA1 keys. | 209 | This operation is only supported for RSA1 keys. |
202 | The program will prompt for the file containing the private keys, for | 210 | The program will prompt for the file containing the private keys, for |
203 | the passphrase if the key has one, and for the new comment. | 211 | the passphrase if the key has one, and for the new comment. |
204 | .It Fl D Ar reader | 212 | .It Fl D Ar pkcs11 |
205 | Download the RSA public key stored in the smartcard in | 213 | Download the RSA public keys provided by the PKCS#11 shared library |
206 | .Ar reader . | 214 | .Ar pkcs11 . |
207 | .It Fl e | 215 | .It Fl e |
208 | This option will read a private or public OpenSSH key file and | 216 | This option will read a private or public OpenSSH key file and |
209 | print the key in | 217 | print the key in |
@@ -248,6 +256,17 @@ but they do not reveal identifying information should the file's contents | |||
248 | be disclosed. | 256 | be disclosed. |
249 | This option will not modify existing hashed hostnames and is therefore safe | 257 | This option will not modify existing hashed hostnames and is therefore safe |
250 | to use on files that mix hashed and non-hashed names. | 258 | to use on files that mix hashed and non-hashed names. |
259 | .It Fl h | ||
260 | When signing a key, create a host certificate instead of a user | ||
261 | certificate. | ||
262 | Please see the | ||
263 | .Sx CERTIFICATES | ||
264 | section for details. | ||
265 | .It Fl I Ar certificate_identity | ||
266 | Specify the key identity when signing a public key. | ||
267 | Please see the | ||
268 | .Sx CERTIFICATES | ||
269 | section for details. | ||
251 | .It Fl i | 270 | .It Fl i |
252 | This option will read an unencrypted private (or public) key file | 271 | This option will read an unencrypted private (or public) key file |
253 | in SSH2-compatible format and print an OpenSSH compatible private | 272 | in SSH2-compatible format and print an OpenSSH compatible private |
@@ -257,6 +276,8 @@ also reads the | |||
257 | RFC 4716 SSH Public Key File Format. | 276 | RFC 4716 SSH Public Key File Format. |
258 | This option allows importing keys from several commercial | 277 | This option allows importing keys from several commercial |
259 | SSH implementations. | 278 | SSH implementations. |
279 | .It Fl L | ||
280 | Prints the contents of a certificate. | ||
260 | .It Fl l | 281 | .It Fl l |
261 | Show fingerprint of specified public key file. | 282 | Show fingerprint of specified public key file. |
262 | Private RSA1 keys are also supported. | 283 | Private RSA1 keys are also supported. |
@@ -271,6 +292,71 @@ Specify the amount of memory to use (in megabytes) when generating | |||
271 | candidate moduli for DH-GEX. | 292 | candidate moduli for DH-GEX. |
272 | .It Fl N Ar new_passphrase | 293 | .It Fl N Ar new_passphrase |
273 | Provides the new passphrase. | 294 | Provides the new passphrase. |
295 | .It Fl n Ar principals | ||
296 | Specify one or more principals (user or host names) to be included in | ||
297 | a certificate when signing a key. | ||
298 | Multiple principals may be specified, separated by commas. | ||
299 | Please see the | ||
300 | .Sx CERTIFICATES | ||
301 | section for details. | ||
302 | .It Fl O Ar constraint | ||
303 | Specify a certificate constraint when signing a key. | ||
304 | This option may be specified multiple times. | ||
305 | Please see the | ||
306 | .Sx CERTIFICATES | ||
307 | section for details. | ||
308 | The constraints that are valid for user certificates are: | ||
309 | .Bl -tag -width Ds | ||
310 | .It Ic no-x11-forwarding | ||
311 | Disable X11 forwarding (permitted by default). | ||
312 | .It Ic no-agent-forwarding | ||
313 | Disable | ||
314 | .Xr ssh-agent 1 | ||
315 | forwarding (permitted by default). | ||
316 | .It Ic no-port-forwarding | ||
317 | Disable port forwarding (permitted by default). | ||
318 | .It Ic no-pty | ||
319 | Disable PTY allocation (permitted by default). | ||
320 | .It Ic no-user-rc | ||
321 | Disable execution of | ||
322 | .Pa ~/.ssh/rc | ||
323 | by | ||
324 | .Xr sshd 8 | ||
325 | (permitted by default). | ||
326 | .It Ic clear | ||
327 | Clear all enabled permissions. | ||
328 | This is useful for clearing the default set of permissions so permissions may | ||
329 | be added individually. | ||
330 | .It Ic permit-x11-forwarding | ||
331 | Allows X11 forwarding. | ||
332 | .It Ic permit-agent-forwarding | ||
333 | Allows | ||
334 | .Xr ssh-agent 1 | ||
335 | forwarding. | ||
336 | .It Ic permit-port-forwarding | ||
337 | Allows port forwarding. | ||
338 | .It Ic permit-pty | ||
339 | Allows PTY allocation. | ||
340 | .It Ic permit-user-rc | ||
341 | Allows execution of | ||
342 | .Pa ~/.ssh/rc | ||
343 | by | ||
344 | .Xr sshd 8 . | ||
345 | .It Ic force-command=command | ||
346 | Forces the execution of | ||
347 | .Ar command | ||
348 | instead of any shell or command specified by the user when | ||
349 | the certificate is used for authentication. | ||
350 | .It Ic source-address=address_list | ||
351 | Restrict the source addresses from which the certificate is considered valid | ||
352 | from. | ||
353 | The | ||
354 | .Ar address_list | ||
355 | is a comma-separated list of one or more address/netmask pairs in CIDR | ||
356 | format. | ||
357 | .El | ||
358 | .Pp | ||
359 | At present, no constraints are valid for host keys. | ||
274 | .It Fl P Ar passphrase | 360 | .It Fl P Ar passphrase |
275 | Provides the (old) passphrase. | 361 | Provides the (old) passphrase. |
276 | .It Fl p | 362 | .It Fl p |
@@ -300,6 +386,11 @@ Print the SSHFP fingerprint resource record named | |||
300 | for the specified public key file. | 386 | for the specified public key file. |
301 | .It Fl S Ar start | 387 | .It Fl S Ar start |
302 | Specify start point (in hex) when generating candidate moduli for DH-GEX. | 388 | Specify start point (in hex) when generating candidate moduli for DH-GEX. |
389 | .It Fl s Ar ca_key | ||
390 | Certify (sign) a public key using the specified CA key. | ||
391 | Please see the | ||
392 | .Sx CERTIFICATES | ||
393 | section for details. | ||
303 | .It Fl T Ar output_file | 394 | .It Fl T Ar output_file |
304 | Test DH group exchange candidate primes (generated using the | 395 | Test DH group exchange candidate primes (generated using the |
305 | .Fl G | 396 | .Fl G |
@@ -313,9 +404,29 @@ for protocol version 1 and | |||
313 | or | 404 | or |
314 | .Dq dsa | 405 | .Dq dsa |
315 | for protocol version 2. | 406 | for protocol version 2. |
316 | .It Fl U Ar reader | 407 | .It Fl V Ar validity_interval |
317 | Upload an existing RSA private key into the smartcard in | 408 | Specify a validity interval when signing a certificate. |
318 | .Ar reader . | 409 | A validity interval may consist of a single time, indicating that the |
410 | certificate is valid beginning now and expiring at that time, or may consist | ||
411 | of two times separated by a colon to indicate an explicit time interval. | ||
412 | The start time may be specified as a date in YYYYMMDD format, a time | ||
413 | in YYYYMMDDHHMMSS format or a relative time (to the current time) consisting | ||
414 | of a minus sign followed by a relative time in the format described in the | ||
415 | .Sx TIME FORMATS | ||
416 | section of | ||
417 | .Xr ssh_config 5 . | ||
418 | The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMMSS time or | ||
419 | a relative time starting with a plus character. | ||
420 | .Pp | ||
421 | For example: | ||
422 | .Dq +52w1d | ||
423 | (valid from now to 52 weeks and one day from now), | ||
424 | .Dq -4w:+4w | ||
425 | (valid from four weeks ago to four weeks from now), | ||
426 | .Dq 20100101123000:20110101123000 | ||
427 | (valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011), | ||
428 | .Dq -1d:20110101 | ||
429 | (valid from yesterday to midnight, January 1st, 2011). | ||
319 | .It Fl v | 430 | .It Fl v |
320 | Verbose mode. | 431 | Verbose mode. |
321 | Causes | 432 | Causes |
@@ -386,6 +497,73 @@ Screened DH groups may be installed in | |||
386 | .Pa /etc/moduli . | 497 | .Pa /etc/moduli . |
387 | It is important that this file contains moduli of a range of bit lengths and | 498 | It is important that this file contains moduli of a range of bit lengths and |
388 | that both ends of a connection share common moduli. | 499 | that both ends of a connection share common moduli. |
500 | .Sh CERTIFICATES | ||
501 | .Nm | ||
502 | supports signing of keys to produce certificates that may be used for | ||
503 | user or host authentication. | ||
504 | Certificates consist of a public key, some identity information, zero or | ||
505 | more principal (user or host) names and an optional set of constraints that | ||
506 | are signed by a Certification Authority (CA) key. | ||
507 | Clients or servers may then trust only the CA key and verify its signature | ||
508 | on a certificate rather than trusting many user/host keys. | ||
509 | Note that OpenSSH certificates are a different, and much simpler, format to | ||
510 | the X.509 certificates used in | ||
511 | .Xr ssl 8 . | ||
512 | .Pp | ||
513 | .Nm | ||
514 | supports two types of certificates: user and host. | ||
515 | User certificates authenticate users to servers, whereas host certificates | ||
516 | authenticate server hosts to users. | ||
517 | To generate a user certificate: | ||
518 | .Pp | ||
519 | .Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub | ||
520 | .Pp | ||
521 | The resultant certificate will be placed in | ||
522 | .Pa /path/to/user_key_cert.pub . | ||
523 | A host certificate requires the | ||
524 | .Fl h | ||
525 | option: | ||
526 | .Pp | ||
527 | .Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub | ||
528 | .Pp | ||
529 | The host certificate will be output to | ||
530 | .Pa /path/to/host_key_cert.pub . | ||
531 | In both cases, | ||
532 | .Ar key_id | ||
533 | is a "key identifier" that is logged by the server when the certificate | ||
534 | is used for authentication. | ||
535 | .Pp | ||
536 | Certificates may be limited to be valid for a set of principal (user/host) | ||
537 | names. | ||
538 | By default, generated certificates are valid for all users or hosts. | ||
539 | To generate a certificate for a specified set of principals: | ||
540 | .Pp | ||
541 | .Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub | ||
542 | .Dl $ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub | ||
543 | .Pp | ||
544 | Additional limitations on the validity and use of user certificates may | ||
545 | be specified through certificate constraints. | ||
546 | A constrained certificate may disable features of the SSH session, may be | ||
547 | valid only when presented from particular source addresses or may | ||
548 | force the use of a specific command. | ||
549 | For a list of valid certificate constraints, see the documentation for the | ||
550 | .Fl O | ||
551 | option above. | ||
552 | .Pp | ||
553 | Finally, certificates may be defined with a validity lifetime. | ||
554 | The | ||
555 | .Fl V | ||
556 | option allows specification of certificate start and end times. | ||
557 | A certificate that is presented at a time outside this range will not be | ||
558 | considered valid. | ||
559 | By default, certificates have a maximum validity interval. | ||
560 | .Pp | ||
561 | For certificates to be used for user or host authentication, the CA | ||
562 | public key must be trusted by | ||
563 | .Xr sshd 8 | ||
564 | or | ||
565 | .Xr ssh 1 . | ||
566 | Please refer to those manual pages for details. | ||
389 | .Sh FILES | 567 | .Sh FILES |
390 | .Bl -tag -width Ds | 568 | .Bl -tag -width Ds |
391 | .It Pa ~/.ssh/identity | 569 | .It Pa ~/.ssh/identity |
@@ -393,7 +571,7 @@ Contains the protocol version 1 RSA authentication identity of the user. | |||
393 | This file should not be readable by anyone but the user. | 571 | This file should not be readable by anyone but the user. |
394 | It is possible to | 572 | It is possible to |
395 | specify a passphrase when generating the key; that passphrase will be | 573 | specify a passphrase when generating the key; that passphrase will be |
396 | used to encrypt the private part of this file using 3DES. | 574 | used to encrypt the private part of this file using 128-bit AES. |
397 | This file is not automatically accessed by | 575 | This file is not automatically accessed by |
398 | .Nm | 576 | .Nm |
399 | but it is offered as the default file for the private key. | 577 | but it is offered as the default file for the private key. |
@@ -411,7 +589,7 @@ Contains the protocol version 2 DSA authentication identity of the user. | |||
411 | This file should not be readable by anyone but the user. | 589 | This file should not be readable by anyone but the user. |
412 | It is possible to | 590 | It is possible to |
413 | specify a passphrase when generating the key; that passphrase will be | 591 | specify a passphrase when generating the key; that passphrase will be |
414 | used to encrypt the private part of this file using 3DES. | 592 | used to encrypt the private part of this file using 128-bit AES. |
415 | This file is not automatically accessed by | 593 | This file is not automatically accessed by |
416 | .Nm | 594 | .Nm |
417 | but it is offered as the default file for the private key. | 595 | but it is offered as the default file for the private key. |
@@ -429,7 +607,7 @@ Contains the protocol version 2 RSA authentication identity of the user. | |||
429 | This file should not be readable by anyone but the user. | 607 | This file should not be readable by anyone but the user. |
430 | It is possible to | 608 | It is possible to |
431 | specify a passphrase when generating the key; that passphrase will be | 609 | specify a passphrase when generating the key; that passphrase will be |
432 | used to encrypt the private part of this file using 3DES. | 610 | used to encrypt the private part of this file using 128-bit AES. |
433 | This file is not automatically accessed by | 611 | This file is not automatically accessed by |
434 | .Nm | 612 | .Nm |
435 | but it is offered as the default file for the private key. | 613 | but it is offered as the default file for the private key. |