4. config.xml (for RPMs and DEBs too)

After the installation all necessary files are in the correct directories but there are hunderts of files called *.template. These files contain placeholders which can be configured in OPENCADIR/etc/config.xml. Before you start using OpenCA check this file and run OPENCADIR/etc/configure_etc.sh.

OPENCADIR/etc/configure_etc.sh loads OPENCADIR/etc/config.xml and creates the correct files. If you use packages from distribution then OPENCADIR is usually empty because they create a directory /etc/openca.

config.xml contains seven big sections which will be described first. Second we describe how to setup an installation with only one common area but two management interfaces. This is useful if you want to test the dataexchange.

4.1. Configuration sections of config.xml

4.1.1. General options

Here you have to define some options which are relevant for several interfaces. The ca locality, organization and country affects the distinguished name and the preconfiguration of the LDAP stuff. Nevertheless you should read the LDAP section too. The values which you enter are directly used for l, o and c.

The mailpart is used for the node and RA interface. The sendmail field defines the command which will be used to send mails. You must have a mailprogram with a sendmail interface (e.g. postfix). You can enter every program which works like sendmail -n. There are several people which like postfix more than sendmail and we don't like do decide which mailprogram is the best one. The option send_mail_automatic configures the node interface. If the value is YES then OpenCA sends all incoming mails during an import automatically. This can be nice but it is dangerous too if you make a mistake. The service_mail_account is used as From for all sended mails. Usually this should be something like . You can replace > by > to but this is not required by the XML specification.

The last option policy_link defines a link to your policy. It is highly recommended to don't ignore this value. If you have such a reference then you can modify the page request_success.html (add a hint) and the users can read all about the PKI at every time they want. If you have no such link then you receive dozens questions which are really simple but cost a lot of time and you have no base for your operations. Ok, I think I have not to explain the advantages of a policy here ...

4.1.2. web server configuration

Sometimes you need to run a CA on really unusual ports or you have to use https. It is also a little bit difficult for us to guess your correct hostname. Therefore you can specify these parameters in config.xml. The httpd_port should be the default port of the protocol and in this case it can be empty. If you need to run for example a http server on port 8080 then you have to use the option. Please remember to set the colons if you specify a port.

CRL distribution points (CDPs) can be specified extra. This is necessary because there are softwares which has problems with https in general or other softwares which try to download a CRL and before they start the download they want to check the CRL of the webserver but the CRL is not present (or why should somebody tries to download it :) ) and so an endless loop starts - Microsoft CAPI is such a software.

If you setup a real CA then it is highly recommended to edit all files in OPENCADIR/etc/openssl/extfiles and OPENCADIR/etc/openssl.cnf too. Every certificate should contain at minimum two CDPs. It is best practice to have two http CDPs and two ldap CDPs. Such a solution allows fast migration and a good reliability.

4.1.3. ldap server configuration

Before you start working with OpenCA's LDAP code please be sure that your LDAP server knows the objectclasses pkiUser, pkiCA and uniquelyIdentifiedUser. The last objectclass was introduced by Entrust Technolgies to have a clean way to include serialnumbers into the subject of the certificate. Yes, it is proprietary but there is no other way to do it.

The following list is identical with the listof the list in the tech guide where you can find more informations about OpenCA's LDAP code and how to configure the details in the configuration files.

useLDAP

If you set this option to "yes" then the LDAP code will be activated.

update_ldap_automatic

If you want that the LDAP server will be updated during the import from a higher level of the hierarchy then you must set this option to YES.

ldap_host

This is the hostname of your LDAP server.

ldap_port

This is the port where your LDAP server listens.

ldaproot

The bind DN of the user which OpenCA uses to add data to the server.

ldaprootpwd

The passphrase for OpenCA's ldap account.

4.1.4. database configuration

First you have to decide which database module you want to use. OpenCA supports two modules - one for DBM files and one for SQL databases. DB activates support for DBM files and DBI activates the SQL support.

