- djm@cvs.openbsd.org 2013/01/17 23:00:01

     [auth.c key.c key.h ssh-keygen.1 ssh-keygen.c sshd_config.5]
     [krl.c krl.h PROTOCOL.krl]
     add support for Key Revocation Lists (KRLs). These are a compact way to
     represent lists of revoked keys and certificates, taking as little as
     a single bit of incremental cost to revoke a certificate by serial number.
     KRLs are loaded via the existing RevokedKeys sshd_config option.
     feedback and ok markus@

1 files changed, 116 insertions, 2 deletions

diff --git a/ssh-keygen.1 b/ssh-keygen.1
index 1d556464..52f4b6ea 100644
--- a/ssh-keygen.1
+++ b/ssh-keygen.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ssh-keygen.1,v 1.110 2012/08/15 18:25:50 jmc Exp $
+.\"	$OpenBSD: ssh-keygen.1,v 1.111 2013/01/17 23:00:01 djm 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: August 15 2012 $
+.Dd $Mdocdate: January 17 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 ca_public
+.Op Fl z version_number
+.Ar
+.Nm ssh-keygen
+.Fl Q
+.Fl f Ar krl_file
+.Ar
 .Ek
 .Sh DESCRIPTION
 .Nm
@@ -144,6 +155,13 @@ 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
@@ -321,6 +339,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
@@ -448,6 +477,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 certificated 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
@@ -485,6 +522,12 @@ For example:
 (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).
+.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
 Verbose mode.
 Causes
@@ -504,6 +547,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
@@ -638,6 +685,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 Op -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.
+In 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