upgrade to CAM v2.0

[stack/cam.git] / README

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..0e92373
--- /dev/null
+++ b/README
@@ -0,0 +1,67 @@
+
+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
+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
+and renew them.
+
+
+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 `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.
+
+Certificates are intentified by a ''tag'', (the section name), so for
+example given the following configuration snippet::
+
+    [web]
+    cn = www.domain.org
+
+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::
+
+    $ cam --config=my.config files web
+    /your/ca/dir/public/certs/web.pem
+    /your/ca/dir/private/web.key
+
+
+Installation
+------------
+
+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`::
+
+    $ virtualenv --no-site-packages /secure/cam
+    $ virtualenv --relocatable /secure/cam
+    $ (cd /tmp ; git clone http://git.autistici.org/cam.git \
+       && /secure/cam/bin/python setup.py install)
+
+Then you can simply mount your encrypted image wherever there is a
+Python interpreter available (well, with the same architecture/OS too)
+and run::
+
+    $ /secure/cam/bin/cam --config=/secure/ca/my.config ...
+
+