Finished up ca-scripts.conf docs.
This commit is contained in:
Alex Bramley
parent
c6a5ba2704
commit
a39c584d0a
|
|
@ -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</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
|
||||
Loading…
Reference in New Issue