diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/server/plugins/generators/sslca.txt | 96 |
1 files changed, 96 insertions, 0 deletions
diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt new file mode 100644 index 000000000..118a16559 --- /dev/null +++ b/doc/server/plugins/generators/sslca.txt @@ -0,0 +1,96 @@ +.. -*- mode: rst -*- + +.. _server-plugins-generators-sslca: + +===== +SSLCA +===== + +SSLCA is a generator plugin designed to handle creation of SSL private keys +and certificates on request. + +Borrowing ideas from the TGenshi and SSHbase plugins, SSLCA automates the +generation of SSL certificates by allowing you to specify key and certificate +definitions. Then, when a client requests a Path that contains such a +definition within the SSLCA repository, the matching key/cert is generated, and +stored in a hostfile in the repo so that subsequent requests do not result in +repeated key/cert recreation. In the event that a new key or cert is needed, +the offending hostfile can simply be removed from the repository, and the next +time that host checks in, a new file will be created. If that file happens to +be the key, any dependent certificates will also be regenerated. + +Getting started +=============== + +In order to use SSLCA, you must first have at least one CA configured on +your system. For details on setting up your own OpenSSL based CA, please +see http://www.openssl.org/docs/apps/ca.html for details of the suggested +directory layout and configuration directives. + +For SSLCA to work, the openssl.cnf (or other configuration file) for that CA +must contain full (not relative) paths. + +#. Add SSLCA to the **plugins** line in ``/etc/bcfg2.conf`` and restart the + server -- This enabled the SSLCA plugin on the Bcfg2 server. + +#. Add a section to your ``/etc/bcfg2.conf`` called sslca_foo, replacing foo +with the name you wish to give your CA so you can reference it in certificate +definitions. + +#. Under that section, add an entry for ``config`` that gives the location of +the openssl configuration file for your CA. + +#. If necessary, add an entry for ``passphrase`` containing the passphrase for +the CA's private key. We store this in ``/etc/bcfg2.conf`` as the permissions +on that file should have it only readable by the bcfg2 user. If no passphrase +is entry exists, it is assumed that the private key is stored unencrypted. + +#. 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. + +#. Once all this is done, you should have a section in your ``/etc/bcfg2.conf`` +that looks similar to the following: + + [sslca_default] + config = /etc/pki/CA/openssl.cnf + passphrase = youReallyThinkIdShareThis? + chaincert = /etc/pki/CA/chaincert.crt + +#. You are now ready to create key and certificate definitions. For this +example we'll assume you've added Path entries for the key, +``/etc/pki/tls/private/localhost.key``, and the certificate, +``/etc/pki/tls/certs/localhost.crt`` to a bundle or base. + +#. Defining a key or certificate is similar to defining a TGenshi template. +Under your Bcfg2's SSLCA directory, create the directory structure to match the +path to your key. In this case this would be something like +``/var/lib/bcfg2/SSLCA/etc/pki/tls/private/localhost.key``. + +#. Within that directory, create a ``key.xml`` file containing the following: + + <KeyInfo> + <Key type="rsa" bits="2048" /> + </KeyInfo> + +#. This will cause the generation of an 2048 bit RSA key when a client requests +that Path. Alternatively you can specify ``dsa`` as the keytype, or a different +number of bits. + +#. Similarly, create the matching directory structure for the certificate path, +and a ``cert.xml`` containinng the following: + + <CertInfo> + <Cert format="pem" key="/etc/pki/tls/private/localhost.key" ca="default" days="365" c="US" l="New York" st="New York" o="Your Company Name" /> + </CertInfo> + +#. When a client requests the cert path, a certificate will be generated using +the key hostfile at the specified key location, using the CA matching the ca +attribute. ie. ca="default" will match [sslca_default] in your +``/etc/bcfg2.conf`` + +TODO +==== + +#. Add generation of pkcs12 format certs |