psi-jack/ca-scripts
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Some re-wording and formatting fixes for README.md

Browse source
This commit is contained in:
Alex Bramley 2010-02-14 06:50:25 +00:00
parent a8ae2ea085
commit 58aa925513
1 changed files with 40 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

74
README.md
View file

@ -30,7 +30,7 @@ alternative location.
Creating a Certificate Authority Creating a Certificate Authority
-------------------------------- --------------------------------
Before running `ca-init(1)`, a configuration file for the CA scripts must be 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 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.
@ -40,14 +40,14 @@ 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,
but for a more complex setup a directory of configuration files will probably 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 be needed. Some settings are required, namely the **CA\_HOME**, **CA\_DOMAIN**,
`CA_DN_*` variables, while others can be inferred from these or have sensible and **CA\_DN\_\*** variables, while others can be inferred from these or have
defaults set. See `ca-scripts.conf(5)` for more detail on these. 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 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 with **ca-init(1)**, but please note that the path set in **CA\_HOME** must exist
be writeable before it will run correctly. It is recommended (but not in any way and be writeable before it will run correctly. It is recommended (but not in an
required) to create an unprivileged "`ssl`" user to run all the scripts as, so 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 the permissions are correctly set. A number of subdirectories will be set
up underneath this root, and an openssl configuration file, certificate and up underneath this root, and an openssl configuration file, certificate and
private key will be generated. This key can be 3DES encrypted for security. private key will be generated. This key can be 3DES encrypted for security.
@ -56,36 +56,42 @@ private key will be generated. This key can be 3DES encrypted for security.
directory structure and openssl configuration generation can be done in a 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 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 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)`, going to need to read the following:
and `x509v3_config(5ssl)`. Particularly important are the x509v3 extensions
present in the certificate, which are defined in the "ca\_x509\_extensions" * [**ca**(1ssl)](http://www.openssl.org/docs/apps/ca.html)
section of the config file. * [**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)
* [**x509v3\_config**(5ssl)](http://www.openssl.org/docs/apps/x509v3_config.html)
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 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 extension these different certificate types, details can be found in the documentation
templates provided with the scripts. for **ca-create-cert**(1).
`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 is mandatory, and for *server* certs it is very
likely that the `--alt-name` option will be useful to set x509v3 subjectAltName 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 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 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 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 preserved as alternative DNS names in the certificate. The private key may be
encrypted with 3DES, and optionally the certificate, key, and CA certificate encrypted with 3DES, and optionally the certificate, key, and CA certificate
can be bundled together into a PKCS#12 format certificate archive. By default 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 certificates are valid for 365 days from signing, but this may be changed with
the `--days` option. 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.
@ -95,25 +101,25 @@ that configurations that are created from templates can be edited beforehand.
Renewing a certificate Renewing a certificate
---------------------- ----------------------
Certificates are renewed using `ca-renew-cert(1)`. This script currently does Certificates are renewed using **ca-renew-cert**(1). This script currently
some painful certificate manipulation that is not strictly necessary in most does some painful certificate manipulation that is not strictly necessary in
cases, and may in fact decrease SSL security slightly. This is done because 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 the normal renewal process re-generates the certificate signing request and
thus creates a new public/private keypair. If the certificates are used for 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 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. 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 To avoid this, **ca-renew-cert**(1) re-signs the old certificate request with
a new expiry date using the extensions generated when the old certificate was 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 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* option
to `ca-create-cert(1)`. to **ca-create-cert**(1).
As with the certificate creation script the `--type` option is mandatory for 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 **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 path to a certificate. Internally this will be resolved to the correct
information required for certificate renewal. information required for certificate renewal.
@ -121,8 +127,8 @@ 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 the
`--type` option and either the hostname, username or the path to the certificate *--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 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 basic HTML template to serve the CA certificate and CRL with verifiable MD5 and
SHA1 checksums. SHA1 checksums.