From 416162c37c0b30cf42db1b7bd86bf5e15ff61284 Mon Sep 17 00:00:00 2001 From: Graham Hagger Date: Fri, 22 Oct 2010 14:31:09 -0400 Subject: added some docs for sslca --- doc/server/plugins/generators/sslca.txt | 53 +++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 doc/server/plugins/generators/sslca.txt (limited to 'doc') diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt new file mode 100644 index 000000000..17f936ffc --- /dev/null +++ b/doc/server/plugins/generators/sslca.txt @@ -0,0 +1,53 @@ +===== +SSLCA +===== + +SSLCA is a simple generator plugin designed to handle creation of +SSL private keys and certificates on request. + +At present, only the following file locations are supported, and thus +only a single key and certifcate will be generated: + +* /etc/pki/tls/private/localhost.key +* /etc/pki/tls/certs/localhost.crt + +While this could be seen as very limiting, SSLCA does support any aliases +specified in clients.xml. Any aliases will be added to the cert under the +subjectAltName extension. + + +Interacting with SSLCA +====================== + +* Pre-seeding with existing keys/certs -- Currently existing keys/certs + will be overwritten by new, sslca-managed ones by default. Pre-existing + files can be added to the repository by putting them in + /SSLCA/.H_ + +* Revoking existing keys -- deleting /SSLCA/\*.H_ + will remove files for an existing client. + + +Getting started +=============== + +#. Add SSLCA to the **plugins** line in ``/etc/bcfg2.conf`` and + restart the server -- This enables the SSLCA plugin on the Bcfg2 + server. + +#. Add Path entries for ``/etc/pki/tls/private/localhost.key``, and + ``/etc/pky/tls/certs/localhost.crt``, etc to a bundle or base. + +#. Add a [sslca] section to ``/etc/bcfg2.conf`` contaning the following + information: + + ca_cert - location of the CA certificate + ca_key - CA private key + ca_key_passphrase - Passphrase (if any) needed to use the CA private key + cert_subject - Additional subject info for the resulting certificates, CN + will always be the bcfg2 clients hostname. + cert_days - number of days from generation that cert should be valid. + pkey_bits - number of bits for the private key. + +#. Enjoy. + -- cgit v1.2.3-1-g7c22 From df1d94eda634e2f00757af19b70e1abb6b1b98a2 Mon Sep 17 00:00:00 2001 From: Graham Hagger Date: Fri, 22 Oct 2010 15:15:03 -0400 Subject: moved some sslca docs around --- doc/server/plugins/generators/sslca.txt | 43 +++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) (limited to 'doc') diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt index 17f936ffc..cfc01efe1 100644 --- a/doc/server/plugins/generators/sslca.txt +++ b/doc/server/plugins/generators/sslca.txt @@ -51,3 +51,46 @@ Getting started #. Enjoy. + +==== +TODO +==== + +V1.0 - Only handles localhost.key and localhost.crt, therefor +assuming we only care about a cert for www, or all ssl services +will use the same cert + +Initialiazation: +Grab options from bcfg2.conf +load cakey, cacert +cache other options + +Req comes in for key & cert +If key exists: + load key + cache key + return key +Else: + gen key + cache key + save key + return key +If cert exists: + load cert + If fails to verify against key: + gen cert + save cert + return cert + If aliases fail don't match + gen cert + save cert + return cert + return cert +Else: + gen cert + save cert + return cert + +V2.0 - Maybe create additional types, SSLCertPath, SSLKeyPath, +to allow generation of multiple certs/keys in arbitrary locations + -- cgit v1.2.3-1-g7c22 From 17cfe3010f115dfc5294129aaae61660cfbb4896 Mon Sep 17 00:00:00 2001 From: Graham Hagger Date: Fri, 22 Oct 2010 22:39:19 -0400 Subject: added extra todo notes --- doc/server/plugins/generators/sslca.txt | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt index cfc01efe1..5f987be1e 100644 --- a/doc/server/plugins/generators/sslca.txt +++ b/doc/server/plugins/generators/sslca.txt @@ -56,7 +56,14 @@ Getting started TODO ==== -V1.0 - Only handles localhost.key and localhost.crt, therefor +V1.0 - Nearly done... + +...need to add cert expiry checking/regen... + +...otherwise the below is done, but really should be rewritten to +use openssl binary rather than patched m2crypto + +Only handles localhost.key and localhost.crt, therefor assuming we only care about a cert for www, or all ssl services will use the same cert @@ -91,6 +98,8 @@ Else: save cert return cert + + V2.0 - Maybe create additional types, SSLCertPath, SSLKeyPath, to allow generation of multiple certs/keys in arbitrary locations -- cgit v1.2.3-1-g7c22 From d4a8aa409cd3db6143f91809466866e9b088254c Mon Sep 17 00:00:00 2001 From: Graham Hagger Date: Tue, 2 Nov 2010 21:16:36 -0400 Subject: Properly documented the way this _should_ work. Need to make some small changes to the SSLCA plugin itself to make this truly the case. --- doc/server/plugins/generators/sslca.txt | 155 +++++++++++++++----------------- 1 file changed, 73 insertions(+), 82 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt index 5f987be1e..118a16559 100644 --- a/doc/server/plugins/generators/sslca.txt +++ b/doc/server/plugins/generators/sslca.txt @@ -1,105 +1,96 @@ +.. -*- mode: rst -*- + +.. _server-plugins-generators-sslca: + ===== SSLCA ===== -SSLCA is a simple generator plugin designed to handle creation of -SSL private keys and certificates on request. +SSLCA is a generator plugin designed to handle creation of SSL private keys +and certificates on request. -At present, only the following file locations are supported, and thus -only a single key and certifcate will be generated: +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. -* /etc/pki/tls/private/localhost.key -* /etc/pki/tls/certs/localhost.crt +Getting started +=============== -While this could be seen as very limiting, SSLCA does support any aliases -specified in clients.xml. Any aliases will be added to the cert under the -subjectAltName extension. +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. -Interacting with SSLCA -====================== +#. Add SSLCA to the **plugins** line in ``/etc/bcfg2.conf`` and restart the + server -- This enabled the SSLCA plugin on the Bcfg2 server. -* Pre-seeding with existing keys/certs -- Currently existing keys/certs - will be overwritten by new, sslca-managed ones by default. Pre-existing - files can be added to the repository by putting them in - /SSLCA/.H_ +#. 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. -* Revoking existing keys -- deleting /SSLCA/\*.H_ - will remove files for an existing client. +#. 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. -Getting started -=============== +#. 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. -#. Add SSLCA to the **plugins** line in ``/etc/bcfg2.conf`` and - restart the server -- This enables the SSLCA plugin on the Bcfg2 - server. +#. Once all this is done, you should have a section in your ``/etc/bcfg2.conf`` +that looks similar to the following: -#. Add Path entries for ``/etc/pki/tls/private/localhost.key``, and - ``/etc/pky/tls/certs/localhost.crt``, etc to a bundle or base. + [sslca_default] + config = /etc/pki/CA/openssl.cnf + passphrase = youReallyThinkIdShareThis? + chaincert = /etc/pki/CA/chaincert.crt -#. Add a [sslca] section to ``/etc/bcfg2.conf`` contaning the following - information: +#. 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. - ca_cert - location of the CA certificate - ca_key - CA private key - ca_key_passphrase - Passphrase (if any) needed to use the CA private key - cert_subject - Additional subject info for the resulting certificates, CN - will always be the bcfg2 clients hostname. - cert_days - number of days from generation that cert should be valid. - pkey_bits - number of bits for the private key. +#. 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``. -#. Enjoy. +#. Within that directory, create a ``key.xml`` file containing the following: + + + + +#. 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: + + + + + +#. 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 ==== -V1.0 - Nearly done... - -...need to add cert expiry checking/regen... - -...otherwise the below is done, but really should be rewritten to -use openssl binary rather than patched m2crypto - -Only handles localhost.key and localhost.crt, therefor -assuming we only care about a cert for www, or all ssl services -will use the same cert - -Initialiazation: -Grab options from bcfg2.conf -load cakey, cacert -cache other options - -Req comes in for key & cert -If key exists: - load key - cache key - return key -Else: - gen key - cache key - save key - return key -If cert exists: - load cert - If fails to verify against key: - gen cert - save cert - return cert - If aliases fail don't match - gen cert - save cert - return cert - return cert -Else: - gen cert - save cert - return cert - - - -V2.0 - Maybe create additional types, SSLCertPath, SSLKeyPath, -to allow generation of multiple certs/keys in arbitrary locations - +#. Add generation of pkcs12 format certs -- cgit v1.2.3-1-g7c22