-.\" $OpenBSD: ssh-keygen.1,v 1.108 2011/10/16 11:02:46 dtucker Exp $
+.\" $OpenBSD: ssh-keygen.1,v 1.115 2013/01/19 07:13:25 jmc Exp $
.\"
.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd $Mdocdate: October 16 2011 $
+.Dd $Mdocdate: January 19 2013 $
.Dt SSH-KEYGEN 1
.Os
.Sh NAME
.Fl f Ar input_file
.Op Fl v
.Op Fl a Ar num_trials
+.Op Fl J Ar num_lines
+.Op Fl j Ar start_line
.Op Fl K Ar checkpt
.Op Fl W Ar generator
.Nm ssh-keygen
.Op Fl f Ar input_keyfile
.Nm ssh-keygen
.Fl A
+.Nm ssh-keygen
+.Fl k
+.Fl f Ar krl_file
+.Op Fl u
+.Op Fl s Ar ca_public
+.Op Fl z Ar version_number
+.Ar
+.Nm ssh-keygen
+.Fl Q
+.Fl f Ar krl_file
+.Ar
.Ek
.Sh DESCRIPTION
.Nm
.Sx MODULI GENERATION
section for details.
.Pp
+Finally,
+.Nm
+can be used to generate and update Key Revocation Lists, and to test whether
+given keys have been revoked by one.
+See the
+.Sx KEY REVOCATION LISTS
+section for details.
+.Pp
Normally each user wishing to use SSH
with public key authentication runs this once to create the authentication
key in
.Fl m
option and print an OpenSSH compatible private
(or public) key to stdout.
+.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.
.It Fl K Ar checkpt
Write the last line processed to the file
.Ar checkpt
commercial SSH implementations.
The default import format is
.Dq RFC4716 .
+.It Fl k
+Generate a KRL file.
+In this mode,
+.Nm
+will generate a KRL file at the location specified via the
+.Fl f
+flag that revokes every key or certificate presented on the command line.
+Keys/certificates to be revoked may be specified by public key file or
+using the format described in the
+.Sx KEY REVOCATION LISTS
+section.
.It Fl L
Prints the contents of a certificate.
.It Fl l
The program will prompt for the file
containing the private key, for the old passphrase, and twice for the
new passphrase.
+.It Fl Q
+Test whether keys have been revoked in a KRL.
.It Fl q
Silence
.Nm ssh-keygen .
Please see the
.Sx CERTIFICATES
section for details.
+.Pp
+When generating a KRL,
+.Fl s
+specifies a path to a CA public key file used to revoke certificates directly
+by key ID or serial number.
+See the
+.Sx KEY REVOCATION LISTS
+section for details.
.It Fl T Ar output_file
Test DH group exchange candidate primes (generated using the
.Fl G
or
.Dq rsa
for protocol version 2.
+.It Fl u
+Update a KRL.
+When specified with
+.Fl k ,
+keys listed via the command line are added to the existing KRL rather than
+a new KRL being created.
.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
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.
+.Pp
+When generating a KRL, the
+.Fl z
+flag is used to specify a KRL version number.
.El
.Sh MODULI GENERATION
.Nm
.Fl S
option, which specifies a different start point (in hex).
.Pp
-Once a set of candidates have been generated, they must be tested for
+Once a set of candidates have been generated, they must be screened for
suitability.
This may be performed using the
.Fl T
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.
-By default, certificates have a maximum validity interval.
+By default, certificates are valid from
+.Ux
+Epoch to the distant future.
.Pp
For certificates to be used for user or host authentication, the CA
public key must be trusted by
or
.Xr ssh 1 .
Please refer to those manual pages for details.
+.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
+compact format, taking as little a one bit per certificate if they are being
+revoked by serial number.
+.Pp
+KRLs may be generated using the
+.Fl k
+flag.
+This option reads one or more files from the command line and generates a new
+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
+.It Cm serial : Ar serial_number Ns Op - Ns Ar serial_number
+Revokes a certificate with the specified serial number.
+Serial numbers are 64-bit values, not including zero and may be expressed
+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
+command line using the
+.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
+command line using the
+.Fl s
+option.
+.It Cm key : Ar public_key
+Revokes the specified key.
+If a certificate is listed, then it is revoked as a plain public key.
+.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 .
+When this option is specified, keys listed via the command line are merged into
+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.
+If any key listed on the command line has been revoked (or an error encountered)
+then
+.Nm
+will exit with a non-zero exit status.
+A zero exit status will only be returned if no key was revoked.
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa ~/.ssh/identity
projects / platform / upstream / openssh.git / blobdiff