Benjamin Smee - strerror@disciplina.net
1.00
This HOWTO came about from needing to setup a Certificate Authority for both personal use and work. This HOWTO will guild the reader through configuring OpenCA and tailoring it to their precise needs as well as clarifying the LDAP integration that OpenCA supports (but isn't all that well documented.).
I did some research into the OSS CAs and came up with only two suitable given my requirements which were OpenCA and EJBCA. My requirements were as follows:
While EJBCA seems to be a good product after some research it seemed to me that OpenCA had a better architecture and so I chose it to implement my CAs. Configuring and running CAs is more complex then many other services as the administrator should be aware of all the intracacies of certificate usage and creation, topics which are beyond the scope of this HOWTO, but that are covered in detail elsewhere. With that said OpenCA makes setting up and running a CA really quite simple and if you only read the architecture section of its documentation you should have enough information to setup a CA.
At the time of writing OpenCA has just had a large fork, Openxpki. From how things look at this point in time I think that Openxpki will be the more important branch and I will be aiming to providing ebuilds for Openxpki upon their first major release and deprecating OpenCA.
Using the Gentoo ebuilds that I have written all the dependancies are resolved. Aside from the dependancies that are pulled in during the emerge process all that is really required is a functioning web server which supports CGI usage. An ideal installation of a CA requires more then one machine and ideally one of them should be offline and only brought online for signing the certificate requests with the ROOT CA. However, most implementations are unlikely to have the resources to do that and so this HOWTO will assume that you are going to install all the components of the CA on one machine.
On Gentoo we simply emerge openca, but otherwise we need to compile it from source. Once installed the first step is to modify the /etc/openca/config.xml file. Modifications should be self apparent as the file is well documented. One thing that should be mentioned is that you must use the external DB password that you compiled it with, in our case this can be found (randomly generated) in /usr/share/doc/${PV}/mysql-setup.sql.gz and all that needs to be done is:
to create the database with the relevant user and the right pass for that user.
Once the config.xml has been modified then we must generate all the actual configuration files themselves based off the info in the config.xml. This is done by an included script, configure_etc.sh. Once run this will generate all the configuration files for the different parts of OpenCA. LDAP integration is in theory relatively simple with OpenCA, however, they made the unfortunate choice to use as a default the older style DIT syntax (to be fair it is the X.500 standard its just not in common use in normal LDAP implementations) where the company name and location made up the basedn eg O=Disciplina Networks,l=England,C=UK. This clashes with the setup I want to use which uses the more modern DNS style which is dc=disciplina,dc=net. In order to make OpenCA use the domain based style we need to make a number of manual changes to some configuration files rather then let the configure script extrapolate the DIT based on entries we put in the config.xml. It is important to note that as a general rule whenever you make a change to the config.xml you should rerun the configure_etc.sh script so that ALL the configuration files are in sync with the same information. Unfortunately if we rerun the script we will overwrite the manual changes that we are about to make to some configuration files, so you should backup each of the files we are about to modify AFTER you make the changes so that you can copy them back into place if you need to rerun the configure_etc.sh script again.
Firstly modify /etc/openca/ldap.xml, change the protocol version if required and configure the TLS settings change the suffix to reflect what you want, eg ou=pki, ou=services, dc=disciplina, dc=net
Now we should modify the following files:
modify /etc/opneca/servers/ca.conf, replace the relevant parts with:
DN_TYPE_BASIC_BASE "OU" "OU" "DC" "DC"
DN_TYPE_BASIC_BASE_1 "pki"
DN_TYPE_BASIC_BASE_2 "services"
DN_TYPE_BASIC_BASE_3 "disciplina"
DN_TYPE_BASIC_BASE_4 "uk"
modify /etc/opneca/servers/ra.conf, replace the relevant parts with:
DN_TYPE_IE_BASE "OU" "OU" "DC" "DC"
DN_TYPE_IE_BASE_1 "pki"
DN_TYPE_IE_BASE_2 "services"
DN_TYPE_IE_BASE_3 "disciplina"
DN_TYPE_IE_BASE_4 "net"
NOTE: this file has 2 places where you will need to change the base IE and SPKAC.
modify /etc/opneca/servers/pub.conf, replace the relevant parts with:
DN_TYPE_TOKEN_BASE "OU" "OU" "DC" "DC"
DN_TYPE_TOKEN_BASE_1 "pki"
DN_TYPE_TOKEN_BASE_2 "services"
DN_TYPE_TOKEN_BASE_3 "disciplina"
DN_TYPE_TOKEN_BASE_4 "net"
NOTE: with this file there is more then ONE place that you have to do this for. Make sure that you go through the entire file and change all occurances of the older syntax to the newer format as in the above example.
Once this is done we need to make some changes to /etc/openldap/slapd.conf so that the user we have defined to access the DIT for openca is able to execute the relevant commands.
Changes to slapd.conf:
access to dn.subtree="ou=pki,ou=services,dc=disciplina,dc=net"
by dn="cn=pki,dc=disciplina,dc=net" write
Once the changes are made we need to restart the slapd if we are using openldap 2.2 or lower.
Finally we need to modify our apache setup to allow access to the site. Below is a sample configuration file for a vhost setup:
<VirtualHost 10.10.40.121:443>
ServerAdmin webmaster@disciplina.net
ServerName ca.disciplina.net
DocumentRoot /var/www/localhost/htdocs/openca
ScriptAlias /cgi-bin/ "/var/www/localhost/cgi-bin/"
<Directory "/var/www/localhost/cgi-bin">
AuthType basic
AllowOverride AuthConfig
Options ExecCGI -Indexes FollowSymLinks SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory>
<Directory />
AuthType basic
Options -Indexes FollowSymLinks SymLinksIfOwnerMatch
DirectoryIndex pub/
AllowOverride None
Order allow,deny
Allow from all
</Directory>
ErrorLog /var/log/apache2/ca/error_log
CustomLog /var/log/apache2/ca/access_log combined
SSLEngine on
SSLCertificateFile /etc/ssl/certs/webserver-cert.pem
SSLCertificateKeyFile /etc/ssl/private/webserver-key.pem
SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
</VirtualHost>
Now we simply need to restart apache and then start the openca xml daemon with:
You should now be able to use the OpenCA site.
Sometimes, depending on browsers, you might get an error when trying to access parts of the sites saying "General Error Aborting connection - you are using a too short symmetric keylength ().". This error indicates that there browser that is trying to access the site is unable to support certain advanced cryptographic functions. To get around this, we can remove the restriction by modifying the appropriate /etc/openca/access_control/{ra,ldap,pub}.xml and changing the symetric key length from 128 to 0 for example. You will need to restart the xml engine for this change to take effect via:
/etc/init.d/openca start