diff options
Diffstat (limited to 'ssh-keygen.1')
-rw-r--r-- | ssh-keygen.1 | 178 |
1 files changed, 176 insertions, 2 deletions
diff --git a/ssh-keygen.1 b/ssh-keygen.1 index f09e1a100..772caf7ad 100644 --- a/ssh-keygen.1 +++ b/ssh-keygen.1 | |||
@@ -1,4 +1,4 @@ | |||
1 | .\" $OpenBSD: ssh-keygen.1,v 1.83 2010/02/10 23:20:38 markus Exp $ | 1 | .\" $OpenBSD: ssh-keygen.1,v 1.84 2010/02/26 20:29:54 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: February 10 2010 $ | 40 | .Dd $Mdocdate: February 26 2010 $ |
41 | .Dt SSH-KEYGEN 1 | 41 | .Dt SSH-KEYGEN 1 |
42 | .Os | 42 | .Os |
43 | .Sh NAME | 43 | .Sh NAME |
@@ -106,6 +106,14 @@ | |||
106 | .Op Fl v | 106 | .Op Fl v |
107 | .Op Fl a Ar num_trials | 107 | .Op Fl a Ar num_trials |
108 | .Op Fl W Ar generator | 108 | .Op Fl W Ar generator |
109 | .Nm ssh-keygen | ||
110 | .Fl s Ar ca_key | ||
111 | .Fl I Ar certificate_identity | ||
112 | .Op Fl h | ||
113 | .Op Fl n Ar principals | ||
114 | .Op Fl O Ar constraint | ||
115 | .Op Fl V Ar validity_interval | ||
116 | .Ar | ||
109 | .Sh DESCRIPTION | 117 | .Sh DESCRIPTION |
110 | .Nm | 118 | .Nm |
111 | generates, manages and converts authentication keys for | 119 | generates, manages and converts authentication keys for |
@@ -245,6 +253,17 @@ but they do not reveal identifying information should the file's contents | |||
245 | be disclosed. | 253 | be disclosed. |
246 | This option will not modify existing hashed hostnames and is therefore safe | 254 | This option will not modify existing hashed hostnames and is therefore safe |
247 | to use on files that mix hashed and non-hashed names. | 255 | to use on files that mix hashed and non-hashed names. |
256 | .It Fl h | ||
257 | When signing a key, create a host certificate instead of a user | ||
258 | certificate. | ||
259 | Please see the | ||
260 | .Sx CERTIFICATES | ||
261 | section for details. | ||
262 | .It Fl I | ||
263 | Specify the key identity when signing a public key. | ||
264 | Please see the | ||
265 | .Sx CERTIFICATES | ||
266 | section for details. | ||
248 | .It Fl i | 267 | .It Fl i |
249 | This option will read an unencrypted private (or public) key file | 268 | This option will read an unencrypted private (or public) key file |
250 | in SSH2-compatible format and print an OpenSSH compatible private | 269 | in SSH2-compatible format and print an OpenSSH compatible private |
@@ -268,6 +287,67 @@ Specify the amount of memory to use (in megabytes) when generating | |||
268 | candidate moduli for DH-GEX. | 287 | candidate moduli for DH-GEX. |
269 | .It Fl N Ar new_passphrase | 288 | .It Fl N Ar new_passphrase |
270 | Provides the new passphrase. | 289 | Provides the new passphrase. |
290 | .It Fl n Ar principals | ||
291 | Specify one or more principals (user or host names) to be included in | ||
292 | a certificate when signing a key. | ||
293 | Multiple principals may be specified, separated by commas. | ||
294 | Please see the | ||
295 | .Sx CERTIFICATES | ||
296 | section for details. | ||
297 | .It Fl O Ar constraint | ||
298 | Specify a certificate constraint when signing a key. | ||
299 | This option may be specified multiple times. | ||
300 | Please see the | ||
301 | .Sx CERTIFICATES | ||
302 | section for details. | ||
303 | The constraints that are valid for user certificates are: | ||
304 | .Bl -tag -width Ds | ||
305 | .It Ic no-x11-forwarding | ||
306 | Disable X11 forwarding. (permitted by default) | ||
307 | .It Ic no-agent-forwarding | ||
308 | Disable | ||
309 | .Xr ssh-agent 1 | ||
310 | forwarding. (permitted by default) | ||
311 | .It Ic no-port-forwarding | ||
312 | Disable port forwarding. (permitted by default) | ||
313 | .It Ic no-pty | ||
314 | Disable PTY allocation. (permitted by default) | ||
315 | .It Ic no-user-rc | ||
316 | Disable execution of | ||
317 | .Pa ~/.ssh/rc | ||
318 | by | ||
319 | .Xr sshd 8 . | ||
320 | (permitted by default) | ||
321 | .It Ic clear | ||
322 | Clear all enabled permissions. | ||
323 | This is useful for clearing the default set of permissions so permissions may | ||
324 | be added individually. | ||
325 | .It Ic permit-x11-forwarding | ||
326 | Allows X11 forwarding. | ||
327 | .It Ic permit-port-forwarding | ||
328 | Allows port forwarding. | ||
329 | .It Ic permit-pty | ||
330 | Allows PTY allocation. | ||
331 | .It Ic permit-user-rc | ||
332 | Allows execution of | ||
333 | .Pa ~/.ssh/rc | ||
334 | by | ||
335 | .Xr sshd 8 . | ||
336 | .It Ic force-command=command | ||
337 | Forces the execution of | ||
338 | .Ar command | ||
339 | instead of any shell or command specified by the user when | ||
340 | the certificate is used for authentication. | ||
341 | .It Ic source-address=address_list | ||
342 | Restrict the source addresses from which the certificate is considered valid | ||
343 | from. | ||
344 | The | ||
345 | .Ar address_list | ||
346 | is a comma-separated list of one or more address/netmask pairs in CIDR | ||
347 | format. | ||
348 | .El | ||
349 | .Pp | ||
350 | At present, no constraints are valid for host keys. | ||
271 | .It Fl P Ar passphrase | 351 | .It Fl P Ar passphrase |
272 | Provides the (old) passphrase. | 352 | Provides the (old) passphrase. |
273 | .It Fl p | 353 | .It Fl p |
@@ -297,6 +377,11 @@ Print the SSHFP fingerprint resource record named | |||
297 | for the specified public key file. | 377 | for the specified public key file. |
298 | .It Fl S Ar start | 378 | .It Fl S Ar start |
299 | Specify start point (in hex) when generating candidate moduli for DH-GEX. | 379 | Specify start point (in hex) when generating candidate moduli for DH-GEX. |
380 | .It Fl s Ar ca_key | ||
381 | Certify (sign) a public key using the specified CA key. | ||
382 | Please see the | ||
383 | .Sx CERTIFICATES | ||
384 | section for details. | ||
300 | .It Fl T Ar output_file | 385 | .It Fl T Ar output_file |
301 | Test DH group exchange candidate primes (generated using the | 386 | Test DH group exchange candidate primes (generated using the |
302 | .Fl G | 387 | .Fl G |
@@ -310,6 +395,29 @@ for protocol version 1 and | |||
310 | or | 395 | or |
311 | .Dq dsa | 396 | .Dq dsa |
312 | for protocol version 2. | 397 | for protocol version 2. |
398 | .It Fl V Ar validity_interval | ||
399 | Specify a validity interval when signing a certificate. | ||
400 | A validity interval may consist of a single time, indicating that the | ||
401 | certificate is valid beginning now and expiring at that time, or may consist | ||
402 | of two times separated by a colon to indicate an explicit time interval. | ||
403 | The start time may be specified as a date in YYYYMMDD format, a time | ||
404 | in YYYYMMDDHHMMSS format or a relative time (to the current time) consisting | ||
405 | of a minus sign followed by a relative time in the format described in the | ||
406 | .Sx TIME FORMATS | ||
407 | section of | ||
408 | .Xr ssh_config 5 . | ||
409 | The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMMSS time or | ||
410 | a relative time starting with a plus character. | ||
411 | .Pp | ||
412 | For example: | ||
413 | .Dq +52w1d | ||
414 | (valid from now to 52 weeks and one day from now), | ||
415 | .Dq -4w:+4w | ||
416 | (valid from four weeks ago to four weeks from now), | ||
417 | .Dq 20100101123000:20110101123000 | ||
418 | (valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011), | ||
419 | .Dq -1d:20110101 | ||
420 | (valid from yesterday to midnight, January 1st, 2011). | ||
313 | .It Fl v | 421 | .It Fl v |
314 | Verbose mode. | 422 | Verbose mode. |
315 | Causes | 423 | Causes |
@@ -380,6 +488,72 @@ Screened DH groups may be installed in | |||
380 | .Pa /etc/moduli . | 488 | .Pa /etc/moduli . |
381 | It is important that this file contains moduli of a range of bit lengths and | 489 | It is important that this file contains moduli of a range of bit lengths and |
382 | that both ends of a connection share common moduli. | 490 | that both ends of a connection share common moduli. |
491 | .Sh CERTIFICATES | ||
492 | .Nm | ||
493 | supports signing of keys to produce certificates that may be used for | ||
494 | user or host authentication. | ||
495 | Certificates consist of a public key, some identity information, zero or | ||
496 | more principal (user or host) names and an optional set of constraints that | ||
497 | are signed by a Certification Authority (CA) key. | ||
498 | Clients or servers may then trust only the CA key and verify its signature | ||
499 | on a certificate rather than trusting many user/host keys. | ||
500 | Note that OpenSSH certificates are a different, and much simpler, format to | ||
501 | the X.509 certificates used in | ||
502 | .Xr ssl 8 . | ||
503 | .Pp | ||
504 | .Nm | ||
505 | supports two types of certificates: user and host. | ||
506 | User certificates authenticate users to servers, whereas host certificates | ||
507 | authenticate server hosts to users. To generate a user certificate: | ||
508 | .Pp | ||
509 | .Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub | ||
510 | .Pp | ||
511 | The resultant certificate will be placed in | ||
512 | .Pa /path/to/user_key_cert.pub . | ||
513 | A host certificate requires the | ||
514 | .Fl h | ||
515 | option: | ||
516 | .Pp | ||
517 | .Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub | ||
518 | .Pp | ||
519 | The host certificate will be output to | ||
520 | .Pa /path/to/host_key_cert.pub . | ||
521 | In both cases, | ||
522 | .Ar key_id | ||
523 | is a "key identifier" that is logged by the server when the certificate | ||
524 | is used for authentication. | ||
525 | .Pp | ||
526 | Certificates may be limited to be valid for a set of principal (user/host) | ||
527 | names. | ||
528 | By default, generated certificates are valid for all users or hosts. | ||
529 | To generate a certificate for a specified set of principals: | ||
530 | .Pp | ||
531 | .Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub | ||
532 | .Dl $ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub | ||
533 | .Pp | ||
534 | Additional limitations on the validity and use of user certificates may | ||
535 | be specified through certificate constraints. | ||
536 | A constrained certificate may disable features of the SSH session, may be | ||
537 | valid only when presented from particular source addresses or may | ||
538 | force the use of a specific command. | ||
539 | For a list of valid certificate constraints, see the documentation for the | ||
540 | .Fl O | ||
541 | option above. | ||
542 | .Pp | ||
543 | Finally, certificates may be defined with a validity lifetime. | ||
544 | The | ||
545 | .Fl V | ||
546 | option allows specification of certificate start and end times. | ||
547 | A certificate that is presented at a time outside this range will not be | ||
548 | considered valid. | ||
549 | By default, certificates have a maximum validity interval. | ||
550 | .Pp | ||
551 | For certificates to be used for user or host authentication, the CA | ||
552 | public key must be trusted by | ||
553 | .Xr sshd 8 | ||
554 | or | ||
555 | .Xr ssh 1 . | ||
556 | Please refer to those manual pages for details. | ||
383 | .Sh FILES | 557 | .Sh FILES |
384 | .Bl -tag -width Ds | 558 | .Bl -tag -width Ds |
385 | .It Pa ~/.ssh/identity | 559 | .It Pa ~/.ssh/identity |