From d82b2c9aa2275802b87bb9a8e2cda66d6e23538b Mon Sep 17 00:00:00 2001 From: ale Date: Sat, 27 Sep 2014 10:23:57 +0100 Subject: [PATCH 1/1] extend the documentation a bit --- README.rst | 163 ++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 143 insertions(+), 20 deletions(-) diff --git a/README.rst b/README.rst index 26a88f4..8ea21cc 100644 --- a/README.rst +++ b/README.rst @@ -1,34 +1,48 @@ +===================================================== cam - minimal X509 Certification Authority management ===================================================== -`cam` is a tiny Python program that can be used to manage a X509 -certification authority for a small organization. It can only create -server certificates, so this is not going to be useful to manage an +``cam`` is a tiny Python program that can be used to manage a X509 +Certification Authority for a small organization. It can only create +server certificates, so it is not going to be useful to manage an X509-based client authentication infrastructure. The intended usage involves describing the list of certificates to -generate in a configuration file, and using the `cam' tool to create +generate in a configuration file, and using the ``cam`` tool to create and renew them. +Installation +------------ + +``cam`` has few requirements: + +* A moderately recent version of Python 2; +* OpenSSL (>=1.0.0) - specifically, the ``openssl`` binary. + +Once you have downloaded the source code, system-wide installation is +simply a matter of:: + + $ sudo python setup.py install + + Configuration ------------- -The configuration file uses INI-like syntax, consisting of a number of -sections. There are two special sections: `ca` and `global`, any other -section is interpreted as a certificate definition. +The configuration file uses a standard INI-like syntax, consisting of +a number of sections. There are two special sections: ``ca`` and +``global``, any other section is interpreted as a certificate +definition. -The `ca` section contains the attributes of the CA itself, see the +The ``ca`` section contains the attributes of the CA itself, see the example configuration file to see which attributes are supported. -The `global` section contains configuration parameters for `cam`. The -only configuration parameter supported is `root_dir`, which is where all -the CA private data will be stored. If you leave this parameter empty, -or if you don't define a `global` section at all, this will default to -the directory containing the configuration file. +The ``global`` section contains configuration parameters for ``cam``. +The only configuration parameter supported is ``root_dir``, which is +where all the CA private data will be stored. -Certificates are intentified by a ''tag'', (the section name), so for +Certificates are identified by a *tag* (the section name), so for example given the following configuration snippet:: [web] @@ -38,20 +52,129 @@ you would use the following command to generate it:: $ cam --config=my.config gen web -Certificates and private keys are saved within the CA data directory, -you can obtain their path with:: + +Global +++++++ + +The ``global`` section contains options that affect the behavior of +the ``cam`` tool itself. You can usually leave this out altogether. + +Available options: + +``root_dir`` + This is where the CA private data will be stored. If you leave this + parameter empty, or if you don't define a ``global`` section at all, + this will default to the directory containing the configuration file. + + +Certification Authority ++++++++++++++++++++++++ + +The ``ca`` section specifies parameters for the Certification +Authority. Some of these are mandatory as they uniquely identify each +CA. + +The following parameters specify options of the CA certificate itself. +They are only used once, at CA initialization time (when running ``cam +init``). Subsequent changes to these options will be ignored. + +``cn`` + Value of the Common Name (CN) field in the X509 Subject. + +``org`` + Value of the Organization (O) field in the X509 Subject. + +``country`` + Value of the Country (C) field in the X509 Subject. + +``email`` + Contact email, added to the X509 CA certificate. + +``days`` + Number of days that the CA certificate will be valid for (default: + 3650, or 10 years). + +``crl_url`` + Public URL where the CA Certificate Revocation List will be + accessible (optional). + +Other options: + +``default_days`` + Number of days that a new certificate will be valid for (default: 365). + +``bits`` + Size of the RSA key for the CA certificate, and also default key + size for all newly created certificates (default: 2048). + +``signature_algorithm`` + Digest algorithm to use for CA signatures (default: sha256). + + +Certificates +++++++++++++ + +Every other section defines options for a certificate. Some of these +options can be left unset, in which case a default value will be +provided by the ``ca`` section. ``cn`` must be always specified. + +The following options are available: + +``days`` + Number of days that this certificate will be valid for. If unset, + will use ``ca.default_days``. + +``cn`` + Common Name (CN) for the X509 Subject. + +``ou`` + Organizational Unit (OU) for the X509 Subject (optional). + +``alt_names`` + Space-separated list of alternate names for this certificate. These + will be encoded as DNS entries in the certificate's X509v3 Subject + Alternative Name field. + + +Usage +----- + +Once you have created a configuration file, initialize the CA by +running:: + + $ cam --config=my.config init + +This will create the CA certificate and private key, and it will ask +you to set a passphrase for the key. Pick something secure. + +Once this is done, you will be able to generate the certificates +described in the configuration using the ``cam gen`` command. For +example, if the configuration defines a certificate with a tag of +``web``:: + + $ cam --config=my.config gen web + +The tool will ask you for the CA passphrase, and it will create a +certificate and a private key in the CA private data directory. You +can obtain their path with:: $ cam --config=my.config files web /your/ca/dir/public/certs/web.pem /your/ca/dir/private/web.key +At any time you can inspect the status of the configured certificates +(and see which ones are about to expire) using the ``cam list`` +command:: -Installation ------------- + $ cam --config=my.config list + + +Standalone Install +------------------ The CA private keys are very sensitive information, so you'll want to -store them in some encrypted removable storage. You can bundle the `cam` -application itself with the CA data by using `virtualenv`:: +store them in some encrypted removable storage. You can bundle the +``cam`` application itself with the CA data by using ``virtualenv``:: $ virtualenv --no-site-packages /secure/cam $ virtualenv --relocatable /secure/cam -- 2.20.1