1 files changed, 129 insertions, 0 deletions
diff --git a/doc/authentication.txt b/doc/authentication.txt
new file mode 100644
index 000000000..aa741903d
--- /dev/null
+++ b/doc/authentication.txt
@@ -0,0 +1,129 @@
+.. -*- mode: rst -*-
+
+==============
+Authentication
+==============
+
+Scenarios
+=========
+
+1. Cluster nodes that are frequently rebuilt
+
+   Default settings work well; machines do not float, and a per-client
+   password is not required.
+
+2. :doc:`NAT_HOWTO`
+
+ * Build client records in advance with bcfg2-admin, setting a uuid
+   for each new client.
+
+ * Set the address attribute for each to the address of the NAT.
+
+ * Optionally, set a per-client password for each, and set into secure
+   mode.
+
+   .. note::
+
+      This will require the use of the uuid and password from each
+      client, and will require that they come through the NAT address.
+
+Building bcfg2.conf automatically
+=================================
+
+This is a TCheetah template that automatically constructs per-client
+bcfg2.conf from the per-client metadata::
+
+    [communication]
+    protocol = xmlrpc/ssl
+    #if $self.metadata.uuid != None
+    user = $self.metadata.uuid
+    #endif
+    #if $self.metadata.password != None
+    password = $self.metadata.password
+    #else
+    password = my-password-foobat
+    #endif
+    fingerprint = d8b7423da5d8ccd0f3db29742fc8eed00b9d0848
+
+    [components]
+    bcfg2 = https://localhost:6789
+
+In this setup, this will cause any clients that have uuids established
+to be set to use them in bcfg2.conf. It will also cause any clients
+with passwords set to use them instead of the global password. The
+fingerprint needs to be manually set, per-server, using the output of
+"bcfg2-admin fingerprint".
+
+How Authentication Works
+========================
+
+#. First, the client is associated with a client record. If the client
+   specifies a uuid, it uses this instead of the results of a dns or
+   address lookup.
+
+#. Next, the ip address is verified against the client record. If the
+   address doesn't match, then the client must be set to
+   location=floating
+
+#. Finally, the password is verified. If the client is set to secure
+   mode, the only its per-client password is accepted. If it is not set
+   to secure mode, then either the global password or per-client password
+   will be accepted
+
+Failure during any of these stages results in authentication
+failure. Note that clients set into secure mode that do not have
+per-client passwords set will not be able to connect.
+
+SSL Cert-based client authentication
+====================================
+
+As of 1.0pre3, SSL-based client authentication is supported. This
+requires several things:
+
+#. Certificate Authority (to sign all keys)
+
+#. Server key and cert signed by the CA
+
+#. Client key and cert signed by the CA
+
+A variety of CAs can be used, but these keys can be simply generated
+using the following set of steps:
+
+#. Setup a CA
+
+   http://www.flatmtn.com/article/setting-openssl-create-certificates
+
+#. Create keys for each client and server, signing them with the CA
+   signing cert
+
+   http://www.flatmtn.com/article/setting-ssl-certificates-apache
+
+#. Distribute the keys and certs to the appropriate locations
+
+#. Copy the ca cert to clients, so that the server can be authenticated
+
+Clients authenticating themselves with a certificate will be
+authenticated that way first; clients can be setup to either
+authenticate solely with certs, use certs with a fallback to password,
+or password only. Also a bootstrap mode will be added shortly; this
+will allow a client to authenticate with a password its first time,
+requiring a certificate all subsequent times. This behavior can be
+controlled through the use of the auth attribute in
+Metadata/clients.xml::
+
+    <Clients>
+      <Client name='testclient' auth='cert'/>
+    </Clients>
+
+Allowed values are:
+
+    +---------------+------------------------------------------+
+    | **Auth Type** | **Meaning**                              |
+    +---------------+------------------------------------------+
+    | cert          | Certificates must be used                |
+    +---------------+------------------------------------------+
+    | cert+password | Certificate or password may be used      |
+    +---------------+------------------------------------------+
+    | bootstrap     | Password can be used for one client run, |
+    |               | after that certificate is required       |
+    +---------------+------------------------------------------+