README.rst

   1
   2 cam - minimal X509 Certification Authority management
   3 =====================================================
   4
   5 `cam` is a tiny Python program that can be used to manage a X509
   6 certification authority for a small organization. It can only create
   7 server certificates, so this is not going to be useful to manage an
   8 X509-based client authentication infrastructure.
   9
  10 The intended usage involves describing the list of certificates to
  11 generate in a configuration file, and using the `cam' tool to create
  12 and renew them.
  13
  14
  15 Configuration
  16 -------------
  17
  18 The configuration file uses INI-like syntax, consisting of a number of
  19 sections. There are two special sections: `ca` and `global`, any other
  20 section is interpreted as a certificate definition.
  21
  22 The `ca` section contains the attributes of the CA itself, see the
  23 example configuration file to see which attributes are supported.
  24
  25 The `global` section contains configuration parameters for `cam`. The
  26 only configuration parameter supported is `root_dir`, which is where all
  27 the CA private data will be stored. If you leave this parameter empty,
  28 or if you don't define a `global` section at all, this will default to
  29 the directory containing the configuration file.
  30
  31 Certificates are intentified by a ''tag'', (the section name), so for
  32 example given the following configuration snippet::
  33
  34     [web]
  35     cn = www.domain.org
  36
  37 you would use the following command to generate it::
  38
  39     $ cam --config=my.config gen web
  40
  41 Certificates and private keys are saved within the CA data directory,
  42 you can obtain their path with::
  43
  44     $ cam --config=my.config files web
  45     /your/ca/dir/public/certs/web.pem
  46     /your/ca/dir/private/web.key
  47
  48
  49 Installation
  50 ------------
  51
  52 The CA private keys are very sensitive information, so you'll want to
  53 store them in some encrypted removable storage. You can bundle the `cam`
  54 application itself with the CA data by using `virtualenv`::
  55
  56     $ virtualenv --no-site-packages /secure/cam
  57     $ virtualenv --relocatable /secure/cam
  58     $ (cd /tmp ; git clone https://git.autistici.org/ai/cam.git \
  59        && /secure/cam/bin/python setup.py install)
  60
  61 Then you can simply mount your encrypted image wherever there is a
  62 Python interpreter available (well, with the same architecture/OS too)
  63 and run::
  64
  65     $ /secure/cam/bin/cam --config=/secure/ca/my.config ...
  66
  67