From 2d51d1ef50b9f78937d15330566927f6e3d48025 Mon Sep 17 00:00:00 2001
From: Alex Bramley <a.bramley@gmail.com>
Date: Tue, 16 Feb 2010 06:35:57 +0000
Subject: [PATCH] Finish up script documentation.

---
 doc/ca-init.pod        |  6 ++-
 doc/ca-renew-cert.pod  |  0
 doc/ca-revoke-cert.pod | 92 ++++++++++++++++++++++++++++++++++++++++++
 doc/revoke-cert.txt    | 18 ---------
 4 files changed, 96 insertions(+), 20 deletions(-)
 mode change 100644 => 100755 doc/ca-renew-cert.pod
 create mode 100755 doc/ca-revoke-cert.pod
 delete mode 100644 doc/revoke-cert.txt

diff --git a/doc/ca-init.pod b/doc/ca-init.pod
index ba2a91d..5b475ec 100755
--- a/doc/ca-init.pod
+++ b/doc/ca-init.pod
@@ -27,8 +27,10 @@ B<ca-init> [B<-h>] | [B<--help>]
 
 B<ca-init> reads the ca-scripts configuration file and generates an openssl(1)
 configuration file and an X.509 certificate and key suitable for use as an
-x509(1) certificate authority. The format of the ca-scripts configuration file
-is documented in ca-scripts.conf(5).
+x509(1) certificate authority. It can also optionally generate an HTML file
+with MD5 and SHA1 fingerprints suitable for publishing the CA certificate and
+the CRL. The format of the ca-scripts configuration file is documented in
+ca-scripts.conf(5).
 
 =head1 OPTIONS
 
diff --git a/doc/ca-renew-cert.pod b/doc/ca-renew-cert.pod
old mode 100644
new mode 100755
diff --git a/doc/ca-revoke-cert.pod b/doc/ca-revoke-cert.pod
new file mode 100755
index 0000000..d1c9d96
--- /dev/null
+++ b/doc/ca-revoke-cert.pod
@@ -0,0 +1,92 @@
+#! /bin/sh
+
+if [ -z "$1" -o "$1" == "man" ]; then
+  exec /usr/bin/pod2man -n CA-REVOKE-CERT -s 1 -d "12 February 2010" \
+    -r "ca-scripts version 0.9" -c "SSL Certificate Authority utilities" $0
+elif [ "$1" == "html" ]; then
+  exec /usr/bin/pod2html --title "ca-revoke-cert(1)" < $0
+elif [ "$1" == "text" ]; then
+  exec /usr/bin/pod2text -o $0
+fi
+echo "Unrecognised output format '$1', try man, html, or text."
+exit 1
+
+=pod
+
+=head1 NAME
+
+ca-revoke-cert - revoke a certificate and re-generate CRL
+
+=head1 SYNOPSIS
+
+B<ca-revoke-cert> -t I<type> [B<-f> I<config>] [B<-i> I<template>]
+[B<-o> I<file>] I<hostname, username, or path to certificate>
+
+B<ca-revoke-cert> [B<-h>] | [B<--help>]
+
+=head1 DESCRIPTION
+
+B<ca-revoke-cert> revokes certificates generated with ca-create-cert(1) and
+updates the CA's certificate revocation lists in both PEM and DER-encoded
+formats. It can also optionally generate an HTML file with MD5 and SHA1
+fingerprints suitable for publishing the CA certificate and the CRL.
+
+=head1 OPTIONS
+
+B<ca-revoke-cert> can infer the correct cached configurations to use for
+certificate revocation from the hostname of a I<server> or I<client>, the
+username of a I<user>, or the path to a previously generated certificate of any
+type.
+
+=over
+
+=item B<-t> I<TYPE>, B<--type> I<TYPE>
+
+This argument is mandatory and tells B<ca-revoke-cert> what type of certificate
+it is revoking, either I<server>, I<client>, or I<user>.
+
+=item B<-f> I<FILE>, B<--config> I<FILE>
+
+Load the ca-scripts configuration from I<FILE> instead of
+I</etc/ca-scripts.conf>.
+
+=item B<-i> I<FILE>, B<--template> I<FILE>
+
+Use the index.html template in I<FILE> rather than the standard one provided
+with ca-scripts. See the B<TEMPLATING> section of ca-scripts.conf(5) for more
+details of the templating system. Hint: it's sed(1) based...
+
+=item B<-o> I<FILE>, B<--output> I<FILE>
+
+Generate a HTML page in I<FILE> suitable for serving your CA certificate and
+revocation lists via HTTP. The default template is basic but provides MD5 and
+SHA1 fingerprints of both files for verification purposes.
+
+=back
+
+=head1 BUGS
+
+Probably. At the moment the revocation reason is hardcoded to "superseded";
+this may change in future releases along with code to deal with key compromise.
+Additionally, the CRLv2 extension I<issuingDistributionPoint> is not yet set in
+generated CRLs due to requiring a very recent version of openssl(1).
+
+=head1 AVAILABILITY
+
+New releases of the ca-scripts utilities can be found at
+L<the developer's website|http://www.pl0rt.org/code/ca-scripts>.
+A L<git repository|git://git.pl0rt.org/alex/code/ca-scripts>
+for development versions also exists.
+
+=head1 AUTHORS
+
+Copyright 2009, 2010 Alex Bramley a.bramley@gmail.com
+
+=head1 SEE ALSO
+
+ca-init(1), ca-create-cert(1), ca-renew-cert(1), ca-scripts.conf(5),
+openssl(1ssl), ca(1ssl), req(1ssl), x509(1ssl), config(5ssl), and
+x509v3_config(5ssl).
+
+=cut
+
diff --git a/doc/revoke-cert.txt b/doc/revoke-cert.txt
deleted file mode 100644
index 1b66adb..0000000
--- a/doc/revoke-cert.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-# a brief man-page for revoke-cert.sh
-# $Id: revoke-cert.txt 2660 2009-07-24 18:49:52Z alexeb $
-
-NAME
-        revoke-cert.sh - revoke a certificate and generate revocation list
-
-SYNOPSIS
-        revoke-cert.sh /path/to/certificate
-        revoke-cert.sh <hostname>
-        revoke-cert.sh <username>
-
-DESCRIPTION
-        This script revokes the provided certificate and updates the revocation
-        list. It generates both a PEM and a DER encoded version of the CRL for
-        different browsers, and updates the html page with the new fingerprints.
-
-OPTIONS
-        This script takes no options.