If you want to use SQL databases then you have to setup some additional parameters:

db_type

This is the type of the DBD driver. We support Pg, MySQL, Oracle and DB2. If you need support for another database then please contact us.

db_name

name of the database which OpenCA should use

db_host

host of the database but sometimes the drivers don't need the host.

db_port

same as for host

db_user

the database user for OpenCA

db_passwd

has not to be explained :)

4.1.5. module configuration

OpenCA has a mechanism to isolate the different interfaces from eachother to avoid conflicts especially double serialnumbers. The module_shift is the number of bits reserved for the IDs. You can use IDs from 0 to (2^module_shift - 1). 0 is the ID of the CA. All the other _module_ids must be in the scope of the module shift. Please be careful you cannot change the module_shift after the first definition.

4.1.6. configuration of relative paths

The _url_prefix options define the exact positions in the webserver. This depends highly on the positions of the files in the filesystem but you can configure aliases in the httpd.conf. So OpenCA is fully flexible.

4.1.7. configuration of SCEP

SCEP is really simple to configure but please don't forget the access control configuration. It is strongly recommended to restrict the source addresses which can access the SCEP server.

SCEP_RA_KEY

This is the PEM encoded private key of the SCEP interface. It has the same format like for mod_ssl.

SCEP_RA_CERT

This is the PEM encoded certificate of the SCEP interface. It has the same format like for mod_ssl.

SCEP_RA_PASSWD

This is the passphrase for the private key of the SCEP server. If you use a not encrypted private key (what is not recommended - then please set an empty string here. interface. It has the same format like for mod_ssl.

4.1.8. Dataexchange

The configuration of the dataexchange is really complex in OpenCA. You can find a description in the section about the configuration of the dataexchange (see Section 9, “Dataexchange”). If it is your first OpenCA installation then please use one of the templates. If you setup a production level PKI then you must understand this configuration before you use it. This is one of the most important configuration options to guarantee the security of the PKI.

4.2. How to setup two management interfaces on one server?

Before the explanations start please notice that it is important to first install the online components and then the offline components if you follow the instructions because the configuration of the offline components take care about the already configured online components.

Additonally please remember to set the configure option --with-node-prefix to different names during the configuration of the online and offline installation. This is important because otherwise you have only one management interface.

4.2.1. Online Components

The first installation uses only the normal steps - ./configure --with-node-prefix=online_node --with-your-options, make, make test, make install-online, edit OPENCADIR/etc/config.xml and OPENCADIR/etc/configure_etc.sh. Please use your options to configure the software and use the hierarchy level ra.

4.2.2. Offline Components

The first step is the protection of the already installed configuration files. Please set no permissions to the later needed configuration files in OPENCADIR/etc/servers.

chmod 000 etc/servers/*.conf*

The first four steps are the same as for the online components except of the configuration options where you should change at minimum the hierarchy level to CA. So first you do ./configure --with-node-prefix=offline_node --with-your-options, make, make test, make install-offline and edit OPENCADIR/etc/config.xml.

The next step is really important you have to edit the file etc/configure_etc.sh. The directory with the serverconfigurations is protected because of the first step but all the other directories should only contain configuration files of the ca. Usually there should be the following directories:

/Test/OpenCA/etc/
/Test/OpenCA/lib/servers/offline_node
/Test/OpenCA/lib/servers/ca
/Test/htdocs/ca
/Test/htdocs/offline_node 

After you fixed the script please run it. Now the offline components are installed and configured.

4.2.3. OPENCADIR/etc/menu.xml

menu.xml must be fixed manually because it includes only a basic configuration. You have to copy a complete menu section. The section must be renamed from offline_node to online_node. The cgi_prefix must be fixed too. Please verifies the menus with the names ra, ldap and pub to use the correct links to the node interface. If all values are correct then you have now a working testinstallation with two management interfaces.