1 files changed, 122 insertions, 3 deletions

diff --git a/ssh-keygen.1 b/ssh-keygen.1
index fe26750a4..0d84ebd1e 100644
--- a/ssh-keygen.1
+++ b/ssh-keygen.1
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ssh-keygen.1,v 1.109 2012/07/06 00:41:59 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
@@ -35,7 +35,7 @@
 .\" (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: July 6 2012 $
+.Dd $Mdocdate: January 19 2013 $
 .Dt SSH-KEYGEN 1
 .Os
 .Sh NAME
@@ -122,6 +122,17 @@
 .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
@@ -144,6 +155,14 @@ See the
 .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
@@ -317,6 +336,17 @@ This option allows importing keys from other software, including several
 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
@@ -421,6 +451,8 @@ creating a new private key.
 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 .
@@ -444,6 +476,14 @@ Certify (sign) a public key using the specified CA key.
 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
@@ -458,6 +498,12 @@ for protocol version 1 and
 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
@@ -500,6 +546,10 @@ OpenSSH format file and print an OpenSSH public key to stdout.
 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
@@ -624,7 +674,9 @@ The
 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
@@ -632,6 +684,73 @@ 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