README.rst

   1
   2 =====================================================
   3 cam - minimal X509 Certification Authority management
   4 =====================================================
   5
   6 ``cam`` is a tiny Python program that can be used to manage a X509
   7 Certification Authority for a small organization. It can only create
   8 server certificates, so it is not going to be useful to manage an
   9 X509-based client authentication infrastructure.
  10
  11 The intended usage involves describing the list of certificates to
  12 generate in a configuration file, and using the ``cam`` tool to create
  13 and renew them.
  14
  15
  16 Installation
  17 ------------
  18
  19 ``cam`` has few requirements:
  20
  21 * A moderately recent version of Python 2;
  22 * OpenSSL (>=1.0.0) - specifically, the ``openssl`` binary.
  23
  24 Once you have downloaded the source code, system-wide installation is
  25 simply a matter of::
  26
  27     $ sudo python setup.py install
  28
  29
  30 Configuration
  31 -------------
  32
  33 The configuration file uses a standard INI-like syntax, consisting of
  34 a number of sections. There are two special sections: ``ca`` and
  35 ``global``, any other section is interpreted as a certificate
  36 definition.
  37
  38 The ``ca`` section contains the attributes of the CA itself, see the
  39 example configuration file to see which attributes are supported.
  40
  41 The ``global`` section contains configuration parameters for ``cam``.
  42 The only configuration parameter supported is ``root_dir``, which is
  43 where all the CA private data will be stored.
  44
  45 Certificates are identified by a *tag* (the section name), so for
  46 example given the following configuration snippet::
  47
  48     [web]
  49     cn = www.domain.org
  50
  51 you would use the following command to generate it::
  52
  53     $ cam --config=my.config gen web
  54
  55
  56 Global
  57 ++++++
  58
  59 The ``global`` section contains options that affect the behavior of
  60 the ``cam`` tool itself. You can usually leave this out altogether.
  61
  62 Available options:
  63
  64 ``root_dir``
  65   This is where the CA private data will be stored. If you leave this
  66   parameter empty, or if you don't define a ``global`` section at all,
  67   this will default to the directory containing the configuration file.
  68
  69
  70 Certification Authority
  71 +++++++++++++++++++++++
  72
  73 The ``ca`` section specifies parameters for the Certification
  74 Authority. Some of these are mandatory as they uniquely identify each
  75 CA.
  76
  77 The following parameters specify options of the CA certificate itself.
  78 They are only used once, at CA initialization time (when running ``cam
  79 init``). Subsequent changes to these options will be ignored.
  80
  81 ``cn``
  82   Value of the Common Name (CN) field in the X509 Subject.
  83
  84 ``org``
  85   Value of the Organization (O) field in the X509 Subject.
  86
  87 ``country``
  88   Value of the Country (C) field in the X509 Subject.
  89
  90 ``email``
  91   Contact email, added to the X509 CA certificate.
  92
  93 ``days``
  94   Number of days that the CA certificate will be valid for (default:
  95   3650, or 10 years).
  96
  97 ``crl_url``
  98   Public URL where the CA Certificate Revocation List will be
  99   accessible (optional).
 100
 101 Other options:
 102
 103 ``default_days``
 104   Number of days that a new certificate will be valid for (default: 365).
 105
 106 ``bits``
 107   Size of the RSA key for the CA certificate, and also default key
 108   size for all newly created certificates (default: 2048).
 109
 110 ``signature_algorithm``
 111   Digest algorithm to use for CA signatures (default: sha256).
 112
 113
 114 Certificates
 115 ++++++++++++
 116
 117 Every other section defines options for a certificate. Some of these
 118 options can be left unset, in which case a default value will be
 119 provided by the ``ca`` section. ``cn`` must be always specified.
 120
 121 The following options are available:
 122
 123 ``days``
 124   Number of days that this certificate will be valid for. If unset,
 125   will use ``ca.default_days``.
 126
 127 ``cn``
 128   Common Name (CN) for the X509 Subject.
 129
 130 ``ou``
 131   Organizational Unit (OU) for the X509 Subject (optional).
 132
 133 ``alt_names``
 134   Space-separated list of alternate names for this certificate. These
 135   will be encoded as DNS entries in the certificate's X509v3 Subject
 136   Alternative Name field.
 137
 138
 139 Usage
 140 -----
 141
 142 Once you have created a configuration file, initialize the CA by
 143 running::
 144
 145     $ cam --config=my.config init
 146
 147 This will create the CA certificate and private key, and it will ask
 148 you to set a passphrase for the key. Pick something secure.
 149
 150 Once this is done, you will be able to generate the certificates
 151 described in the configuration using the ``cam gen`` command. For
 152 example, if the configuration defines a certificate with a tag of
 153 ``web``::
 154
 155     $ cam --config=my.config gen web
 156
 157 The tool will ask you for the CA passphrase, and it will create a
 158 certificate and a private key in the CA private data directory. You
 159 can obtain their path with::
 160
 161     $ cam --config=my.config files web
 162     /your/ca/dir/public/certs/web.pem
 163     /your/ca/dir/private/web.key
 164
 165 At any time you can inspect the status of the configured certificates
 166 (and see which ones are about to expire) using the ``cam list``
 167 command::
 168
 169     $ cam --config=my.config list
 170
 171
 172 Standalone Install
 173 ------------------
 174
 175 The CA private keys are very sensitive information, so you'll want to
 176 store them in some encrypted removable storage. You can bundle the
 177 ``cam`` application itself with the CA data by using ``virtualenv``::
 178
 179     $ virtualenv --no-site-packages /secure/cam
 180     $ virtualenv --relocatable /secure/cam
 181     $ (cd /tmp ; git clone https://git.autistici.org/ai/cam.git \
 182        && /secure/cam/bin/python setup.py install)
 183
 184 Then you can simply mount your encrypted image wherever there is a
 185 Python interpreter available (well, with the same architecture/OS too)
 186 and run::
 187
 188     $ /secure/cam/bin/cam --config=/secure/ca/my.config ...
 189
 190