#! /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</etc/ca-scripts.conf>

=head1 DESCRIPTION

The B<ca-scripts.conf> 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<CA_HOME>="/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<CA_DOMAIN>="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<CA_DN_C>="GB"

CA_DN_C sets the I<Country> (C) field of the DN. It should be the two-letter
country code for the country your organisation resides in.

=item B<CA_DN_ST>="London"

CA_DN_ST sets the I<State> (ST) field of the DN.

=item B<CA_DN_L>="Example House, Mayfair"

CA_DN_L sets the I<Locality> (L) field of the DN.

=item B<CA_DN_O>="Example Security Services Ltd."

CA_DN_O sets the I<Organisation> (O) field of the DN.

=item B<CA_DN_OU>="Example Internet Encryption Division"

CA_DN_OU sets the I<Organisational Unit> (OU) field of the DN.

=item B<CA_DN_CN>="Example Security Services Root Certificate Authority"

CA_DN_CN sets the I<Common Name> (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_DESC>="$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<nsComment> extension in
the generated CA certificate, and as a header in the default HTML template.

=item B<CA_EMAIL>="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<CA_CRT_URI>="http://$CA_DOMAIN/ca/$CA_NAME.ca.crt"

=item B<CA_CRL_URI>="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<CA_DAYS>=3650

=item B<CA_CRT_DAYS>=365

=item B<CA_CRL_DAYS>=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<CA_CRT_BITS>=2048

CA_CRT_BITS sets the default key length for generated private keys.

=item B<CA_CRT_TYPE>="server"

CA_CRT_TYPE sets the default type of certificate created by ca-create-cert(1).
This can be set to I<server>, I<client>, or I<user>.

=item B<CA_PATHLEN>=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_CRT_C>="$CA_DN_C"

CA_CRT_C sets the I<Country> (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_CRT_ST>="$CA_DN_ST"

CA_CRT_ST sets the I<State> (ST) field of the DN. Equivalent to B<--state>.

=item B<CA_CRT_L>="$CA_DN_L"

CA_CRT_L sets the I<Locality> (L) field of the DN. Equivalent to B<--loc>.

=item B<CA_CRT_O>="$CA_DN_O"

CA_CRT_O sets the I<Organisation> (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_CRT_OU>="$CA_DN_OU"

CA_CRT_OU sets the I<Organisational Unit> (OU) field of the DN. Equivalent to
B<--ounit>.

=item B<CA_CRT_E>="$CA_EMAIL"

CA_CRT_E sets the I<E-Mail Address> (E) field of the DN. This will be moved
into the X.509v3 I<subhectAltName> 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<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-revoke-cert(1),
openssl(1ssl), ca(1ssl), x509(1ssl), and ocsp(1ssl).

=cut