Some re-wording and formatting fixes for README.md
This commit is contained in:
Alex Bramley
parent
a8ae2ea085
commit
58aa925513
1 changed files with 40 additions and 34 deletions
74
README.md
74
README.md
|
|
@ -30,7 +30,7 @@ alternative location.
|
|||
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
|
||||
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.
|
||||
|
|
@ -40,14 +40,14 @@ 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.
|
||||
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
|
||||
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 an
|
||||
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.
|
||||
|
|
@ -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
|
||||
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.
|
||||
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)
|
||||
* [**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
|
||||
----------------------
|
||||
|
||||
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
|
||||
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.
|
||||
these different certificate types, details can be found in the documentation
|
||||
for **ca-create-cert**(1).
|
||||
|
||||
`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
|
||||
**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
|
||||
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 *--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
|
||||
**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.
|
||||
|
|
@ -95,25 +101,25 @@ 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
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
|
|
@ -121,8 +127,8 @@ 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
|
||||
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