Documentation: Automated Bcfg2 SSL Authentication.

1 files changed, 127 insertions, 1 deletions

diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt
index c91905d78..503c68be0 100644
--- a/doc/server/plugins/generators/sslca.txt
+++ b/doc/server/plugins/generators/sslca.txt
@@ -48,7 +48,8 @@ must contain full (not relative) paths.
 #. Add an entry ``chaincert`` that points to the location of your ssl chaining
    certificate.  This is used when preexisting certifcate hostfiles are found, so
    that they can be validated and only regenerated if they no longer meet the
-   specification.
+   specification. If you're using a self signing CA this would be the CA cert
+   that you generated.
 
 #. Once all this is done, you should have a section in your ``/etc/bcfg2.conf``
    that looks similar to the following::
@@ -94,6 +95,131 @@ must contain full (not relative) paths.
    attribute. ie. ca="default" will match [sslca_default] in your
    ``/etc/bcfg2.conf``
 
+Automated Bcfg2 SSL Authentication
+==================================
+
+This section describes one possible scenario for automating ssl certificate generation and distribution for bcfg2 client/server communication using SSLCA. The process involves configuring a certificate authority (CA), generating the CA cert and key pair, configuring the bcfg2 SSLCA plugin and a Bundle to use the SSLCA generated certs to authenticate the bcfg2 client and server.
+
+OpenSSL CA
+----------
+
+If you already have an SSL CA available you can skip this section, otherwise you can easily build one on the server using openssl. The paths should be adjusted to suite your preferences.
+
+#. Prepare the directories and files. ::
+
+    mkdir -p /etc/pki/CA/newcerts
+    mkdir /etc/pki/CA/crl
+    echo '01' > /etc/pki/CA/serial
+    touch /etc/pki/CA/index.txt
+    touch /etc/pki/CA/crlnumber
+
+#. Edit the ``openssl.cnf`` config file, and in the **[ CA_default ]** section adjust the following parameters. ::
+
+    dir         = /etc/pki          # Where everything is kept
+    certs       = /etc/pki/CA/certs     # Where the issued certs are kept
+    database    = /etc/pki/CA/index.txt # database index file.
+    new_certs_dir   = /etc/pki/CA/newcerts      # default place for new certs.
+    certificate = /etc/pki/CA/certs/bcfg2ca.crt     # The CA certificate
+    serial      = /etc/pki/CA/serial        # The current serial number
+    crl_dir     = /etc/pki/CA/crl           # Where the issued crl are kept
+    crlnumber   = /etc/pki/CA/crlnumber # the current crl number
+    crl     = /etc/pki/CA/crl.pem       # The current CRL
+    private_key = /etc/pki/CA/private/bcfg2ca.key # The private key
+
+#. Create the CA root certificate and key pair. You'll be asked to supply a passphrase, and some organizational info. The most important bit is **Common Name** which you should set to be the hostname of your bcfg2 server that your clients will see when doing a reverse DNS query on it's ip address. ::
+
+    openssl req -new -x509 -extensions v3_ca -keyout bcfg2ca.key -out bcfg2ca.crt -days 3650
+
+#. Move the generated cert and key to the locations specified in ``openssl.cnf``. ::
+
+    mv bcfg2ca.key /etc/pki/CA/private/
+    mv bcfg2ca.crt /etc/pki/CA/certs/
+
+Your self-signing CA is now ready to use. 
+
+Bcfg2
+-----
+
+SSLCA
+^^^^^
+
+The SSLCA plugin was not designed specifically to manage bcfg2 client/server communication though it is certainly able to provide certificate generation and management services for that purpose. You'll need to configure the **SSLCA** plugin to serve the key, and certificate paths that we will define later in our client's ``bcfg2.conf`` file.
+
+The rest of these instructions will assume that you've configured the **SSLCA** plugin as described above and that the files ``SSLCA/etc/pki/tls/certs/bcfg2client.crt/cert.xml`` and ``SSLCA/etc/pki/tls/private/bcfg2client.key/key.xml`` represent the cert and key paths you want generated for SSL auth.
+
+Client Bundle
+^^^^^^^^^^^^^
+
+To automate the process of generating and distributing certs to the clients we need define at least the Cert and Key paths served by the SSLCA plugin, as well as the ca certificate path in a Bundle. For example:
+
+    .. code-block:: xml
+
+        <Path name='/etc/pki/tls/certs/bcfg2ca.crt'/>
+        <Path name='/etc/pki/tls/bcfg2client.crt'/>
+        <Path name='/etc/pki/tls/private/bcfg2client.key'/>
+
+Here's a more complete example bcfg2-client bundle: 
+
+    .. code-block:: xml
+
+        <Bundle name='bcfg2-client'>
+           <Path name='/etc/bcfg2.conf'/>
+           <Path name='/etc/cron.d/bcfg2-client'/>
+           <Package name='bcfg2'/>
+           <Service name='bcfg2'/>
+           <Group name='rpm'>
+               <Path name='/etc/sysconfig/bcfg2'/>
+               <Path name='/etc/pki/tls/certs/bcfg2ca.crt' altsrc='/etc/ssl/certs/bcfg2ca.crt'/>
+               <Path name='/etc/pki/tls/certs/bcfg2client.crt' altsrc='/etc/ssl/certs/bcfg2client.crt' />
+               <Path name='/etc/pki/tls/private/bcfg2client.key' altsrc='/etc/ssl/private/bcfg2client.key'/>
+           </Group>
+           <Group name='deb'>
+               <Path name='/etc/default/bcfg2' altsrc='/etc/sysconfig/bcfg2'/>
+               <Path name='/etc/ssl/certs/bcfg2ca.crt' altsrc='/etc/pki/tls/certs/bcfg2ca.crt'/>
+               <Path name='/etc/ssl/certs/bcfg2client.crt' altsrc='/etc/pki/tls/certs/bcfg2client.crt'/>
+               <Path name='/etc/ssl/private/bcfg2client.key' altsrc='/etc/pki/tls/private/bcfg2client.key'/>
+           </Group>
+        </Bundle>
+
+In the above example we told Bcfg2 that it also needs to serve ``/etc/bcfg2.conf``. This is optional but convenient. 
+
+The ``bcfg2.conf`` client config needs at least 5 parameters set for SSL auth. 
+
+#. ``key`` : This is the host specific key that SSLCA will generate. 
+#. ``certificate`` : This is the host specific cert that SSLCA will generate.
+#. ``ca`` : This is a copy of you CA certificate. Not generated by SSLCA.
+#. ``user`` : Usually set to fqdn of client. This *shouldn't* be required but is as of 1.2rc2. see: http://trac.mcs.anl.gov/projects/bcfg2/ticket/1019 
+#. ``password`` : Set to arbitrary string when using certificate auth. This also *shouldn't* be required. see: http://trac.mcs.anl.gov/projects/bcfg2/ticket/1019 
+
+Here's what a functional **[communication]** section in a ``bcfg2.conf`` genshi template for clients might look like.::
+
+   [communication]
+   protocol = xmlrpc/ssl
+   {% if metadata.uuid != None %}\
+   user = ${metadata.uuid}
+   {% end %}\
+   password = DUMMYPASSWORDFORCERTAUTH
+   {% choose %}\
+   {% when 'rpm' in metadata.groups %}\
+   certificate = /etc/pki/tls/certs/bcfg2client.crt
+   key = /etc/pki/tls/private/bcfg2client.key
+   ca = /etc/pki/tls/certs/bcfg2ca.crt
+   {% end %}\
+   {% when 'deb' in metadata.groups %}\
+   certificate = /etc/ssl/certs/bcfg2client.crt
+   key = /etc/ssl/private/bcfg2client.key
+   ca = /etc/ssl/certs/bcfg2ca.crt
+   {% end %}\
+   {% end %}\
+
+As a client will not be able to authenticate with certificates it does not yet posses we need to overcome the chicken and egg scenario the first time we try to connect such a client to the server. We can do so using password based auth to boot strap the client manually specifying all the relevant auth parameters like so:
+
+   bcfg2 -qv -S https://fqdn.of.bcfg2-server:6789 -u fqdn.of.client -x SUPER_SECRET_PASSWORD
+
+If all goes well the client should recieve a freshly generated key and cert and you should be able to run ``bcfg2`` again without specifying the connection parameters.
+
+If you do run into problems you may want to review :ref:`appendix-guides-authentication`
+
 TODO
 ====