ssh-keygen.1 25.6 KB
Newer Older
1
.\"	$OpenBSD: ssh-keygen.1,v 1.119 2013/12/21 07:10:47 tedu Exp $
2 3 4 5 6
.\"
.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
.\"                    All rights reserved
.\"
7 8 9 10 11 12 13
.\" As far as I am concerned, the code I have written for this software
.\" can be used freely for any purpose.  Any derived versions of this
.\" software must be clearly marked as such, and if the derived work is
.\" incompatible with the protocol description in the RFC file, it must be
.\" called by a name other than "ssh" or "Secure Shell".
.\"
.\"
14 15 16
.\" Copyright (c) 1999,2000 Markus Friedl.  All rights reserved.
.\" Copyright (c) 1999 Aaron Campbell.  All rights reserved.
.\" Copyright (c) 1999 Theo de Raadt.  All rights reserved.
17 18 19 20 21 22 23 24 25
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
26
.\"
27 28 29 30 31 32 33 34 35 36
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37
.\"
38
.Dd $Mdocdate: December 21 2013 $
39 40 41 42
.Dt SSH-KEYGEN 1
.Os
.Sh NAME
.Nm ssh-keygen
43
.Nd authentication key generation, management and conversion
44
.Sh SYNOPSIS
45
.Bk -words
46
.Nm ssh-keygen
47
.Op Fl q
48
.Op Fl b Ar bits
49
.Fl t Ar type
50 51
.Op Fl N Ar new_passphrase
.Op Fl C Ar comment
52
.Op Fl f Ar output_keyfile
53 54 55 56
.Nm ssh-keygen
.Fl p
.Op Fl P Ar old_passphrase
.Op Fl N Ar new_passphrase
57
.Op Fl f Ar keyfile
58
.Nm ssh-keygen
59
.Fl i
60
.Op Fl m Ar key_format
61
.Op Fl f Ar input_keyfile
62
.Nm ssh-keygen
63
.Fl e
64
.Op Fl m Ar key_format
65
.Op Fl f Ar input_keyfile
66 67
.Nm ssh-keygen
.Fl y
68
.Op Fl f Ar input_keyfile
69
.Nm ssh-keygen
70 71 72
.Fl c
.Op Fl P Ar passphrase
.Op Fl C Ar comment
73 74 75
.Op Fl f Ar keyfile
.Nm ssh-keygen
.Fl l
76 77 78
.Op Fl f Ar input_keyfile
.Nm ssh-keygen
.Fl B
79
.Op Fl f Ar input_keyfile
80
.Nm ssh-keygen
81
.Fl D Ar pkcs11
82
.Nm ssh-keygen
83 84
.Fl F Ar hostname
.Op Fl f Ar known_hosts_file
85
.Op Fl l
86 87 88 89 90 91 92
.Nm ssh-keygen
.Fl H
.Op Fl f Ar known_hosts_file
.Nm ssh-keygen
.Fl R Ar hostname
.Op Fl f Ar known_hosts_file
.Nm ssh-keygen
93 94 95
.Fl r Ar hostname
.Op Fl f Ar input_keyfile
.Op Fl g
96 97
.Nm ssh-keygen
.Fl G Ar output_file
98
.Op Fl v
99 100 101 102 103 104
.Op Fl b Ar bits
.Op Fl M Ar memory
.Op Fl S Ar start_point
.Nm ssh-keygen
.Fl T Ar output_file
.Fl f Ar input_file
105
.Op Fl v
106
.Op Fl a Ar rounds
107 108
.Op Fl J Ar num_lines
.Op Fl j Ar start_line
109
.Op Fl K Ar checkpt
110
.Op Fl W Ar generator
Damien Miller's avatar
Damien Miller committed
111 112 113 114 115
.Nm ssh-keygen
.Fl s Ar ca_key
.Fl I Ar certificate_identity
.Op Fl h
.Op Fl n Ar principals
116
.Op Fl O Ar option
Damien Miller's avatar
Damien Miller committed
117
.Op Fl V Ar validity_interval
118
.Op Fl z Ar serial_number
Damien Miller's avatar
Damien Miller committed
119
.Ar
120 121 122
.Nm ssh-keygen
.Fl L
.Op Fl f Ar input_keyfile
123 124
.Nm ssh-keygen
.Fl A
125 126 127 128
.Nm ssh-keygen
.Fl k
.Fl f Ar krl_file
.Op Fl u
129 130
.Op Fl s Ar ca_public
.Op Fl z Ar version_number
131 132 133 134 135
.Ar
.Nm ssh-keygen
.Fl Q
.Fl f Ar krl_file
.Ar
136
.Ek
137
.Sh DESCRIPTION
138
.Nm
139
generates, manages and converts authentication keys for
140
.Xr ssh 1 .
141
.Nm
142 143
can create RSA keys for use by SSH protocol version 1 and
DSA, ECDSA, ED25519 or RSA keys for use by SSH protocol version 2.
144
The type of key to be generated is specified with the
145
.Fl t
146
option.
147 148
If invoked without any arguments,
.Nm
149
will generate an RSA key for use in SSH protocol 2 connections.
150
.Pp
151 152 153 154 155 156 157
.Nm
is also used to generate groups for use in Diffie-Hellman group
exchange (DH-GEX).
See the
.Sx MODULI GENERATION
section for details.
.Pp
158 159 160
Finally,
.Nm
can be used to generate and update Key Revocation Lists, and to test whether
161 162
given keys have been revoked by one.
See the
163 164 165
.Sx KEY REVOCATION LISTS
section for details.
.Pp
166
Normally each user wishing to use SSH
167
with public key authentication runs this once to create the authentication
168
key in
169
.Pa ~/.ssh/identity ,
170
.Pa ~/.ssh/id_dsa ,
171
.Pa ~/.ssh/id_ecdsa ,
172
.Pa ~/.ssh/id_ed25519
173
or
174
.Pa ~/.ssh/id_rsa .
175 176 177
Additionally, the system administrator may use this to generate host keys,
as seen in
.Pa /etc/rc .
178 179
.Pp
Normally this program generates the key and asks for a file in which
Damien Miller's avatar
Damien Miller committed
180 181
to store the private key.
The public key is stored in a file with the same name but
182
.Dq .pub
Damien Miller's avatar
Damien Miller committed
183 184 185
appended.
The program also asks for a passphrase.
The passphrase may be empty to indicate no passphrase
186
(host keys must have an empty passphrase), or it may be a string of
Damien Miller's avatar
Damien Miller committed
187
arbitrary length.
188 189 190 191
A passphrase is similar to a password, except it can be a phrase with a
series of words, punctuation, numbers, whitespace, or any string of
characters you want.
Good passphrases are 10-30 characters long, are
192
not simple sentences or otherwise easily guessable (English
193
prose has only 1-2 bits of entropy per character, and provides very bad
194 195
passphrases), and contain a mix of upper and lowercase letters,
numbers, and non-alphanumeric characters.
Damien Miller's avatar
Damien Miller committed
196
The passphrase can be changed later by using the
197 198 199
.Fl p
option.
.Pp
Damien Miller's avatar
Damien Miller committed
200
There is no way to recover a lost passphrase.
201 202
If the passphrase is lost or forgotten, a new key must be generated
and the corresponding public key copied to other machines.
203
.Pp
204 205
For RSA1 keys,
there is also a comment field in the key file that is only for
Damien Miller's avatar
Damien Miller committed
206 207 208
convenience to the user to help identify the key.
The comment can tell what the key is for, or whatever is useful.
The comment is initialized to
209 210 211 212 213
.Dq user@host
when the key is created, but can be changed using the
.Fl c
option.
.Pp
214 215 216
After a key is generated, instructions below detail where the keys
should be placed to be activated.
.Pp
217 218
The options are as follows:
.Bl -tag -width Ds
219
.It Fl A
220 221
For each of the key types (rsa1, rsa, dsa, ecdsa and ed25519)
for which host keys
222 223
do not exist, generate the host keys with the default key file path,
an empty passphrase, default bits for the key type, and default comment.
224
This is used by
225 226
.Pa /etc/rc
to generate new host keys.
227 228 229 230 231 232 233 234 235 236 237
.It Fl a Ar rounds
When saving a new-format private key (i.e. an ed25519 key or any SSH protocol
2 key when the
.Fl o
flag is set), this option specifies the number of KDF (key derivation function)
rounds used.
Higher numbers result in slower passphrase verification and increased
resistance to brute-force password cracking (should the keys be stolen).
.Pp
When screening DH-GEX candidates (
using the
238
.Fl T
239 240
command).
This option specifies the number of primality tests to perform.
241 242
.It Fl B
Show the bubblebabble digest of specified private or public key file.
243
.It Fl b Ar bits
Damien Miller's avatar
Damien Miller committed
244
Specifies the number of bits in the key to create.
245
For RSA keys, the minimum size is 768 bits and the default is 2048 bits.
246
Generally, 2048 bits is considered sufficient.
247
DSA keys must be exactly 1024 bits as specified by FIPS 186-2.
248 249
For ECDSA keys, the
.Fl b
250
flag determines the key length by selecting from one of three elliptic
251 252 253
curve sizes: 256, 384 or 521 bits.
Attempting to use bit lengths other than these three values for ECDSA keys
will fail.
254 255 256
ED25519 keys have a fixed length and the
.Fl b
flag will be ignored.
257 258
.It Fl C Ar comment
Provides a new comment.
259 260
.It Fl c
Requests changing the comment in the private and public key files.
261
This operation is only supported for RSA1 keys.
262
The program will prompt for the file containing the private keys, for
263
the passphrase if the key has one, and for the new comment.
264
.It Fl D Ar pkcs11
265 266
Download the RSA public keys provided by the PKCS#11 shared library
.Ar pkcs11 .
267 268 269 270 271
When used in combination with
.Fl s ,
this option indicates that a CA key resides in a PKCS#11 token (see the
.Sx CERTIFICATES
section for details).
272
.It Fl e
273
This option will read a private or public OpenSSH key file and
274 275 276 277 278
print to stdout the key in one of the formats specified by the
.Fl m
option.
The default export format is
.Dq RFC4716 .
279
This option allows exporting OpenSSH keys for use by other programs, including
280
several commercial SSH implementations.
281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298
.It Fl F Ar hostname
Search for the specified
.Ar hostname
in a
.Pa known_hosts
file, listing any occurrences found.
This option is useful to find hashed host names or addresses and may also be
used in conjunction with the
.Fl H
option to print found keys in a hashed format.
.It Fl f Ar filename
Specifies the filename of the key file.
.It Fl G Ar output_file
Generate candidate primes for DH-GEX.
These primes must be screened for
safety (using the
.Fl T
option) before use.
299
.It Fl g
300
Use generic DNS format when printing fingerprint resource records using the
301
.Fl r
302
command.
303 304 305
.It Fl H
Hash a
.Pa known_hosts
306 307 308 309
file.
This replaces all hostnames and addresses with hashed representations
within the specified file; the original content is moved to a file with
a .old suffix.
310 311 312 313 314 315 316 317
These hashes may be used normally by
.Nm ssh
and
.Nm sshd ,
but they do not reveal identifying information should the file's contents
be disclosed.
This option will not modify existing hashed hostnames and is therefore safe
to use on files that mix hashed and non-hashed names.
Damien Miller's avatar
Damien Miller committed
318 319 320 321 322 323
.It Fl h
When signing a key, create a host certificate instead of a user
certificate.
Please see the
.Sx CERTIFICATES
section for details.
324
.It Fl I Ar certificate_identity
Damien Miller's avatar
Damien Miller committed
325 326 327 328
Specify the key identity when signing a public key.
Please see the
.Sx CERTIFICATES
section for details.
329 330
.It Fl i
This option will read an unencrypted private (or public) key file
331 332 333
in the format specified by the
.Fl m
option and print an OpenSSH compatible private
334
(or public) key to stdout.
335 336 337 338 339 340 341 342 343 344
.It Fl J Ar num_lines
Exit after screening the specified number of lines
while performing DH candidate screening using the
.Fl T
option.
.It Fl j Ar start_line
Start screening at the specified line number
while performing DH candidate screening using the
.Fl T
option.
345 346 347 348 349 350 351 352
.It Fl K Ar checkpt
Write the last line processed to the file
.Ar checkpt
while performing DH candidate screening using the
.Fl T
option.
This will be used to skip lines in the input file that have already been
processed if the job is restarted.
353 354 355 356
This option allows importing keys from other software, including several
commercial SSH implementations.
The default import format is
.Dq RFC4716 .
357 358 359 360 361 362
.It Fl k
Generate a KRL file.
In this mode,
.Nm
will generate a KRL file at the location specified via the
.Fl f
363
flag that revokes every key or certificate presented on the command line.
364 365 366 367
Keys/certificates to be revoked may be specified by public key file or
using the format described in the
.Sx KEY REVOCATION LISTS
section.
368 369
.It Fl L
Prints the contents of a certificate.
370
.It Fl l
371
Show fingerprint of specified public key file.
372 373 374
Private RSA1 keys are also supported.
For RSA and DSA keys
.Nm
375 376 377 378
tries to find the matching public key file and prints its fingerprint.
If combined with
.Fl v ,
an ASCII art representation of the key is supplied with the fingerprint.
379 380 381
.It Fl M Ar memory
Specify the amount of memory to use (in megabytes) when generating
candidate moduli for DH-GEX.
382 383 384 385 386
.It Fl m Ar key_format
Specify a key format for the
.Fl i
(import) or
.Fl e
387
(export) conversion options.
388 389
The supported key formats are:
.Dq RFC4716
390
(RFC 4716/SSH2 public or private key),
391 392 393 394 395 396 397
.Dq PKCS8
(PEM PKCS8 public key)
or
.Dq PEM
(PEM public key).
The default conversion format is
.Dq RFC4716 .
398 399
.It Fl N Ar new_passphrase
Provides the new passphrase.
Damien Miller's avatar
Damien Miller committed
400 401 402 403 404 405 406
.It Fl n Ar principals
Specify one or more principals (user or host names) to be included in
a certificate when signing a key.
Multiple principals may be specified, separated by commas.
Please see the
.Sx CERTIFICATES
section for details.
407 408
.It Fl O Ar option
Specify a certificate option when signing a key.
Damien Miller's avatar
Damien Miller committed
409 410 411 412
This option may be specified multiple times.
Please see the
.Sx CERTIFICATES
section for details.
413
The options that are valid for user certificates are:
Damien Miller's avatar
Damien Miller committed
414
.Bl -tag -width Ds
415 416 417 418 419 420 421 422 423
.It Ic clear
Clear all enabled permissions.
This is useful for clearing the default set of permissions so permissions may
be added individually.
.It Ic force-command Ns = Ns Ar command
Forces the execution of
.Ar command
instead of any shell or command specified by the user when
the certificate is used for authentication.
Damien Miller's avatar
Damien Miller committed
424 425 426
.It Ic no-agent-forwarding
Disable
.Xr ssh-agent 1
427
forwarding (permitted by default).
Damien Miller's avatar
Damien Miller committed
428
.It Ic no-port-forwarding
429
Disable port forwarding (permitted by default).
Damien Miller's avatar
Damien Miller committed
430
.It Ic no-pty
431
Disable PTY allocation (permitted by default).
Damien Miller's avatar
Damien Miller committed
432 433 434 435
.It Ic no-user-rc
Disable execution of
.Pa ~/.ssh/rc
by
436 437
.Xr sshd 8
(permitted by default).
438 439
.It Ic no-x11-forwarding
Disable X11 forwarding (permitted by default).
440 441 442 443
.It Ic permit-agent-forwarding
Allows
.Xr ssh-agent 1
forwarding.
Damien Miller's avatar
Damien Miller committed
444 445 446 447 448 449 450 451 452
.It Ic permit-port-forwarding
Allows port forwarding.
.It Ic permit-pty
Allows PTY allocation.
.It Ic permit-user-rc
Allows execution of
.Pa ~/.ssh/rc
by
.Xr sshd 8 .
453 454 455
.It Ic permit-x11-forwarding
Allows X11 forwarding.
.It Ic source-address Ns = Ns Ar address_list
456
Restrict the source addresses from which the certificate is considered valid.
Damien Miller's avatar
Damien Miller committed
457 458 459 460 461 462
The
.Ar address_list
is a comma-separated list of one or more address/netmask pairs in CIDR
format.
.El
.Pp
463
At present, no options are valid for host keys.
464 465 466 467 468 469 470 471
.It Fl o
Causes
.Nm
to save SSH protocol 2 private keys using the new OpenSSH format rather than
the more compatible PEM format.
The new format has increased resistance to brute-force password cracking
but is not supported by versions of OpenSSH prior to 6.5.
Ed25519 keys always use the new private key format.
472 473
.It Fl P Ar passphrase
Provides the (old) passphrase.
474 475
.It Fl p
Requests changing the passphrase of a private key file instead of
Damien Miller's avatar
Damien Miller committed
476 477
creating a new private key.
The program will prompt for the file
478 479
containing the private key, for the old passphrase, and twice for the
new passphrase.
480 481
.It Fl Q
Test whether keys have been revoked in a KRL.
482 483 484
.It Fl q
Silence
.Nm ssh-keygen .
485 486 487
.It Fl R Ar hostname
Removes all keys belonging to
.Ar hostname
488
from a
489 490
.Pa known_hosts
file.
491
This option is useful to delete hashed hosts (see the
492 493
.Fl H
option above).
494 495 496 497
.It Fl r Ar hostname
Print the SSHFP fingerprint resource record named
.Ar hostname
for the specified public key file.
498 499
.It Fl S Ar start
Specify start point (in hex) when generating candidate moduli for DH-GEX.
Damien Miller's avatar
Damien Miller committed
500 501 502 503 504
.It Fl s Ar ca_key
Certify (sign) a public key using the specified CA key.
Please see the
.Sx CERTIFICATES
section for details.
505 506 507
.Pp
When generating a KRL,
.Fl s
508
specifies a path to a CA public key file used to revoke certificates directly
509 510 511 512
by key ID or serial number.
See the
.Sx KEY REVOCATION LISTS
section for details.
513 514 515 516
.It Fl T Ar output_file
Test DH group exchange candidate primes (generated using the
.Fl G
option) for safety.
517 518 519 520 521
.It Fl t Ar type
Specifies the type of key to create.
The possible values are
.Dq rsa1
for protocol version 1 and
522
.Dq dsa ,
523 524
.Dq ecdsa ,
.Dq ed25519 ,
525
or
526
.Dq rsa
527
for protocol version 2.
528 529 530 531
.It Fl u
Update a KRL.
When specified with
.Fl k ,
532
keys listed via the command line are added to the existing KRL rather than
533
a new KRL being created.
Damien Miller's avatar
Damien Miller committed
534 535 536 537 538 539 540 541
.It Fl V Ar validity_interval
Specify a validity interval when signing a certificate.
A validity interval may consist of a single time, indicating that the
certificate is valid beginning now and expiring at that time, or may consist
of two times separated by a colon to indicate an explicit time interval.
The start time may be specified as a date in YYYYMMDD format, a time
in YYYYMMDDHHMMSS format or a relative time (to the current time) consisting
of a minus sign followed by a relative time in the format described in the
542
TIME FORMATS section of
543
.Xr sshd_config 5 .
Damien Miller's avatar
Damien Miller committed
544 545 546 547 548 549 550 551 552 553 554 555
The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMMSS time or
a relative time starting with a plus character.
.Pp
For example:
.Dq +52w1d
(valid from now to 52 weeks and one day from now),
.Dq -4w:+4w
(valid from four weeks ago to four weeks from now),
.Dq 20100101123000:20110101123000
(valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011),
.Dq -1d:20110101
(valid from yesterday to midnight, January 1st, 2011).
556 557 558 559 560 561 562 563 564 565
.It Fl v
Verbose mode.
Causes
.Nm
to print debugging messages about its progress.
This is helpful for debugging moduli generation.
Multiple
.Fl v
options increase the verbosity.
The maximum is 3.
566 567 568 569 570
.It Fl W Ar generator
Specify desired generator when testing candidate moduli for DH-GEX.
.It Fl y
This option will read a private
OpenSSH format file and print an OpenSSH public key to stdout.
571 572 573 574
.It Fl z Ar serial_number
Specifies a serial number to be embedded in the certificate to distinguish
this certificate from others from the same CA.
The default serial number is zero.
575 576 577 578
.Pp
When generating a KRL, the
.Fl z
flag is used to specify a KRL version number.
579
.El
580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596
.Sh MODULI GENERATION
.Nm
may be used to generate groups for the Diffie-Hellman Group Exchange
(DH-GEX) protocol.
Generating these groups is a two-step process: first, candidate
primes are generated using a fast, but memory intensive process.
These candidate primes are then tested for suitability (a CPU-intensive
process).
.Pp
Generation of primes is performed using the
.Fl G
option.
The desired length of the primes may be specified by the
.Fl b
option.
For example:
.Pp
597
.Dl # ssh-keygen -G moduli-2048.candidates -b 2048
598 599 600 601 602 603 604
.Pp
By default, the search for primes begins at a random point in the
desired length range.
This may be overridden using the
.Fl S
option, which specifies a different start point (in hex).
.Pp
605
Once a set of candidates have been generated, they must be screened for
606 607 608 609 610 611 612 613 614 615 616
suitability.
This may be performed using the
.Fl T
option.
In this mode
.Nm
will read candidates from standard input (or a file specified using the
.Fl f
option).
For example:
.Pp
617
.Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates
618 619 620 621 622 623 624 625 626 627
.Pp
By default, each candidate will be subjected to 100 primality tests.
This may be overridden using the
.Fl a
option.
The DH generator value will be chosen automatically for the
prime under consideration.
If a specific generator is desired, it may be requested using the
.Fl W
option.
628
Valid generator values are 2, 3, and 5.
629 630 631 632 633
.Pp
Screened DH groups may be installed in
.Pa /etc/moduli .
It is important that this file contains moduli of a range of bit lengths and
that both ends of a connection share common moduli.
Damien Miller's avatar
Damien Miller committed
634 635 636 637 638
.Sh CERTIFICATES
.Nm
supports signing of keys to produce certificates that may be used for
user or host authentication.
Certificates consist of a public key, some identity information, zero or
639
more principal (user or host) names and a set of options that
Damien Miller's avatar
Damien Miller committed
640 641 642 643 644 645 646 647 648 649
are signed by a Certification Authority (CA) key.
Clients or servers may then trust only the CA key and verify its signature
on a certificate rather than trusting many user/host keys.
Note that OpenSSH certificates are a different, and much simpler, format to
the X.509 certificates used in
.Xr ssl 8 .
.Pp
.Nm
supports two types of certificates: user and host.
User certificates authenticate users to servers, whereas host certificates
650 651
authenticate server hosts to users.
To generate a user certificate:
Damien Miller's avatar
Damien Miller committed
652 653 654 655
.Pp
.Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
.Pp
The resultant certificate will be placed in
656
.Pa /path/to/user_key-cert.pub .
Damien Miller's avatar
Damien Miller committed
657 658 659 660 661 662 663
A host certificate requires the
.Fl h
option:
.Pp
.Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
.Pp
The host certificate will be output to
664
.Pa /path/to/host_key-cert.pub .
665 666 667 668 669 670 671 672 673 674 675
.Pp
It is possible to sign using a CA key stored in a PKCS#11 token by
providing the token library using
.Fl D
and identifying the CA key by providing its public half as an argument
to
.Fl s :
.Pp
.Dl $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id host_key.pub
.Pp
In all cases,
Damien Miller's avatar
Damien Miller committed
676 677 678 679 680 681 682 683 684 685
.Ar key_id
is a "key identifier" that is logged by the server when the certificate
is used for authentication.
.Pp
Certificates may be limited to be valid for a set of principal (user/host)
names.
By default, generated certificates are valid for all users or hosts.
To generate a certificate for a specified set of principals:
.Pp
.Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
686
.Dl "$ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub"
Damien Miller's avatar
Damien Miller committed
687 688
.Pp
Additional limitations on the validity and use of user certificates may
689
be specified through certificate options.
690
A certificate option may disable features of the SSH session, may be
Damien Miller's avatar
Damien Miller committed
691 692
valid only when presented from particular source addresses or may
force the use of a specific command.
693
For a list of valid certificate options, see the documentation for the
Damien Miller's avatar
Damien Miller committed
694 695 696 697 698 699 700 701 702
.Fl O
option above.
.Pp
Finally, certificates may be defined with a validity lifetime.
The
.Fl V
option allows specification of certificate start and end times.
A certificate that is presented at a time outside this range will not be
considered valid.
703 704 705
By default, certificates are valid from
.Ux
Epoch to the distant future.
Damien Miller's avatar
Damien Miller committed
706 707 708 709 710 711 712
.Pp
For certificates to be used for user or host authentication, the CA
public key must be trusted by
.Xr sshd 8
or
.Xr ssh 1 .
Please refer to those manual pages for details.
713 714 715 716
.Sh KEY REVOCATION LISTS
.Nm
is able to manage OpenSSH format Key Revocation Lists (KRLs).
These binary files specify keys or certificates to be revoked using a
717
compact format, taking as little as one bit per certificate if they are being
718 719 720 721 722
revoked by serial number.
.Pp
KRLs may be generated using the
.Fl k
flag.
723
This option reads one or more files from the command line and generates a new
724 725 726 727 728 729 730 731 732 733 734 735 736 737
KRL.
The files may either contain a KRL specification (see below) or public keys,
listed one per line.
Plain public keys are revoked by listing their hash or contents in the KRL and
certificates revoked by serial number or key ID (if the serial is zero or
not available).
.Pp
Revoking keys using a KRL specification offers explicit control over the
types of record used to revoke keys and may be used to directly revoke
certificates by serial number or key ID without having the complete original
certificate on hand.
A KRL specification consists of lines containing one of the following directives
followed by a colon and some directive-specific information.
.Bl -tag -width Ds
738
.It Cm serial : Ar serial_number Ns Op - Ns Ar serial_number
739
Revokes a certificate with the specified serial number.
740
Serial numbers are 64-bit values, not including zero and may be expressed
741 742 743 744 745
in decimal, hex or octal.
If two serial numbers are specified separated by a hyphen, then the range
of serial numbers including and between each is revoked.
The CA key must have been specified on the
.Nm
746
command line using the
747 748 749 750 751 752
.Fl s
option.
.It Cm id : Ar key_id
Revokes a certificate with the specified key ID string.
The CA key must have been specified on the
.Nm
753
command line using the
754 755 756 757
.Fl s
option.
.It Cm key : Ar public_key
Revokes the specified key.
758
If a certificate is listed, then it is revoked as a plain public key.
759 760 761 762 763 764 765 766
.It Cm sha1 : Ar public_key
Revokes the specified key by its SHA1 hash.
.El
.Pp
KRLs may be updated using the
.Fl u
flag in addition to
.Fl k .
767
When this option is specified, keys listed via the command line are merged into
768 769 770 771 772 773 774
the KRL, adding to those already there.
.Pp
It is also possible, given a KRL, to test whether it revokes a particular key
(or keys).
The
.Fl Q
flag will query an existing KRL, testing each key specified on the commandline.
775
If any key listed on the command line has been revoked (or an error encountered)
776 777 778 779
then
.Nm
will exit with a non-zero exit status.
A zero exit status will only be returned if no key was revoked.
780
.Sh FILES
781
.Bl -tag -width Ds -compact
782
.It Pa ~/.ssh/identity
783
Contains the protocol version 1 RSA authentication identity of the user.
Damien Miller's avatar
Damien Miller committed
784 785
This file should not be readable by anyone but the user.
It is possible to
786
specify a passphrase when generating the key; that passphrase will be
787
used to encrypt the private part of this file using 3DES.
Damien Miller's avatar
Damien Miller committed
788
This file is not automatically accessed by
789 790
.Nm
but it is offered as the default file for the private key.
791
.Xr ssh 1
792
will read this file when a login attempt is made.
793
.Pp
794
.It Pa ~/.ssh/identity.pub
795
Contains the protocol version 1 RSA public key for authentication.
Damien Miller's avatar
Damien Miller committed
796
The contents of this file should be added to
797
.Pa ~/.ssh/authorized_keys
798
on all machines
799
where the user wishes to log in using RSA authentication.
Damien Miller's avatar
Damien Miller committed
800
There is no need to keep the contents of this file secret.
801
.Pp
802
.It Pa ~/.ssh/id_dsa
803
.It Pa ~/.ssh/id_ecdsa
804
.It Pa ~/.ssh/id_ed25519
805
.It Pa ~/.ssh/id_rsa
806 807
Contains the protocol version 2 DSA, ECDSA, ED25519 or RSA
authentication identity of the user.
808 809 810
This file should not be readable by anyone but the user.
It is possible to
specify a passphrase when generating the key; that passphrase will be
811
used to encrypt the private part of this file using 128-bit AES.
812 813 814
This file is not automatically accessed by
.Nm
but it is offered as the default file for the private key.
815
.Xr ssh 1
816
will read this file when a login attempt is made.
817 818 819
.Pp
.It Pa ~/.ssh/id_dsa.pub
.It Pa ~/.ssh/id_ecdsa.pub
820
.It Pa ~/.ssh/id_ed25519.pub
821
.It Pa ~/.ssh/id_rsa.pub
822 823
Contains the protocol version 2 DSA, ECDSA, ED25519 or RSA
public key for authentication.
824
The contents of this file should be added to
825
.Pa ~/.ssh/authorized_keys
826
on all machines
827
where the user wishes to log in using public key authentication.
828
There is no need to keep the contents of this file secret.
829
.Pp
830 831 832 833
.It Pa /etc/moduli
Contains Diffie-Hellman groups used for DH-GEX.
The file format is described in
.Xr moduli 5 .
834
.El
835 836 837
.Sh SEE ALSO
.Xr ssh 1 ,
.Xr ssh-add 1 ,
Damien Miller's avatar
Damien Miller committed
838
.Xr ssh-agent 1 ,
839
.Xr moduli 5 ,
Ben Lindstrom's avatar
Ben Lindstrom committed
840
.Xr sshd 8
841
.Rs
842 843 844
.%R RFC 4716
.%T "The Secure Shell (SSH) Public Key File Format"
.%D 2006
845
.Re
846 847 848 849 850 851 852 853 854
.Sh AUTHORS
OpenSSH is a derivative of the original and free
ssh 1.2.12 release by Tatu Ylonen.
Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
Theo de Raadt and Dug Song
removed many bugs, re-added newer features and
created OpenSSH.
Markus Friedl contributed the support for SSH
protocol versions 1.5 and 2.0.