Updates to README to reflect changes, misc. whitespace fixes.
This commit is contained in:
Alex Bramley
parent
3886d28224
commit
c6a5ba2704
9 changed files with 51 additions and 50 deletions
55
README.md
55
README.md
|
|
@ -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,
|
||||
and the root directory which will be populated with the generated certificates.
|
||||
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
|
||||
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)
|
||||
* [**req**(1ssl)](http://www.openssl.org/docs/apps/req.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)
|
||||
|
||||
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
|
||||
----------------------
|
||||
|
||||
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
|
||||
for authenticating a client to these services; and *user* certificates for
|
||||
authentication, S/MIME e-mail signing or encryption, and code signing. There
|
||||
are minor but important differences in the key usage extensions present in
|
||||
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
|
||||
certificate. The *--type* option is mandatory, and for *server* certs it is very
|
||||
likely that the *--alt-name* option will be useful to set X.509v3 subjectAltName
|
||||
DNS records for other hostnames for the server. Both the server hostname and
|
||||
any alternative names will be fully-qualified to **CA\_DOMAIN** if they do not
|
||||
contain any dots, but if unqualified names are passed in they are also
|
||||
preserved as alternative DNS names in the certificate. The private key may be
|
||||
encrypted with 3DES, and optionally the certificate, key, and CA certificate
|
||||
can be bundled together into a PKCS#12 format certificate archive. By default
|
||||
certificates are valid for 365 days from signing, but this may be changed with
|
||||
the *--days* option.
|
||||
**ca-create-cert**(1) takes a number of options to customise the generated
|
||||
certificate. The **--type** option defaults to creating *server* certs. It is
|
||||
likely that the **--alt-name** option (which sets X.509v3 subjectAltName DNS
|
||||
records for other hostnames for the server) will be useful; it may also be used
|
||||
when creating *client* certs. Both the server hostname and any alternative
|
||||
names will be fully-qualified to **CA\_DOMAIN** if they do not contain any dots
|
||||
unless the **--no-qualify** option is used. If unqualified names are passed in
|
||||
they are preserved as alternative DNS names in the certificate. The private key
|
||||
may be encrypted with 3DES using the **--encrypt** option, and the certificate,
|
||||
key, and CA certificate can be bundled together into a PKCS#12 format
|
||||
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
|
||||
**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
|
||||
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
|
||||
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*
|
||||
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
|
||||
generated that is valid for the correct period of time using the *--days* option
|
||||
to **ca-create-cert**(1).
|
||||
generated that is valid for the correct period of time using the **--days**
|
||||
option to **ca-create-cert**(1).
|
||||
|
||||
As with the certificate creation script the *--type* option is mandatory for
|
||||
**ca-renew-cert**(1), but the argument may be either a hostname, a username or a
|
||||
path to a certificate. Internally this will be resolved to the correct
|
||||
information required for certificate renewal.
|
||||
As with the certificate creation script a Common Name can be passed to
|
||||
identify the certificate to renew; alternatively the path to a previously
|
||||
created certificate can be given. Internally these will be both be resolved to
|
||||
the correct information required for certificate renewal.
|
||||
|
||||
Revoking a certificate
|
||||
----------------------
|
||||
|
||||
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
|
||||
*--type* option and either the hostname, username or the path to the certificate
|
||||
to be revoked. Along with **ca-init**(1) this script can optionally generate a
|
||||
basic HTML template to serve the CA certificate and CRL with verifiable MD5 and
|
||||
SHA1 checksums.
|
||||
both PEM and DER encodings, invoke **ca-revoke-cert**(1), again providing a
|
||||
Common Name or the path to the certificate to be revoked. Along with
|
||||
**ca-init**(1) this script can optionally generate a basic HTML template to
|
||||
serve the CA certificate and CRL with verifiable MD5 and SHA1 checksums.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ CSR_ONLY=0
|
|||
CRT_ONLY=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
|
||||
# should we have options here to change them when it will cause breakage?
|
||||
usage() {
|
||||
|
|
@ -83,7 +83,7 @@ ca_load_conf
|
|||
CA_CRT_CN="$1"
|
||||
|
||||
# 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!"
|
||||
fi
|
||||
|
||||
|
|
|
|||
|
|
@ -56,9 +56,9 @@ ENDDATE=$( openssl x509 -in "$CRT" -noout -enddate | 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
|
||||
# these dates are "<year> <day of year>"
|
||||
export TZ=UTC
|
||||
export TZ=UTC
|
||||
NOWYEAR=$( date +%Y )
|
||||
NOWDAYS=$( date +%j )
|
||||
NOWDAYS=$( date +%j )
|
||||
# XXX: this only works with GNU date, BSD portability fail.
|
||||
ENDYEAR=$( date +%Y -d "$ENDDATE + $CA_CRT_DAYS days" )
|
||||
ENDDAYS=$( date +%j -d "$ENDDATE + $CA_CRT_DAYS days" )
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ Options:
|
|||
|
||||
__EOT__
|
||||
}
|
||||
|
||||
|
||||
short="hf:t:l:i:o:"
|
||||
long="help,config:,type:,crl-days:,template:,output:"
|
||||
opts=$( getopt -o "$short" -l "$long" -n "$PROGNAME" -- "$@" )
|
||||
|
|
|
|||
|
|
@ -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_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.
|
||||
# Default value:
|
||||
# CA_DAYS=3652
|
||||
|
|
@ -51,7 +51,7 @@ CA_DN_CN="Example Security Services Root Certificate Authority"
|
|||
# CA_CRT_TYPE="server"
|
||||
|
||||
# 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.
|
||||
# Default value:
|
||||
# CA_PATHLEN=0
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ B<ca-renew-cert> [B<-h>] | [B<--help>]
|
|||
=head1 DESCRIPTION
|
||||
|
||||
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>.
|
||||
|
||||
=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
|
||||
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
|
||||
certificates.
|
||||
certificates.
|
||||
|
||||
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.
|
||||
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
|
||||
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
|
||||
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
|
||||
validity period, which ensures that no data is lost.
|
||||
|
||||
Arguably, it would be better to support both modes of renewal, and re-generate
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ ca_override_conf() {
|
|||
|
||||
ca_set_default() {
|
||||
local varname vardef
|
||||
|
||||
|
||||
varname="$1"
|
||||
vardef="$2"
|
||||
eval "if [ -z \"\$$varname\" ]; then
|
||||
|
|
@ -58,7 +58,7 @@ ca_load_conf() {
|
|||
CONFFILE="./$CONFFILE"
|
||||
fi
|
||||
. "$CONFFILE"
|
||||
|
||||
|
||||
error=""
|
||||
while read vartest varname; do
|
||||
varerr=$( ca_check_var "$varname" "$vartest" )
|
||||
|
|
@ -78,7 +78,7 @@ __TESTS__
|
|||
if [ -n "$error" ]; then
|
||||
error "Parsing config file $CONFFILE failed:\n$error"
|
||||
fi
|
||||
|
||||
|
||||
# check user-provided variables and copy them to CA_ namespace to override
|
||||
# any defaults that have potentially been set in configuration file
|
||||
# XXX: this is getting really dirty now, perhaps find an alternative?
|
||||
|
|
@ -131,7 +131,7 @@ ca_sed_cmd() {
|
|||
ca_template() {
|
||||
local template dest
|
||||
|
||||
if [ -r "$1" ]; then
|
||||
if [ -r "$1" ]; then
|
||||
template="$1"
|
||||
elif [ -r "$SHAREDIR/$1.tpl" ]; then
|
||||
template="$SHAREDIR/$1.tpl"
|
||||
|
|
@ -175,7 +175,7 @@ ca_cnf_name() {
|
|||
crt="$1"
|
||||
# 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 \
|
||||
-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:]@-' _ )
|
||||
# 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
|
||||
|
|
@ -207,10 +207,10 @@ ca_find_cnf() {
|
|||
error "Unable to derive config details from certificate '$name'."
|
||||
fi
|
||||
fi
|
||||
|
||||
|
||||
# XXX: this stil doesn't handle default types. FIXME when it's not 1am.
|
||||
_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
|
||||
# check if name is "user@domain", append $CA_DOMAIN if not
|
||||
if [ "${_name%%@*}" = "$_name" \
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ default_ca = ca_scripts
|
|||
# This defines our CA configuration
|
||||
[ ca_scripts ]
|
||||
# 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
|
||||
csr_dir = $dir/csr # generated CSRs 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
|
||||
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
|
||||
x509_extensions = ca_x509_default_extensions
|
||||
|
|
@ -36,7 +36,7 @@ policy = ca_extension_policy # policy on required CSR attribu
|
|||
|
||||
# leave these defaults
|
||||
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_crl_days= %CA_CRL_DAYS% # how long before next CRL
|
||||
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
|
||||
# ... and an [emailAddress] may optionally be supplied in the CSR
|
||||
# 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 ]
|
||||
countryName = match
|
||||
stateOrProvinceName = supplied
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ P { width: 700px; margin-left: 100px; }
|
|||
<BODY>
|
||||
<H1>%CA_DESC%</H1>
|
||||
<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>
|
||||
<P>MD5 Fingerprint: %CA_CRT_MD5_FP%</P>
|
||||
<P>SHA1 Fingerprint: %CA_CRT_SHA_FP%</P>
|
||||
|
|
|
|||
Loading…
Reference in a new issue