give README a proper file extension so that it renders correctly
[stack/cam.git] / 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