Update documentation and program output

CHANGELOG

@@ -4,6 +4,7 @@
          - Always add REVISION value to installed certdata.txt
          - Use HG revision value (fall back to date for local files)
          - Allow rebuid within DESTDIR
+         - Complete manpage
 0.1      - Check executable bit for CERTUTIL, KEYTOOL, and OPENSSL
          - Allow global configuration file
          - Use correct license text (MIT)

Makefile

@@ -3,13 +3,13 @@ SBINDIR=/usr/sbin
 
 all:
 	chmod 755 make-ca help2man
-	./help2man -N ./make-ca -o make-ca.1
+	./help2man -s 8 -N ./make-ca -i include.h2m -o make-ca.8
 
 install:
 	/usr/bin/install -vdm755 $(DESTDIR)$(SBINDIR)
-	/usr/bin/install -vdm755 $(DESTDIR)$(MANDIR)/man1
+	/usr/bin/install -vdm755 $(DESTDIR)$(MANDIR)/man8
 	install -vm755 make-ca $(DESTDIR)$(SBINDIR)
-	install -vm644 make-ca.1 $(DESTDIR)$(MANDIR)/man1
+	install -vm644 make-ca.8 $(DESTDIR)$(MANDIR)/man8
 
 .PHONY: all install
 

include.h2m

@@ -0,0 +1,38 @@
+[SYNOPSYS]
+make-ca -g
+
+[EXAMPLES]
+The make-ca script will process the certificates included in the certdata.txt
+file for use in multiple certificate stores (if the associated applications are
+present on the system). Additionally, any local certificates stored in
+/etc/ssl/local will be imported to the certificate stores. Certificates in this
+directory should be stored as PEM encoded OpenSSL trusted certificates.
+
+To create an OpenSSL trusted certificate from a regular PEM encoded file,
+provided by a CA not included in Mozilla's certificate distribution, you need
+to add trust arguments to the openssl command, and create a new certificate.
+There are three trust types that are recognized by the make-ca.sh script,
+SSL/TLS, S/Mime, and code signing. For example, using the CAcert root, if you
+want it to be trusted for all three roles, the following commands will create
+an appropriate OpenSSL trusted certificate:
+
+  #\ install -vdm755 /etc/ssl/local \                                 
+  #\ wget http://www.cacert.org/certs/root.crt \                      
+  #\ openssl x509 -in root.crt -text -fingerprint \\ \                
+                 -setalias "CAcert Class 1 root" \\ \                 
+                 -addtrust serverAuth \\ \                            
+                 -addtrust emailProtection \\ \                       
+                 -addtrust codeSigning \\ \                           
+            > /etc/ssl/local/CAcert_Class_1_root.pem
+
+If one of the three trust arguments is omitted, the certificate is neither
+trusted, nor rejected for that role. Clients that use OpenSSL or NSS
+encountering this certificate will present a warning to the user. Clients using
+GnuTLS without p11-kit support are not aware of trusted certificates. To
+include this CA into the ca-bundle.crt (used for GnuTLS), it must have
+serverAuth trust. Additionally, to explicitly disallow a certificate for a
+particular use, replace the -addtrust flag with the -addreject flag.
+
+Local trust overrides are handled entirely using the /etc/ssl/local directory.
+To override Mozilla's trust values, simply make a copy of the certificate in
+the local directory with alternate trust values.

make-ca

@@ -8,7 +8,7 @@
 # Authors: DJ Lucas
 #          Bruce Dubbs
 
-VERSION="0.1"
+VERSION="0.2"
 
 # Get/set defaults
 if test -f /etc/make-ca.conf; then
