Move README and convert to shiny markdown format.
This commit is contained in:
Alex Bramley
parent
1d37f83385
commit
4a85aae505
2 changed files with 128 additions and 95 deletions
128
README.md
Normal file
128
README.md
Normal file
|
|
@ -0,0 +1,128 @@
|
||||||
|
ca-scripts
|
||||||
|
==========
|
||||||
|
|
||||||
|
A set of `bash(1)` scripts for working with SSL Certificate Authorities.
|
||||||
|
|
||||||
|
These scripts are designed to provide a configurable wrapping layer around
|
||||||
|
[openssl](http://www.openssl.org/), similar to CA.pl. They're potentially a
|
||||||
|
little heavyweight if you just need a single self-signed certificate to secure
|
||||||
|
an HTTPs webserver, but they may come in handy if you want to:
|
||||||
|
|
||||||
|
* Generate multiple service certificates signed by a single authority
|
||||||
|
* Provide signed client certificates to end users for authentication purposes
|
||||||
|
* Provide client certificates for S/MIME encrypted e-mail or code signing
|
||||||
|
* Easily set extensions such as x509v3 subjectAltName in your certificates
|
||||||
|
|
||||||
|
Installation
|
||||||
|
------------
|
||||||
|
|
||||||
|
There aren't any tarballs as yet. Nor will the `make` command below work until
|
||||||
|
I've written a Makefile. It's coming, sometime. Sorry ;-)
|
||||||
|
|
||||||
|
$ git clone git://github.com/fluffle/ca-scripts
|
||||||
|
$ cd ca-scripts
|
||||||
|
$ make; sudo make install
|
||||||
|
|
||||||
|
This will by default install to `/usr/local`, either `export PREFIX=/path` or
|
||||||
|
`make PREFIX=/path; sudo make PREFIX=/path install` to change this to an
|
||||||
|
alternative location.
|
||||||
|
|
||||||
|
Creating a Certificate Authority
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
Before running `ca-init(1)`, a configuration file for the CA scripts must be
|
||||||
|
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.
|
||||||
|
|
||||||
|
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,
|
||||||
|
but for a more complex setup a directory of configuration files will probably
|
||||||
|
be needed. Some settings are required, namely the `CA_HOME`, `CA_DOMAIN`, and
|
||||||
|
`CA_DN_*` variables, while others can be inferred from these or have sensible
|
||||||
|
defaults set. See `ca-scripts.conf(5)` for more detail on these.
|
||||||
|
|
||||||
|
Once the configuration has been created the initial CA setup can be performed
|
||||||
|
with `ca-init(1)`, but please note that the path set in `CA_HOME` must exist and
|
||||||
|
be writeable before it will run correctly. It is recommended (but not in any way
|
||||||
|
required) to create an unprivileged "`ssl`" user to run all the scripts as, so
|
||||||
|
the permissions are correctly set. A number of subdirectories will be set
|
||||||
|
up underneath this root, and an openssl configuration file, certificate and
|
||||||
|
private key will be generated. This key can be 3DES encrypted for security.
|
||||||
|
|
||||||
|
Optionally, it is possible to split the initial setup process so that the
|
||||||
|
directory structure and openssl configuration generation can be done in a
|
||||||
|
seperate step to the generation of the CA certificates, so that the config can
|
||||||
|
be manually edited. To fully understand it's contents you're unfortunately
|
||||||
|
going to need to read `ca(1ssl)`, `req(1ssl)`, `x509(1ssl)`, `config(5ssl)`,
|
||||||
|
and `x509v3_config(5ssl)`. Particularly important are the x509v3 extensions
|
||||||
|
present in the certificate, 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:
|
||||||
|
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 extension
|
||||||
|
templates provided with the scripts.
|
||||||
|
|
||||||
|
`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 x509v3 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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
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.
|
||||||
|
|
||||||
|
Renewing a certificate
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
Certificates are renewed using `ca-renew-cert(1)`. This script currently does
|
||||||
|
some painful certificate manipulation that is not strictly necessary in most
|
||||||
|
cases, and may in fact decrease SSL security slightly. This is done because
|
||||||
|
the normal renewal process re-generates the certificate signing request and
|
||||||
|
thus creates a new public/private keypair. If the certificates are used for
|
||||||
|
S/MIME encryption or code signing, this renders all the encrypted e-mail
|
||||||
|
unreadable and requires you to re-sign the code with your new private key.
|
||||||
|
|
||||||
|
To avoid this, `ca-renew-cert(1)` re-signs the old certificate request with a
|
||||||
|
a new expiry date using the extensions generated when the old certificate was
|
||||||
|
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)`.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
95
doc/README
95
doc/README
|
|
@ -1,95 +0,0 @@
|
||||||
1. Creating a Certificate Authority.
|
|
||||||
|
|
||||||
Before running ca-init(1), a configuration file for the CA scripts must be
|
|
||||||
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.
|
|
||||||
|
|
||||||
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,
|
|
||||||
but for a more complex setup a directory of configuration files will probably
|
|
||||||
be needed. Some settings are required, namely the CA_HOME, CA_DOMAIN, and
|
|
||||||
CA_DN_* variables, while others can be inferred from these or have sensible
|
|
||||||
defaults set. See ca-scripts.conf(5) for more detail on these.
|
|
||||||
|
|
||||||
Once the configuration has been created the initial CA setup can be performed
|
|
||||||
with ca-init(1), but please note that the path set in CA_HOME must exist and be
|
|
||||||
writeable before it will run correctly. It is recommended (but not in any way
|
|
||||||
required) to create an unprivileged "ssl" user to run all the scripts as, so
|
|
||||||
the permissions are correctly set. A number of subdirectories will be set
|
|
||||||
up underneath this root, and an openssl configuration file, certificate and
|
|
||||||
private key will be generated. This key can be 3DES encrypted for security.
|
|
||||||
|
|
||||||
Optionally, it is possible to split the initial setup process so that the
|
|
||||||
directory structure and openssl configuration generation can be done in a
|
|
||||||
seperate step to the generation of the CA certificates, so that the config can
|
|
||||||
be manually edited. To fully understand it's contents you're unfortunately
|
|
||||||
going to need to read ca(1ssl), req(1ssl), x509(1ssl), config(5ssl), and
|
|
||||||
x509v3_config(5ssl). Particularly important are the x509v3 extensions present
|
|
||||||
in the certificate, which are defined in the "ca_x509_extensions" section of
|
|
||||||
the config file.
|
|
||||||
|
|
||||||
2. Creating a 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 extension
|
|
||||||
templates provided with the scripts.
|
|
||||||
|
|
||||||
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 x509v3 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.
|
|
||||||
|
|
||||||
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. 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.
|
|
||||||
|
|
||||||
3. Renewing a certificate.
|
|
||||||
|
|
||||||
Certificates are renewed using ca-renew-cert(1). This script currently does
|
|
||||||
some painful certificate manipulation that is not strictly necessary in most
|
|
||||||
cases, and may in fact decrease SSL security slightly. This is done because
|
|
||||||
the normal renewal process re-generates the certificate signing request and
|
|
||||||
thus creates a new public/private keypair. If the certificates are used for
|
|
||||||
S/MIME encryption or code signing, this renders all the encrypted e-mail
|
|
||||||
unreadable and requires you to re-sign the code with your new private key.
|
|
||||||
|
|
||||||
To avoid this, ca-renew-cert(1) re-signs the old certificate request with a
|
|
||||||
a new expiry date using the extensions generated when the old certificate was
|
|
||||||
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).
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
4. 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.
|
|
||||||
Loading…
Reference in a new issue