- 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@
diff --git a/ssh-keygen.1 b/ssh-keygen.1
index 1d55646..52f4b6e 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 @@
.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 @@
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 @@
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 @@
(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 @@
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 @@
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