@@ -233,63 +233,72 @@ function check_arg(){
 
 function showhelp(){
   echo ""
-  echo "`basename ${0}` converts certdata.txt (provided by the Mozilla Foundation)"
+  echo "`basename ${0}` is a utility to deliver and manage a complete PKI configuration"
-  echo "into a complete PKI distribution for use with LFS or like distributions."
+  echo "for workstaitons and servers using only standard Unix utilities and OpenSSL. It"
+  echo "will optionally generate keystores for OpenJDK and NSS if already installed,"
+  echo "using a Mozilla cacerts.txt or like formatted file. It was originally developed"
+  echo "for use with Linux From Scratch to minimize dependencies for early system"
+  echo "build, but has been written to be generic enough for any Linux distribution."
   echo ""
-  echo "        -C  --certdata   The certdata.txt file (provided by Mozilla)"
+  echo "        -C, --certdata [certdata.txt]"
-  echo "                         Default: ./certdata.txt"
+  echo "                         The location of the certificates source."
   echo ""
-  echo "        -D  --destdir    Change the output directory and use relative"
+  echo "        -D, --destdir [/]"
+  echo "                         Change the output directory and use relative"
   echo "                         paths for all other values."
-  echo "                         Default: unset"
   echo ""
-  echo "        -P  --pkidir     The output PKI directory - Cannot be used with"
+  echo "        -P, --pkidir [/etc/pki]"
-  echo "                         the -a/--anchordir or -n/--nssdb switches"
+  echo "                         The output PKI directory - Cannot be used with"
-  echo "                         Default: /etc/pki"
+  echo "                         the -a / --anchordir or -n / --nssdb switches"
   echo ""
-  echo "        -S  --ssldir     The output SSL root direcotry - Cannot be used"
+  echo "        -S, --ssldir [/etc/ssl]"
-  echo "                         with the -c/--cafile, -d/--cadir, or"
+  echo "                         The output SSL root direcotry - Cannot be used"
-  echo "                         -j/--javacerts switches"
+  echo "                         with the -c / --cafile, -d / --cadir, or"
-  echo "                         Defualt: /etc/ssl"
+  echo "                         -j / --javacerts switches"
   echo ""
-  echo "        -a  --anchordir  The output directory for OpenSSL trusted"
+  echo "        -a, --anchordir [\$PKIDIR/anchors]"
+  echo "                         The output directory for OpenSSL trusted"
   echo "                         CA certificates used as trust anchors."
-  echo "                         Default: \$PKIDIR/anchors"
   echo ""
-  echo "        -c  --cafile     The output filename for the PEM formated bundle"
+  echo "        -c, --cafile [\$SSLDIR/ca-bundle.crt]"
-  echo "                         Default: \$SSLDIR/ca-bundle.crt"
+  echo "                         The output filename for the PEM formated bundle"
   echo ""
-  echo "        -d  --cadir      The output directory for the OpenSSL trusted"
+  echo "        -d, --cadir [\$SSLDIR/certs]"
+  echo "                         The output directory for the OpenSSL trusted"
   echo "                         CA certificates"
-  echo "                         Deault: \$SSLDIR/certs/"
   echo ""
-  echo "        -g  --get        Download certdata.txt directly from Mozilla's"
+  echo "        -j, --javacerts [\$SSLDIR/java/cacerts]"
+  echo "                         The output path for the Java cacerts file"
+  echo ""
+  echo "        -l, --localdir [\$SSLDIR/local]"
+  echo "                         The path to a local set of OpenSSL trusted"
+  echo "                         certificates, used to both override trust bits"
+  echo "                         from upstream sources and provide locally"
+  echo "                         provided certifiates."
+  echo ""
+  echo "        -n, --nssdb [\$PKIDIR/nssdb]"
+  echo "                         The output path for the shared NSS DB"
+  echo ""
+  echo "        -k, --keytool [PATH]"
+  echo "                         The path to the java keytool utility"
+  echo ""
+  echo "        -s, --openssl [PATH]"
+  echo "                         The path to the openssl utility"
+  echo ""
+  echo "        -t, --certutil [PATH]"
+  echo "                         The path the certutil utility"
+  echo ""
+  echo "        -f, --force      Force run, even if source is not newer"
+  echo ""
+  echo "        -g, --get        Download certdata.txt directly from Mozilla's"
   echo "                         Mecurial server."
   echo ""
-  echo "        -j  --javacerts  The output path for the Java cacerts file"
+  echo "        -h, --help       Show this help message and exit"
-  echo "                         Default: \$SSLDIR/java/cacerts"
   echo ""
-  echo "        -l  --localdir   The path to a local set of OpenSSL trusted"
+  echo "        -r, --rebuild    Rebuild the enitre PKI tree using the previous"
-  echo "                         certificates to include in the output"
-  echo "                         Default: \$SSLDIR/local"
-  echo ""
-  echo "        -n  --nssdb      The output path for the shared NSS DB"
-  echo "                         Default: \$PKIDIR/nssdb"
-  echo ""
-  echo "        -k  --keytool    The path to the java keytool utility"
-  echo ""
-  echo "        -r  --rebuild    Rebuild the enitre PKI tree using the previous"
   echo "                         certdata.txt file."
   echo ""
-  echo "        -s  --openssl    The path to the openssl utility"
+  echo "        -v. --version    Show version information and exit"
-  echo ""
-  echo "        -t  --certutil   The path the certutil utility"
-  echo ""
-  echo "        -f  --force      Force run, even if source is not newer"
-  echo ""
-  echo "        -h  --help       Show this help message and exit"
-  echo ""
-  echo "        -v  --version    Show version information and exit"
   echo ""
   echo "Example: `basename ${0}` -f -C ~/certdata.txt"
   echo ""