Created ca-init manpage and deleted ca-cert.txt

2009-10-18 17:18:38 +01:00 · 2009-10-18 17:18:38 +01:00 · 78e49b931b
parent 21147b6b9a
commit 78e49b931b
3 changed files with 167 additions and 17 deletions
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1 @@
+*.swp
--- a/doc/ca-cert.txt
+++ b/doc/ca-cert.txt
@ -1,17 +0,0 @@
-# a brief man-page for ca-cert.sh
-# $Id: ca-cert.txt 2660 2009-07-24 18:49:52Z alexeb $
-
-NAME
-        ca-cert.sh - generate a CA cert and perform initial db setup
-
-SYNOPSIS
-        ca-cert.sh
-
-DESCRIPTION
-        This script generates a CSR and signs it to turn it into a root
-        certificate authority. It also sets up some important files in the CA
-        database directory, generates an initial empty revocation list, and
-        creates index.html from the template.
-
-OPTIONS
-        This script takes no options.
--- a/doc/ca-init.1
+++ b/doc/ca-init.1
@ -0,0 +1,166 @@
+.TH "ca-init" "1" "16 October 2009" "ca-scripts version 0.9" "SSL Certificate Authority utilities" 
+.SH NAME
+ca-init \- initialise an SSL CA and generate certificates
+.
+.SH SYNOPSIS
+.
+.SY ca-init
+.OP \-csx
+.OP \-f config
+.OP \-i template
+.OP \-o output
+.
+.SY ca-init
+.OP \-h
+|
+.OP \-\-help
+.YS
+.
+.SH DESCRIPTION
+.
+\fBca-init\fR reads the ca-scripts configuration file passed to the \fB\-f\fR
+or \fB\-\-config\fR option, or \fI/etc/ca-scripts.conf\fR by default, and uses
+the information there to generate an
+.BR openssl (1)
+configuration file and a certificate and private key suitable for use as an
+.BR x509 (1)
+certificate authority. The format of the ca-scripts configuration file is
+documented in
+.BR ca-scripts.conf (5).
+.
+.SH OPTIONS
+.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Prints out a short synopsis of the options to
+.BR ca-init (1).
+.
+.TP
+\fB\-c\fR, \fB\-\-encrypt\fR
+Encrypt the private key generated for the certificate authority with 3DES.
+.
+.TP
+\fB\-f \fIFILE\fR, \fB\-\-config \fIFILE\fR
+Load the ca-scripts configuration from \fIFILE\fR instead of
+\fI/etc/ca-scripts.conf\fR.
+.
+.TP
+\fB\-i \fIFILE\fR, \fB\-\-template \fIFILE\fR
+Use the index.html template in \fIFILE\fR rather than the standard one
+provided with ca-scripts. See the \fBTEMPLATING\fR section of
+.BR ca-scripts.conf (5)
+for more details of the templating system. Hint: it's
+.BR sed (1)
+based...
+.
+.TP
+\fB\-o \fIFILE\fR, \fB\-\-output \fIFILE\fR
+Generate a HTML page in \fIFILE\fR 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.
+.
+.TP
+\fB\-s\fR, \fB\-\-crt-only\fR
+Generate the CA certificate and private key from a previously-created openssl
+configuration. May only be used after having run \fBca-init\fR with the 
+\fB\-\-cnf-only\fR option, and mutually exclusive to that option.
+.
+.TP
+\fB\-x\fR, \fB\-\-cnf-only\fR
+Create initial CA directory structure and openssl configuration, but do not
+generate CA certificate and private key. Using this option in conjunction with
+\fB\-\-crt-only\fR allows the user to manually customise the openssl config
+before generating the certificates. Mutually exclusive to \fB\-\-crt-only\fR.
+.
+.SH THE CA DIRECTORY STRUCTURE
+.
+\fBca-init\fR creates a number of subdirectories under the path specified in
+the mandatory configuration variable \fICA_HOME\fR. This path must exist before
+\fBca-init\fR will run correctly. All files and directories under this path
+will be created with a restrictive umask of 0027, and in particular the CA
+private key will be created with permissions of 0400.
+.PP
+It is recommended but not required that a non-privileged system "ssl" user and
+group are created for running the ca-scripts suite of utilities, and that any
+local services needing access to a certificate are added to the "ssl" group.
+Access to generate certificates can be bestowed to individuals on a multi-user
+system by adding them to the same group and allowing them to run ca-scripts
+utilities via
+.BR sudo (8).
+.PP
+The directories \fBca-init\fR creates are as follows:
+.TP
+\fIcnf/\fR
+Contains a cache of openssl configuration files created by the various
+ca-scripts utilities from templates.
+.
+.TP
+\fIcrl/\fR
+Contains the certificate revocation list for the CA in both PEM and DER forms.
+.
+.TP
+\fIcrt/\fR
+Contains the signed certificates generated by
+.BR ca-create-cert (1).
+.
+.TP
+\fIcsr/\fR
+Contains the unsigned certificate signing requests generated by
+.BR ca-create-cert (1).
+.
+.TP
+\fIdb/\fR
+Contains internal 
+.BR openssl (1ssl)
+database files required for certificate authority management.
+.
+.TP
+\fIidx/\fR
+Contains signed certificates indexed by serial number to make certificate 
+revocation simpler.
+.
+.TP
+\fIkey/\fR
+Contains the private keys associated with the certificates in \fIcrt/\fR.
+.
+.TP
+\fIp12/\fR
+Contains any generated PKCS#12 certificate archives created by
+.BR ca-create-cert (1).
+.
+.SH BUGS
+Probably. Of particular note is that the default openssl configuration file
+requires the C (country) and O (organisation) fields of all generated
+certificates to match those in the CA certificate, but
+.BR ca-create-cert (1)
+allows these fields to be changed.
+.
+.SH AVAILABILITY
+New releases of the ca-scripts utilities can be found at
+.UR http://\:www.pl0rt.org/\:code/\:ca-scripts
+the developer's website.
+.UE .
+A 
+.UR git://\:git.pl0rt.org/\:alex/\:code/\:ca-scripts
+git repository
+.UE
+for development versions also exists.
+.
+.SH AUTHORS
+.
+Copyright \(co 2009
+.MT a.bramley@gmail.com
+Alex Bramley
+.ME .
+.
+.SH SEE ALSO
+.
+.BR ca-create-cert (1),
+.BR ca-scripts.conf (5),
+.BR openssl (1ssl),
+.BR ca (1ssl),
+.BR req (1ssl),
+.BR x509 (1ssl),
+.BR config (5ssl), and
+.BR x509v3_config (5ssl).
+.