This directory contains scripts for setting up and operating a Public Key
Infrastructure (PKI) based on the OpenSSL utility.

(c) 2013 - 2014 by Guenther Brunthaler.
These scripts are free software.
Distribution is permitted under the terms of the GPLv3.

There are sub-directories containing scripts and configuration files for
different purposes:

* ca: Create a CA.

* client: Create client certificates signed by the CA.

* server: Create server certificates signed by the CA.

There is a single script *.sh in each of the directories for implementing the
job.

There is also a single file *.info which contains parameters such as company
name or country etc. required by the script.

The *.info files contain already example data which can already be used to
create all required certificates.

However, they should be edited to ensure the parameters match your actual
server/client/country etc. settings.

In order to avoid duplication, the C preprocessor is run over the *.info files
and #include-directives as well as C macros can be used to include shared text
snippets from any file within the "shared" subdirectory. There is also a file
examples.info there which contains examples of the settings available for the
*.info files.

The following macros will be predefined when running the preprocessor:

* SERIAL_NUMBER expands to the current serial number of the certificate to be
created.

* SUBTYPE expands either to nothing or to the argument passed as the first
argument of the script. This can be used to specify a specific client's name
for the certificate without the need to create a different *.info file for
every client.

A file last_serial.txt is maintained by the scripts within each directory and
contains the serial number of the last certificate created there. If there is
no such file, a file with contents "00000" is assumed as default.

The number of decimal digits in last_serial.txt affects the generated file
names. Edit the serial number file to add or remove leading "0" digits in
order to set a different length for the serial number substring within file
names.

The general approach is as follows:

* Generate a single CA.

* Generate as many server and client certificates as required. All will be
signed by the CA generated before.

* The only difference between client and server certificates is the intended
use. They are otherwise identical.

* Ship the certificate of the CA to all the client computers which need to
verify that the server is trustworthy.

* Ship the CA certificate also to any server computers which need to
authenticate clients via client certificates.

* Never ever ship the CA's private key to anyone! It needs to be kept secret.

* Ensure the certificates shipped to the client or server computers cannot be
modified before they reach the destination computers. An easy way to do this
is deployment via SSH. Another way is sending them unencrypted via e-mail, but
use digital signatures. The certificates are not secret - but it must be
ensured they cannot maliciously be modified during transit without detection.

The public certificates and private keys generated by the scripts have
self-descriptive names.

Obviously, the private keys must be kept secret, while the public certificates
should be published or shipped to other computers.

The generated certificate and private key files contain the serial number as
part of their name which should make them distinct. However, a symlink to a
file name with the serial number stripped will also be created. This symlink
will therefore always refer to the most recently created certificate of the
same kind.

The server and client generation scripts accept also a single argument which
should be the server's or client's mnemonic name. In this case, the generated
files will contain the provided name as part of the file names, therefore
eliminating the requirement to manually rename the files after creation in
order to avoid overwriting them when generating the next server/client.