Updates to README to reflect changes, misc. whitespace fixes.

This commit is contained in:
Alex Bramley 2010-03-13 18:04:59 +00:00
parent 3886d28224
commit c6a5ba2704
9 changed files with 51 additions and 50 deletions

View file

@ -42,7 +42,7 @@ created. This configuration file sets up some templating variables that will
be present in certificates created for this CA, such as the domain, CA name, be present in certificates created for this CA, such as the domain, CA name,
and the root directory which will be populated with the generated certificates. and the root directory which will be populated with the generated certificates.
An example configuration file is provided with the scripts, and the comments An example configuration file is provided with the scripts, and the comments
should be self-explanatory. should be self-explanatory.
By default the CA scripts will read `/etc/ca-scripts.conf`. This is fine for By default the CA scripts will read `/etc/ca-scripts.conf`. This is fine for
creating a single CA serving a single domain with no intermediary certificates, creating a single CA serving a single domain with no intermediary certificates,
@ -68,7 +68,7 @@ going to need to read the following:
* [**ca**(1ssl)](http://www.openssl.org/docs/apps/ca.html) * [**ca**(1ssl)](http://www.openssl.org/docs/apps/ca.html)
* [**req**(1ssl)](http://www.openssl.org/docs/apps/req.html) * [**req**(1ssl)](http://www.openssl.org/docs/apps/req.html)
* [**x509**(1ssl)](http://www.openssl.org/docs/apps/x509.html) * [**x509**(1ssl)](http://www.openssl.org/docs/apps/x509.html)
* [**config**(5ssl)](http://www.openssl.org/docs/apps/config.html) * [**config**(5ssl)](http://www.openssl.org/docs/apps/config.html)
* [**x509v3\_config**(5ssl)](http://www.openssl.org/docs/apps/x509v3_config.html) * [**x509v3\_config**(5ssl)](http://www.openssl.org/docs/apps/x509v3_config.html)
Particularly important are the x509v3 extensions present in the certificate, Particularly important are the x509v3 extensions present in the certificate,
@ -77,31 +77,33 @@ which are defined in the "ca\_x509\_extensions" section of the config file.
Creating a certificate Creating a certificate
---------------------- ----------------------
The **ca-create-cert**(1) script can generate three "types" of certificate: The **ca-create-cert**(1) script can generate three "types" of certificate:
*server* certificates for securing a service with SSL/TLS; *client* certificates *server* certificates for securing a service with SSL/TLS; *client* certificates
for authenticating a client to these services; and *user* certificates for for authenticating a client to these services; and *user* certificates for
authentication, S/MIME e-mail signing or encryption, and code signing. There authentication, S/MIME e-mail signing or encryption, and code signing. There
are minor but important differences in the key usage extensions present in are minor but important differences in the key usage extensions present in
these different certificate types, details can be found in the documentation these different certificate types, details can be found in the documentation
for **ca-create-cert**(1). for **ca-create-cert**(1). In each case, a Common Name must be provided to give
a unique name for the certificate.
**ca-create-cert**(1) takes a number of options to customise the generated **ca-create-cert**(1) takes a number of options to customise the generated
certificate. The *--type* option is mandatory, and for *server* certs it is very certificate. The **--type** option defaults to creating *server* certs. It is
likely that the *--alt-name* option will be useful to set X.509v3 subjectAltName likely that the **--alt-name** option (which sets X.509v3 subjectAltName DNS
DNS records for other hostnames for the server. Both the server hostname and records for other hostnames for the server) will be useful; it may also be used
any alternative names will be fully-qualified to **CA\_DOMAIN** if they do not when creating *client* certs. Both the server hostname and any alternative
contain any dots, but if unqualified names are passed in they are also names will be fully-qualified to **CA\_DOMAIN** if they do not contain any dots
preserved as alternative DNS names in the certificate. The private key may be unless the **--no-qualify** option is used. If unqualified names are passed in
encrypted with 3DES, and optionally the certificate, key, and CA certificate they are preserved as alternative DNS names in the certificate. The private key
can be bundled together into a PKCS#12 format certificate archive. By default may be encrypted with 3DES using the **--encrypt** option, and the certificate,
certificates are valid for 365 days from signing, but this may be changed with key, and CA certificate can be bundled together into a PKCS#12 format
the *--days* option. certificate archive by passing **--pkcs12**. By default certificates are valid
for 365 days from signing, but this may be changed with the **--days** option.
The certificate's DN can be completely changed from the defaults provided by The certificate's DN can be completely changed from the defaults provided by
**ca-scripts.conf**(5), but be wary as by default the generated openssl config **ca-scripts.conf**(5), but be wary as by default the generated openssl config
file requires that the country (C) and organisation (O) fields match those of file requires that the country (C) and organisation (O) fields match those of
the CA certificate. A comment may also be set that will show up in user browsers the CA certificate. A comment may also be set that will show up in user browsers
when they click on their padlock icons to examine the certificate's properties. when they click on their padlock icons to examine the certificate's properties.
As with the CA setup, the steps to generate the certificate can be split up so As with the CA setup, the steps to generate the certificate can be split up so
that configurations that are created from templates can be edited beforehand. that configurations that are created from templates can be edited beforehand.
@ -122,20 +124,19 @@ signed. In the future it is possible (even likely) that this renewal method
will only be used on *user* type certificates, and the *server* and *client* will only be used on *user* type certificates, and the *server* and *client*
types will be renewed normally. If the current renewal method doesn't provide types will be renewed normally. If the current renewal method doesn't provide
sufficient security, the current certificate should be revoked and a new one sufficient security, the current certificate should be revoked and a new one
generated that is valid for the correct period of time using the *--days* option generated that is valid for the correct period of time using the **--days**
to **ca-create-cert**(1). option to **ca-create-cert**(1).
As with the certificate creation script the *--type* option is mandatory for As with the certificate creation script a Common Name can be passed to
**ca-renew-cert**(1), but the argument may be either a hostname, a username or a identify the certificate to renew; alternatively the path to a previously
path to a certificate. Internally this will be resolved to the correct created certificate can be given. Internally these will be both be resolved to
information required for certificate renewal. the correct information required for certificate renewal.
Revoking a certificate Revoking a certificate
---------------------- ----------------------
To revoke a certificate and re-generate the CA certficate revocation list in To revoke a certificate and re-generate the CA certficate revocation list in
both PEM and DER encodings, invoke **ca-revoke-cert**(1), again providing the both PEM and DER encodings, invoke **ca-revoke-cert**(1), again providing a
*--type* option and either the hostname, username or the path to the certificate Common Name or the path to the certificate to be revoked. Along with
to be revoked. Along with **ca-init**(1) this script can optionally generate a **ca-init**(1) this script can optionally generate a basic HTML template to
basic HTML template to serve the CA certificate and CRL with verifiable MD5 and serve the CA certificate and CRL with verifiable MD5 and SHA1 checksums.
SHA1 checksums.

View file

@ -9,7 +9,7 @@ CSR_ONLY=0
CRT_ONLY=0 CRT_ONLY=0
MAKE_P12=0 MAKE_P12=0
# XXX: in the ca_extension_policy section of ca-config.tpl it states that the # XXX: in the ca_extension_policy section of ca-config.tpl it states that the
# C= and O= DN values in a CSR have to match those of the CA # C= and O= DN values in a CSR have to match those of the CA
# should we have options here to change them when it will cause breakage? # should we have options here to change them when it will cause breakage?
usage() { usage() {
@ -83,7 +83,7 @@ ca_load_conf
CA_CRT_CN="$1" CA_CRT_CN="$1"
# parameter checking fun -- we need a type and a cn (either user or host name) # parameter checking fun -- we need a type and a cn (either user or host name)
if [ -z "$CA_CRT_CN" ]; then if [ -z "$CA_CRT_CN" ]; then
error "The host or username parameter is mandatory!" error "The host or username parameter is mandatory!"
fi fi

View file

@ -56,9 +56,9 @@ ENDDATE=$( openssl x509 -in "$CRT" -noout -enddate | cut -d= -f2 )
SERIAL=$( openssl x509 -in "$CRT" -noout -serial | cut -d= -f2 ) SERIAL=$( openssl x509 -in "$CRT" -noout -serial | cut -d= -f2 )
# work out new expiry date based on expiry date of current cert # work out new expiry date based on expiry date of current cert
# these dates are "<year> <day of year>" # these dates are "<year> <day of year>"
export TZ=UTC export TZ=UTC
NOWYEAR=$( date +%Y ) NOWYEAR=$( date +%Y )
NOWDAYS=$( date +%j ) NOWDAYS=$( date +%j )
# XXX: this only works with GNU date, BSD portability fail. # XXX: this only works with GNU date, BSD portability fail.
ENDYEAR=$( date +%Y -d "$ENDDATE + $CA_CRT_DAYS days" ) ENDYEAR=$( date +%Y -d "$ENDDATE + $CA_CRT_DAYS days" )
ENDDAYS=$( date +%j -d "$ENDDATE + $CA_CRT_DAYS days" ) ENDDAYS=$( date +%j -d "$ENDDATE + $CA_CRT_DAYS days" )

View file

@ -16,7 +16,7 @@ Options:
__EOT__ __EOT__
} }
short="hf:t:l:i:o:" short="hf:t:l:i:o:"
long="help,config:,type:,crl-days:,template:,output:" long="help,config:,type:,crl-days:,template:,output:"
opts=$( getopt -o "$short" -l "$long" -n "$PROGNAME" -- "$@" ) opts=$( getopt -o "$short" -l "$long" -n "$PROGNAME" -- "$@" )

View file

@ -35,7 +35,7 @@ CA_DN_CN="Example Security Services Root Certificate Authority"
# CA_CRT_URI="http://$CA_DOMAIN/ca/$CA_NAME.ca.crt" # CA_CRT_URI="http://$CA_DOMAIN/ca/$CA_NAME.ca.crt"
# CA_CRL_URI="http://$CA_DOMAIN/ca/$CA_NAME.ca.crl" # CA_CRL_URI="http://$CA_DOMAIN/ca/$CA_NAME.ca.crl"
# OPTIONAL: CA_DAYS, CA_CRT_DAYS and CA_CRL_DAYS set the default validity # OPTIONAL: CA_DAYS, CA_CRT_DAYS and CA_CRL_DAYS set the default validity
# period for the CA cert, certificates and revocation lists. # period for the CA cert, certificates and revocation lists.
# Default value: # Default value:
# CA_DAYS=3652 # CA_DAYS=3652
@ -51,7 +51,7 @@ CA_DN_CN="Example Security Services Root Certificate Authority"
# CA_CRT_TYPE="server" # CA_CRT_TYPE="server"
# OPTIONAL: CA_PATHLEN sets the maximum number of intermediate CA certificates # OPTIONAL: CA_PATHLEN sets the maximum number of intermediate CA certificates
# that can be in the chain of authority between the root CA and the # that can be in the chain of authority between the root CA and the
# final certificate. # final certificate.
# Default value: # Default value:
# CA_PATHLEN=0 # CA_PATHLEN=0

View file

@ -27,7 +27,7 @@ B<ca-renew-cert> [B<-h>] | [B<--help>]
=head1 DESCRIPTION =head1 DESCRIPTION
B<ca-renew-cert> renews certificates generated with ca-create-cert(1), B<ca-renew-cert> renews certificates generated with ca-create-cert(1),
extending their validity for a configurable number of days, defaulting to extending their validity for a configurable number of days, defaulting to
B<CA_CRT_DAYS>. B<CA_CRT_DAYS>.
=head1 OPTIONS =head1 OPTIONS
@ -62,14 +62,14 @@ B<CA_CRT_DAYS> set in the configuration file.
B<ca-renew-cert> is currently very careful to re-use the original key and B<ca-renew-cert> is currently very careful to re-use the original key and
certificate serial when it renews a certificate. This is not strictly necessary certificate serial when it renews a certificate. This is not strictly necessary
for most renewals, and may in fact reduce the long-term security of your SSL for most renewals, and may in fact reduce the long-term security of your SSL
certificates. certificates.
The usual renewal process is to re-generate a new CSR and private The usual renewal process is to re-generate a new CSR and private
key with the same DN and sign it as valid for the required time period. key with the same DN and sign it as valid for the required time period.
This has the unfortunate side-effect of rendering unreadable all S/MIME e-mail This has the unfortunate side-effect of rendering unreadable all S/MIME e-mail
and data encrypted with the previous certificate and private key. It will also and data encrypted with the previous certificate and private key. It will also
invalidate any old digital signatures created with the previous certificate. invalidate any old digital signatures created with the previous certificate.
Instead, B<ca-renew-cert> re-signs the old CSR with the same serial and a new Instead, B<ca-renew-cert> re-signs the old CSR with the same serial and a new
validity period, which ensures that no data is lost. validity period, which ensures that no data is lost.
Arguably, it would be better to support both modes of renewal, and re-generate Arguably, it would be better to support both modes of renewal, and re-generate

View file

@ -39,7 +39,7 @@ ca_override_conf() {
ca_set_default() { ca_set_default() {
local varname vardef local varname vardef
varname="$1" varname="$1"
vardef="$2" vardef="$2"
eval "if [ -z \"\$$varname\" ]; then eval "if [ -z \"\$$varname\" ]; then
@ -58,7 +58,7 @@ ca_load_conf() {
CONFFILE="./$CONFFILE" CONFFILE="./$CONFFILE"
fi fi
. "$CONFFILE" . "$CONFFILE"
error="" error=""
while read vartest varname; do while read vartest varname; do
varerr=$( ca_check_var "$varname" "$vartest" ) varerr=$( ca_check_var "$varname" "$vartest" )
@ -78,7 +78,7 @@ __TESTS__
if [ -n "$error" ]; then if [ -n "$error" ]; then
error "Parsing config file $CONFFILE failed:\n$error" error "Parsing config file $CONFFILE failed:\n$error"
fi fi
# check user-provided variables and copy them to CA_ namespace to override # check user-provided variables and copy them to CA_ namespace to override
# any defaults that have potentially been set in configuration file # any defaults that have potentially been set in configuration file
# XXX: this is getting really dirty now, perhaps find an alternative? # XXX: this is getting really dirty now, perhaps find an alternative?
@ -131,7 +131,7 @@ ca_sed_cmd() {
ca_template() { ca_template() {
local template dest local template dest
if [ -r "$1" ]; then if [ -r "$1" ]; then
template="$1" template="$1"
elif [ -r "$SHAREDIR/$1.tpl" ]; then elif [ -r "$SHAREDIR/$1.tpl" ]; then
template="$SHAREDIR/$1.tpl" template="$SHAREDIR/$1.tpl"
@ -175,7 +175,7 @@ ca_cnf_name() {
crt="$1" crt="$1"
# work out what configuration files we should be using from the cert's CN # work out what configuration files we should be using from the cert's CN
echo $( openssl x509 -in "$crt" -noout -nameopt sep_multiline,use_quote \ echo $( openssl x509 -in "$crt" -noout -nameopt sep_multiline,use_quote \
-subject | awk -F= '/CN=/{ gsub("[^A-Za-z0-9@-]", "_", $2); print $2}' ) -subject | awk -F= '/CN=/{ gsub("[^A-Za-z0-9@-]", "_", $2); print $2}' )
# grep "CN=" | cut -d= -f2 | tr -c '[:alnum:]@-' _ ) # grep "CN=" | cut -d= -f2 | tr -c '[:alnum:]@-' _ )
# originally did this like the above but tried awk instead. awk(1) seems # originally did this like the above but tried awk instead. awk(1) seems
# to lie about it's egrep(1) support though as no matter what I tried the # to lie about it's egrep(1) support though as no matter what I tried the
@ -207,10 +207,10 @@ ca_find_cnf() {
error "Unable to derive config details from certificate '$name'." error "Unable to derive config details from certificate '$name'."
fi fi
fi fi
# XXX: this stil doesn't handle default types. FIXME when it's not 1am. # XXX: this stil doesn't handle default types. FIXME when it's not 1am.
_name=$( echo -n "$name" | tr -c '[:alnum:]@-' _ ) _name=$( echo -n "$name" | tr -c '[:alnum:]@-' _ )
if [ "$CA_CRT_TYPE" = "user" ]; then if [ "$CA_CRT_TYPE" = "user" ]; then
# user names may have dots etc. in, so use munged version in match # user names may have dots etc. in, so use munged version in match
# check if name is "user@domain", append $CA_DOMAIN if not # check if name is "user@domain", append $CA_DOMAIN if not
if [ "${_name%%@*}" = "$_name" \ if [ "${_name%%@*}" = "$_name" \

View file

@ -9,7 +9,7 @@ default_ca = ca_scripts
# This defines our CA configuration # This defines our CA configuration
[ ca_scripts ] [ ca_scripts ]
# interpolation variables defining the directories to use # interpolation variables defining the directories to use
dir = %CA_HOME% # root data directory of CA dir = %CA_HOME% # root data directory of CA
db_dir = $dir/db # database files are kept here db_dir = $dir/db # database files are kept here
csr_dir = $dir/csr # generated CSRs are kept here csr_dir = $dir/csr # generated CSRs are kept here
crt_dir = $dir/crt # signed CRTs are kept here crt_dir = $dir/crt # signed CRTs are kept here
@ -27,7 +27,7 @@ RANDFILE = $db_dir/.rand # private random number file
# these two CA directives can be commented out so that v1 CRLs are created # these two CA directives can be commented out so that v1 CRLs are created
crlnumber = $db_dir/crlnumber # crlnumber index file crlnumber = $db_dir/crlnumber # crlnumber index file
crl_extensions = ca_crl_extensions # extensions in v2 CRL crl_extensions = ca_crl_extensions # extensions in v2 CRL
# x509v3 certificate extensions and certificate signing policy # x509v3 certificate extensions and certificate signing policy
x509_extensions = ca_x509_default_extensions x509_extensions = ca_x509_default_extensions
@ -36,7 +36,7 @@ policy = ca_extension_policy # policy on required CSR attribu
# leave these defaults # leave these defaults
name_opt = oneline # Subject Name options - x509(1) name_opt = oneline # Subject Name options - x509(1)
cert_opt = ca_default # Certificate field options - x509(1) cert_opt = ca_default # Certificate field options - x509(1)
default_days = %CA_CRT_DAYS% # how long to certify for default_days = %CA_CRT_DAYS% # how long to certify for
default_crl_days= %CA_CRL_DAYS% # how long before next CRL default_crl_days= %CA_CRL_DAYS% # how long before next CRL
default_md = sha1 # which md to use. default_md = sha1 # which md to use.
@ -55,7 +55,7 @@ email_in_dn = no # remove email from CSR DN when signing
# the server common name [CN] to be supplied in the CSR # the server common name [CN] to be supplied in the CSR
# ... and an [emailAddress] may optionally be supplied in the CSR # ... and an [emailAddress] may optionally be supplied in the CSR
# XXX: is this too restrictive or not restrictive enough? # XXX: is this too restrictive or not restrictive enough?
# should options for ca-create-cert to change "match" values even exist? # should options for ca-create-cert to change "match" values even exist?
[ ca_extension_policy ] [ ca_extension_policy ]
countryName = match countryName = match
stateOrProvinceName = supplied stateOrProvinceName = supplied

View file

@ -13,7 +13,7 @@ P { width: 700px; margin-left: 100px; }
<BODY> <BODY>
<H1>%CA_DESC%</H1> <H1>%CA_DESC%</H1>
<H3>CA Certificate</H3> <H3>CA Certificate</H3>
<P>The CA certificate can be found <P>The CA certificate can be found
<A href="%CA_CRT_URI%">here</A></P> <A href="%CA_CRT_URI%">here</A></P>
<P>MD5 Fingerprint: %CA_CRT_MD5_FP%</P> <P>MD5 Fingerprint: %CA_CRT_MD5_FP%</P>
<P>SHA1 Fingerprint: %CA_CRT_SHA_FP%</P> <P>SHA1 Fingerprint: %CA_CRT_SHA_FP%</P>