From a39c584d0afb608a9fe91009cda0fbb25a1997a7 Mon Sep 17 00:00:00 2001 From: Alex Bramley Date: Sun, 14 Mar 2010 01:29:50 +0000 Subject: [PATCH] Finished up ca-scripts.conf docs. --- doc/ca-scripts.conf.pod | 223 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100755 doc/ca-scripts.conf.pod diff --git a/doc/ca-scripts.conf.pod b/doc/ca-scripts.conf.pod new file mode 100755 index 0000000..d1afa7d --- /dev/null +++ b/doc/ca-scripts.conf.pod @@ -0,0 +1,223 @@ +#! /bin/sh + +if [ -z "$1" -o "$1" == "man" ]; then + exec /usr/bin/pod2man -n CA-SCRIPTS.CONF -s 5 -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-scripts.conf(5)" < $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-scripts.conf - configuration file for ca management scripts + +=head1 SYNOPSIS + +B + +=head1 DESCRIPTION + +The B configuration file is used to set various parameters for +the creation of certificate authorities and signed certificates. It is sourced +directly and must be valid bash(1) syntax. + +=head1 OPTIONS + +=head2 Required Configuration Settings + +The following settings MUST be present in the configuration file for the ca +management scripts to work. The values given in this manpage are the ones from +the example configuration file. + +=over + +=item B="/etc/ssl/ca-scripts" + +CA_HOME provides the path to the root of the CA directory tree. This directory +must exist and be writeable by the user running the scripts. + +=item B="example.com" + +CA_DOMAIN provides a template for other optional variables and the filenames +that are generated within the directory tree. It should be set to the domain +that you are generating SSL certificates for. + +=back + +=head2 CA Distinguished Name Configuration + +These settings configure the Distinguished Name fields present in the CA +certificate generated by ca-init(1) and provide default values for the DN +fields in other certificates generated by ca-create-cert(1). They should be +set to sensible defaults for the organisation you are generating SSL +certificates for, and MUST be present in the configuration file. + +=over + +=item B="GB" + +CA_DN_C sets the I (C) field of the DN. It should be the two-letter +country code for the country your organisation resides in. + +=item B="London" + +CA_DN_ST sets the I (ST) field of the DN. + +=item B="Example House, Mayfair" + +CA_DN_L sets the I (L) field of the DN. + +=item B="Example Security Services Ltd." + +CA_DN_O sets the I (O) field of the DN. + +=item B="Example Internet Encryption Division" + +CA_DN_OU sets the I (OU) field of the DN. + +=item B="Example Security Services Root Certificate Authority" + +CA_DN_CN sets the I (CN) field of the DN. This is what users will +see listed in their browser when they look at the certificate properties. + +=back + +=head2 Optional Configuration Settings + +These settings can be derived programmatically from the above, or have sensible +defaults that may be overridden in the configuration file. + +=over + +=item B="$CA_DN_CN" + +CA_DESC configures a single-line description for your CA. Using the CN= or O= +line from your DN is recommended. This is used as the I extension in +the generated CA certificate, and as a header in the default HTML template. + +=item B="ca@$CA_DOMAIN" + +CA_EMAIL provides an e-mail address that is embedded into all generated +certificates as a point-of-contact for the issuing certificate authority. It's +probably a good idea to ensure that this address is valid and checked +regularly. + +=item B="http://$CA_DOMAIN/ca/$CA_NAME.ca.crt" + +=item B="http://$CA_DOMAIN/ca/$CA_NAME.ca.crl" + +CA_CRT_URI and CA_CRL_URI provide globally accessible locations where the CA +certificate and revocation lists can be found. These are embedded into every +generated certificate, so they should point to valid URIs. + +=item B=3650 + +=item B=365 + +=item B=365 + +CA_CRT_DAYS and CA_CRL_DAYS sets the default validity period for certificates +respectively. If your CA generates and revokes a lot of certificates, it is +probably a good idea to reduce the latter value considerably or use OCSP +instead. + +=item B=2048 + +CA_CRT_BITS sets the default key length for generated private keys. + +=item B="server" + +CA_CRT_TYPE sets the default type of certificate created by ca-create-cert(1). +This can be set to I, I, or I. + +=item B=0 + +CA_PATHLEN sets the maximum number of intermediate CA certificates that can be +in the chain of authority between the root CA and the final certificate. + +=back + +=head2 Certificate Distinguished Name Configuration + +The DN of a certificate generated with ca-create-cert(1) defaults to copying +that of the CA, but alternative defaults can be set instead using the following +options. These values are more usually set with command-line arguments, but +there may be useful reasons to do otherwise. Note that there is no way to set a +default CN, as this should be unique to the certificate being generated. + +=over + +=item B="$CA_DN_C" + +CA_CRT_C sets the I (C) field of the DN. It should be the two-letter +country code for the country your organisation resides in. WARNING: changing +this from the value in your CA certificate may break certificate validation, +due to the extension policy defined in the openssl configuration for the CA. +Equivalent to the B<--country> argument to ca-create-cert(1). + +=item B="$CA_DN_ST" + +CA_CRT_ST sets the I (ST) field of the DN. Equivalent to B<--state>. + +=item B="$CA_DN_L" + +CA_CRT_L sets the I (L) field of the DN. Equivalent to B<--loc>. + +=item B="$CA_DN_O" + +CA_CRT_O sets the I (O) field of the DN. WARNING: changing +this from the value in your CA certificate may break certificate validation, +due to the extension policy defined in the openssl configuration for the CA. +Equivalent to B<--org>. + +=item B="$CA_DN_OU" + +CA_CRT_OU sets the I (OU) field of the DN. Equivalent to +B<--ounit>. + +=item B="$CA_EMAIL" + +CA_CRT_E sets the I (E) field of the DN. This will be moved +into the X.509v3 I extension when the certificate is signed as +per the X.509 spec. Equivalent to B<--email>. + +=back + +=head1 TEMPLATING + +Under the hood, the ca management scripts work by substituting values from the +configuration file and command line arguments into a set of config(5) +templates, then calling the openssl(1) binary to Do The Right Thing. The HTML +for the CA index page is generated in the same manner. + +=head1 CAVEATS + +The templating system is really just a couple of bash(1) functions that build +up a sed(1) script to substitute environment variables into the template files. +It works, but could potentially be considered as a bug just for existing. Using +ascii 1 ("\001", ctrl-a) in your templating variables will break Everything. +Don't do it! + +=head1 AVAILABILITY + +New releases of the ca-scripts utilities can be found at +L. +A L +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-revoke-cert(1), +openssl(1ssl), ca(1ssl), x509(1ssl), and ocsp(1ssl). + +=cut