This interface manages the database and handles all the export and import functionalities.

The database can be initialized what means that OpenCA can create all the tables but OpenCA cannot create the database itself because this differs for every vendor. So we need a database with the appropriate access rights and a new database. The interface includes some functions for the backup and recovery of such a node but please bear in mind that you MUST have a separate backup of the CA's private key and certificate. There is no default mechanism in OpenCA to backup the private key. We don't implement it because first we found no general secure way to backup a private key and second the most CA's use HSMs and therefore you need a completely different and usually proprietary backup strategy.

The export and import will be handled by this interface too. You can configure different rules for the synchronization with nodes on a higher and a lower level of the hierarchy. This includes the configuration of the objects and status which can be exchanged. The configured filters avoid status injections from lower levels of the hierarchy.

The CA interface has all the functions which you need to create certificates and Certificate Revocation Lists (CRLs). The CA also includes all the functions which you can use to change the configuration via a web interface. It is not possible to change the configuration via another web interface.

The CA is the home of the batch processors too. OpenCA includes some powerful batch processors for creating certificates. These batch processors can be used for automatic certificate creation from various Enterprise Resource Planning (ERP) systems (e.g. SAP, HIS, NIS or /etc/passwd).

OpenCA's RA is able to handle all kinds of requests. This include things like editing requests, approving requests, creating private keys with smart cards, delete wrong requests and email users.

The LDAP interface was implemented to separate the LDAP management completely from the rest of the software. This is necessary because there are many functions which are really specific for LDAP admins, with only a few users needing these features.

The Public interface includes all the small things which the users need. This is only a small list and perhaps it is incomplete

Direct chaining of the Root CA and Sub CA including an image.

Chaining of a Root CA and a Sub CA via a normal public interface.

One of the biggest problems of PKI systems is the time. There are two different kinds of computers - online and offline. The usual administrators logic is that a network connected computer can use a timeserver. The question is can you trust this timeserver? A timeserver creates two problems. First is the timestamp really from the timeserver and second is the time source of the timeserver trustworthy? The connection to a timeserver can be secured via tunnel technologies like IPsec but the real problem is the time source. The most timeservers finally use a radio clock which receives a unsigned time signal from a radio station. This signal can be easily faked because it is very weak. So network time sources are really insecure.

After discussing the disadvantages of using online computers we can discuss offline technologies. Radio clocks are problematic and hence we need not discuss them twice. Also many buildings made from good ferroconcrete do not have problems with radio signals because they act as really nice Faraday cages! So what are the alternatives? First we need a trustworthy time source. Simply take a digital watch and compare it's time with several other clocks on the Internet, the video text of your TV, a radio clock, the sun ;-), GPS and any other source you can find. Second you transfer the time from your watch to the computer. Last but not least you have to check the drift and the clock itself on the computer. The drift is a small and easy to handle problem. The clock itself is a much bigger problem. If your computer is always connected to a power outlet then the clock should only drift. Please remember this if you put your CA on a notebook and the notebook into a safe. Several new notebooks have really bad CMOS batteries which result in a wrong time at every reboot. So as you can see time is not trivial.

The most common hardware crashes involve cooler and disk failures. You should backup all your important data - especially ALL issued certificates. Never lose a certificate or you must revoke the complete CA. Backups are a nice thing but it costs some time to recover from a backup. This results in two facts. First you must have a detailed (time-) plan how to recover from a backup. Second you should be able to tolerate disk crashes. RAIDs are sometimes expensive but they helps a lot (ask your SAN admins :) ).

Usually you can make a visual observation if your laptop crashes. A crashed offline computer can be detected by visual monitoring too. However a crashed online component of a PKI is problem because important information is not available,such as newly issued certificates and CRLs. Such a situation also brings down your services like SCEP. If a public interface of the security infrastructure is down then you are bound to have a trust problem with your users in the future. It is also noteworthy that a simple ping is not enough to detect hardware failure. You cannot detect a crashed web or OpenCA perl server with a ping. Software bugs can also cause 100 percent load. I know this problem from our web mail programs really well :)

If your offline CA consists of one offline notebook and you want to ensure dual control and no single point of failure then you can the following method as an example: use one IT module safe and two data safes. An IT module safe is a safe with its own climatization and UPC which has the same physical protection level like a safe. This safe is used to allow nonstop operation of the notebook which reduces time and availability problems. All three safes should have two locks. This ensures dual access control by key sharing. The setup is really simple and really efficient too.

The organization of the safes is really easy. You split the CA passphrase into two parts - front and back. The organization of the data and computers is like follows:

This organization ensures that one broken safe doesn't corrupt the infrastructure. It is important to immediately start a roll out of a new infrastructure but there is no reason for panic. This arrangement also ensures that a loss of one safe doesn't stop your operation. You need two safes to survive and the loss of one safe is acceptable at minimum for a short period of time.

Please remember that this is a really simple idea for medium risk CAs. High risk CAs should use more complex schemes to tolerate more than one broken safe. They should be able to tolerate at least two broken safes to have a longer schedule for the roll-out of a new CA.

This is more an area for a facility manager. The rooms with the PKI safes inside should have solid walls and a door with two locks. The room including the climatization system should be fire proof for 90 minutes (F90). The room and the entry should be camera observed. The cameras in the room itself should show the persons but not the keyboards and monitors. Papers should not be readable. The recorder for the camera should record one week at minimum. The room should also have an alarm system and must be safe against electro magnetic pulse (EMP) and water flooding. This is only a short summary of ideas. Please ask some assurance specialists or architects for more details.

CRL Distribution Points are a critical area. There were several PKIs in the earlier years which had no CDPs or only one CDP. Secure applications must verify the state of a used certificate. Such applications check the CDP field in the extensions of a certificate to find a usable verification source. Today a CRL Distribution Point should not be a source for a CRL. It can be an OCSP responder. A CDP is today more of a Certificate Status Point.

The first question is which protocols must be supported. The common protocols LDAP and HTTP should be supported always. HTTP is supported by nearly all devices but some devices prefer LDAP over HTTP - especially some network solutions. Additionally there are OCSP and HTTPS. OCSP is a protocol to verify the state of a single certificate. This protocol has a much better performance for slow network interconnects if you have large installations with many (revoked) certificates. HTTPS supports you with a trusted source, but is a trusted source necessary for CRLs? Usually not but sometimes yes. CRLs are signed by the CA and they have period of validity. There is only one working attack for CRLs. If a certificate was revoked, but the old CRL is still valid and if the CDP uses HTTP, then an attacker could present the user the old CRL. So this attack is more a question of security policy than a technical question. The validity period is a policy question too because most applications don't accept CRLs if the timestamp for the next update is over. The cool thing is that a CRL is never invalid! There can only be a newer CRL but as mentioned earlier this is more a political discussion.

The second question is how many physical CDPs do you need. If you design a scalable infrastructure then you must be able to tolerate service interruptions of several components like cables, routers, switches and servers. It is a really good idea to always have a local CDP if you only have a single interconnect to your central network. However not every branch office needs its own CDP, since if their computers (including their file and mail systems) are offline then it is not necessary to have a CDP online.

The third question is tricky. Which order should the CDPs have? The question is interesting in the case of network outages. If you support LDAP and HTTP, you have three servers which all serve both protocols. The CDP are ordered like the servers and servers one and two are not available because of a more or less big digger then your applications waits for four timeouts until it can access the first CDP successfully. The application has to wait for timeouts from LDAP on server one, HTTP on server one, LDAP on server two and HTTP on server three. So it is a really good idea to mix the order of protocols and servers. This is most important for application which understand many protocols. Stupid alphabetical ordering using the DNS names is not recommended. Do you think a user would wait two minutes per recipient of an email, for verification if he wants to send a commit for a meeting?

The last question often, does not have a complete solution today. Can some supported and necessary protocols crash other applications? If you use HTTPS then you should invest some time on this problem because it is a typical chicken and egg problem. If you have Microsoft client and the client tries to verify the certificate status via a HTTPS CDP then it receives a certificate from the HTTPS server. This certificate must be verified. If the certificate is from the same CA then the client would contact the HTTPS CDP again to verify the certificate and the verification problem would start again. This is a nice method to implement a busy wait. The only solution is to get a server certificate from another authority which use no CDPs or at minimum no HTTPS CDPs. The insight is that you should be really careful with the usage of crypto protected CDPs.

dual access control (physical and technical but first organizational aspects)

privacy vs. security (e.g. camera recorders)

access control but who controls the access control regulations (no self control)

how to integrate privacy officers public certificates - not always public certificates - which fields must be published? PID vs. new ID what is the identity of a person in conventional areas?

already existing ERP DBs meta directories

There are numerous situations where it is a good idea to operate more than one PKI for end users. Perhaps you need a server CA and a separate user CA. Sometimes an old CA is still active in issuing CRLs because there are still valid certificates but the new CA issues the newer certificates. Other people use different CAs to establish an easy access control by certificate chains (so called trust paths). As you can see there are really many situations where you have to operate more than one PKI.

Most PKI programmers like me have no problem in distinguishing between different PKIs, because we always ask ourselves as to who issued the certificate. Normal users instead look at the certificate, call the hotline and ask why their certificate for Jon Doe with serial 12345 does not work. At the other end the guy from the hotline looks into his computer and answers that the certificate is correct and valid. So what's going on?

A certificate has two significant elements to identify a certificate, which are different from the common name in the subject of the certificate, and which are easy to handle. The keyID and issuer from the authority key identifier are however not easy to interpret for an end user. First there is a serial and second there is an issuer. If a customer calls a hotline then the easiest way to handle a problem is by using organization wide unique serial numbers. If you start a second CA or you have to replace an old CA, never reuse serial numbers if possible. You will have to search for hours if somebody calls you and reports a broken certificate chain for a certificate 12345 when you have two of those certificates. If you ever issued certificates with identical serials then always ask the issuer if you receive an error report. Never ever create a replacement for an old CA with the same name. It only causes trouble.

To sum it up in a simple manner: If you avoid duplicate identifiers then you automatically avoid many problems.

OpenCA is not a complete monolithic system. It uses several software products from other developers of the Open Source community. The following things are used:

We use a lot of different Perl modules. Beginning with OpenCA 0.9.2 we no longer install all foreign modules. This is the normal behaviour of every Open Source project. The following should give you an overview about the required modules. Please note that you must install at minimum the listed version because some earlier versions like for example Net::Server include serious bugs.

OpenCA was tested on several softwarearchitectures but not on so many hardware architectures. Therefore we publish a list of used hardware. Please remember that OpenCA can be used on any system which support Apache, mod_ssl, OpenSSL and Perl. So if you have Unix box then it is usually possible to run an OpenCA on it.

You should define the used system before you start configureing OpenCA itself. OpenCA must know several parameters about your system to work properly.

OpenCA needs two sets of user and group. One set is used for stuff which must not be changed by the OpenCA daemon and the other set is used for dynamic stuff.

We have three different groups of paths - common stuff, prefixes for the different components of OpenCA and the paths for files of the webserver.

One path cannot be classified - --with-module-prefix=DIR. This path can be used to put all Perlmodules which OpenCA installs in one directory to be able to remove OpenCA from your system without any residues. It is also a good idea to use this option if you need different OpenCA installations with different versions of OpenCA on your system. Later versions of OpenCA can have different modules with different interfaces which are not backwards compatible.

The webserver configuration is the most complex and most simple part of the configuration too. If you have single http-server for OpenCA then you only need four options to configure OpenCA for this server. If you have a full featured corporate portal then you can integrate this software seemlessly in the the server. Therefore you can configure a lot of details. So we hope you find a good tradeoff ;-)

The mailoptions are deprecated too. Please read the post-install section to understand how to configure mail. Please don't use the configure option because they can be removed in the next releases.

You can enable three extra features for compilation and installation. SCEP and OCSP can be enabled because they are extra softwarepackages which can work independently from OpenCA but they are included in the distribution. The option --enable-package-build is used to support package maintainers. If it is activated all common parts of OpenCA are not installed automatically. This allows packagers to build seperate conflict free packages for every interfaces because all Perl modules and the common stuff can be put into seperate packages.

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.

chmod 000 etc/servers/*.conf*

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

The channel configuration checks the parameters of the incoming connection to detect misconfigured apaches and obsolete clients. The values in the configuration are regular expressions except of the type. The type defines the type of the environmentvariables which should be tested. Today we support only mod_ssl.

If you use encrypted connection then you must use ssl as protocol. If you need an unencrypted connection like on the CA for the interfaces ca and ca_node then you must use http as protocol if you use mod_ssl. If you use an Apache without mod_ssl then you must use .* to match all incoming protocols. Please remember to set all the keylengths to 0 because otherwise the access control rejects all incoming connections.

<channel>
    <type>mod_ssl</type>
    <protocol>ssl</protocol>
    <source>192.168.0.1</source>
    <asymmetric_cipher>.*</asymmetric_cipher>
    <asymmetric_keylength>0</asymmetric_keylength>
    <symmetric_cipher>.*</symmetric_cipher>
    <symmetric_keylength>128</symmetric_keylength>
</channel> 

We implemented three different ways to login to OpenCA:

<login>
    <type>none</type>
</login>
                

1.2.2. passwd

This method can be used to login via login and passphrase. OpenCA supports authentication based on an internal database and based on calling an external program to perform the actual user authentication.

Figure 4.2. Passphrase based login

1.2.2.1. internal database

For the 'internal database' method you can specify one or more users. Every user has a name, a role, an algorithm and a digest. The algorithm specify which kind of digest should be used to hash the passphrase. OpenCA supports three algorithms SHA1, MD5 and crypt.

<login>
    <type>passwd</type>
    <database>internal</database>
    <passwd>
        <user>
            <name>root</name>
            <algorithm>sha1</algorithm>
            <digest>3Hbp8MAAbo+RngxRXGbbujmC94U</digest>
            <role>CA Operator</role>
        </user>
        <user>...</user>
        ...
    </passwd>
</login> 

Example 4.2. Login and Passphrase configuration

Before somebody tries to crack this hash the passphrase is root and this is the default passphrase of OpenCA :)

We prepared a script to generate the digests. The name of the script is openca-digest and it will be installed during make install*. The program is used like "openca-digest (help|sha1|crypt|md5) string".

1.2.2.2. external authentication

External authentication can be used to integrate authentication methods that are not natively supported by OpenCA. Essentially this method is a variant of the username/passwort authentiation.

External authentication requires an external program that receives the login credentials that were passed on the login screen via the environment. The external program then must verify if the username/password combination represents a valid login and return an appropriate exit code (0 for success).

The external program should take care of handling the username/password information properly, i. e. it should NOT write this information to files or pass these values to other programs on the command line. The latter is particularly important, as this might open security problems when processing untrusted user input (i. e. the login name or the password). If you must call external programs with this information, please take extra care to tidy the login information of illegal characters (such as quoting special characters). Specification of username or password as command arguments is not directory supported for exactly this reason. Use shell script wrappers that read environment variables instead.

Configuration is straightforward:

In this example configuration two environment variables USERNAME and PASSWORD are set for the external program /usr/local/bin/authdummy. The special strings '__USER__' and '__PASSWORD__' are replaced with the actual user login information within environment value definitions. An arbitrary number of environment variables may be defined in the configuration file.

<login>
    <type>passwd</type>
    <database>externalcommand</database>
        <setenv>
            <option>
                <name>USERNAME</name>
                <value>__USER__</value>
            </option>
            <option>
                <name>PASSWORD</name>
                <value>__PASSWD__</value>
            </option>
        </setenv>
        <command>/usr/local/bin/authdummy</command>
</login> 

Example 4.3. External program authentication configuration

As an example a very simple external authentication program /usr/local/bin/authdummy could (but should not) look like this:

#!/bin/bash
if [ "$USERNAME" = "openca" -a "$PASSWORD" = "rocks" ] ; then
        exit 0
fi
exit 1
		

Again, ALWAYS be sure to check the user input when processing the login data as arguments to external programs, it is easy to open gaping security holes here!

<login
    <type>x509</type>
    <chain>OPENCADIR/var/crypto/chain</chain>
</login> 

The session management is today really simple to configure because we only support one method to manage a session and the only real variable is the lifetime of a cookie after the last action. The lifetime must be value which will be accepted by CGI::Session. The directory contains the management informations for the cookies (like the name of the user).

<session>
    <type>cookie</type>
    <directory>@var_prefix@/session/cookie</directory>
    <lifetime>1000</lifetime>
<session> 

The basic configuration of OpenCA's access control list is placed in OPENCADIR/etc/access_control/*.xml. The relevant datastructure is like follows:

<acl_config>
    <acl>yes</acl>
    <list>@etc_prefix@/rbac/acl.xml</list>
    <command_dir>@etc_prefix@/rbac/cmds</command_dir>
    <module_id>0</module_id>
    <ca_cert>@var_prefix@/crypto/cacerts/cacert.pem</ca_cert>
    <map_role>no</map_role>
    <map_operation>no</map_operation>
</acl_config> 

Following you can find the meanings of the elements:

You should check the access control list itself very carefully after you initialized the basic configuration of the interface. The real access control list is embedded into the access control area and has the following format:

<acl>
    <permission>
        <module>0<</module>
        <role>root<</root>
        <operation>serverInfo</operation>
        <owner></owner>
    </permission>
    <permission>...</permission>
    ...
</acl> 

The meanings of the elements are the following ones:

All options can be used with regular expressions but of course the parameters are case sensitive. An ACL which allows anything and only requires a valid login looks like this:

<acl>
    <permission>
        <module>.*</module>
        <role>.*</role>
        <operation>.*</operation>
        <owner>.*</owner>
    </permission>
</acl> 

Every command or script has it's own configuration file which contains the name of the command (this is actually a protection against the renaming of files), the name of the operation for which it is used, the way how to find the affected object and the name of the variable which contains the data which is necessary to determine the object by the specified way. Today there are six OWNER_METHODs:

OpenSSL only support the operational mode standby. Additionaly it support several other dynamic options which are required to work properly.

This token is only a dummy if the key is not a really seperate key. Often the administrators simply use symlinks to the CA keys and certs for the keybackup etc.. An empty token is redirect to the default token which is usually the CA token.

        <item>
          <name>HSM Management<name>
          <id>2<id>
          <item>
            <name>Login to HSMs<name>
            <link>cmd=hsmLogin<link>
            <target>main<target>
          <item>
          <item>
            <name>Logout from HSMs<name>
            <link>cmd=hsmLogout<link>
            <target>main<target>
          <item>
        <item>
            

This token accepts all the options like OpenSSL tokens except of PASSWD_PARTS because Chrysalis-ITS Luna CA3 uses hardware (PIN pad) for login to prevent electronic reconnaisance actions. Luna CA3 supports all operational modes (standby, session and daemon. This module requires some additional options:

This token accepts all the options like OpenSSL tokens but soem options has another meaning. The token only operates in mode standby. Other modes are not supported by OpenSC today. The available options have the following meanings (please notice that we only report OpenSSL options if there meaning differ from the original OpenSSL module):

Usually the first question is about what does an additional attribute be? Additional attributes where introduced to store extra informations in a request without publishing these informations. Big organizations or trustcenters need a lot of information and only a minimal subset should be public. If you are a postmaster or a webmaster of a university then it is a good idea to put the general emailaddresses into the certificates but it is not really optimal to store the telephonenumber in the certificate. Nevertheless it makes sense for the trustcenter stuff to have the phonenumber in a case of emergency.

After you know what a nice feature these attributes are you want to customize them? No problem. A simple example should help:

ADDITIONAL_REQUEST_ATTRIBUTES   "requestercn" "email" "department" "telephone"
ADDITIONAL_ATTRIBUTES_DISPLAY_VALUE     "Name (first and Last name)" "Email" "Department"  "Telephone"
ADDITIONAL_REQUEST_ATTRIBUTES_STRING_TYPE "LATIN1_LETTERS" "EMAIL" "LATIN1_LETTERS" "LATIN1_LETTERS" 

The three options have the following meanings:

The first certificates which were needed in the open source are were server certificates. The most systems which use such certificates are Apaches, OpenLDAPs, IMAPDs, POPDs, SMTPDs and S-Tunnel. Such systems generate the private key by itself - means the administrator generate a key by hand or via the software but there is no interaction with the trustcenter's software until the administrator created a request with the key or exported a request from the software.

If the administrator has the PKCS#10 request then he must bring the request to the trustcenter and this is the job of command which's configuration we describe here. The option DN_TYPE_PKCS10_REQUIRED_ELEMENTS define the structure of the subject of the PKCS#10 request. The option DN_TYPE_PKCS10_BASE and the values of DN_TYPE_PKCS10_BASE_* define the suffix for the certificates which will be accepted by this interface. The restrictions were implemented to get some kind of useful subjects.

DN_TYPE_PKCS10_REQUIRED_ELEMENTS "CN" "OU" "O" "C"
DN_TYPE_PKCS10_BASE     "O" "C"

DN_TYPE_PKCS10_BASE_1 "OpenCA"
DN_TYPE_PKCS10_BASE_2 "it" 

If you have no prepared PKCS#10 request then there is a second method in OpenCA. This method is used if the key and request generation happen during the interaction with the client. OpenCA support clientside keygeneration for Microsoft Internet Explorer, Netscape Communicator, Mozilla and Opera. If you have another browser then OpenCA uses it's serverside key and requestgeneration. So let's start with an example:

    Basic_CSR_Keysizes "512" "768" "1024" "2048" "4096"

    DN_TYPES "BASIC"
    DN_TYPE_BASIC_KEYGEN_MODE "SERVER"
    DN_TYPE_BASIC_KEYGEN_SHEET "@lib_prefix@/servers/@pub_prefix@/sheets/basic_csr_confirm_request.html"

    DN_TYPE_BASIC_BODY "Y"
    DN_TYPE_BASIC_BASE "O" "C"
    DN_TYPE_BASIC_ELEMENTS "emailAddress" "CN" "OU"
    DN_TYPE_BASIC_NAME "Basic User Request"

    DN_TYPE_BASIC_BASE_1 "@ca_organization@"
    DN_TYPE_BASIC_BASE_2 "@ca_country@"

    DN_TYPE_BASIC_ELEMENT_1                "E-Mail"
    DN_TYPE_BASIC_ELEMENT_1_MINIMUM_LENGTH 7
    DN_TYPE_BASIC_ELEMENT_1_REQUIRED       "YES"

    DN_TYPE_BASIC_ELEMENT_2                "Name"
    DN_TYPE_BASIC_ELEMENT_2_MINIMUM_LENGTH 3
    DN_TYPE_BASIC_ELEMENT_2_REQUIRED       "YES"

    DN_TYPE_BASIC_ELEMENT_3                "Certificate Request Group"
    DN_TYPE_BASIC_ELEMENT_3_SELECT         "Internet" "Partners" "Employees" "Trustcenter"
    DN_TYPE_BASIC_ELEMENT_3_MINIMUM_LENGTH 8
    DN_TYPE_BASIC_ELEMENT_3_REQUIRED       "YES" 

The first line defines the available keysize. The next variable DN_TYPES defines the available configurations of basic_csr. The command basic_csr is called via a link and the link must contain an option CSR_TYPE which defines the configuration which is used for this CSR. If you don't set this option then basic_csr starts it's browserdetection.

The default type which is supported by OpenCA is BASIC. You can simply add a type and set a correct link in the public gateway. You can find an example on the public gateway by looking at the link “Basic Request”.

The prefix of every definition is now DN_TYPE_BASIC_. The NAME defines the displayed name (e.g. "Request for managers only"). The BODY defines the type of the request. If the value is Y or YES then a key and a request will be stored and if necessary generated. If the value is N or samp then only a header will be generated. This option is used to get the necessary data from a user to initialize a smartcard on the registration authority.

DN_TYPE_BASIC_KEYGEN_MODE specifies the way how to generate a key and request. The supported modes are SERVER, SPKAC and IE. SPKAC is used with Opera, Mozilla and Netscape, IE is used for Microsoft Internet Explorer and SERVER is used for all other situations.

The BASE is the part of the subject which is not editable by the user who requests a certificate. The other BASE_numbers define the values of the elements which are used for the not editable part of the subject.

The ELEMENTS are the part of subject which can be defined by the user. The defined attributes of the subject can be configured more precisely by the options named *_ELEMENT_number*. They have the following meaning:

<openca>
    <basic_csr>
       <basic>
           <element_3>
               <option>Computer staff</option>
               <option>Management</option>
               ...
           </element_3>
       </basic>
    </basic_csr>
</openca> 

OpenCA supports SCEP for sending requests but we define no rules for such requests because the clients are not able to interact with an interface and so we accept every request which arrives.

OpenCA displays at every time DNs like defined by RFC 2253. There are five options which influence the subject during the issuing itself:

OpenCA uses by default the old “o=University,c=de” style. Several users like international companies, universities or other big organizations need the new dc style. Therefore we support the dc style too. It is necessary to change several files because the configuration of the subjects is highly integrated into the software. We will explain it with an example.

base dn or suffix: dc=university,dc=edu
user dn: dc=mike tester,dc=university,dc=edu
webserver dn:dc=www,dc=university,dc=edu
ca dn:dc=CA,dc=university,dc=edu
            

There are five things which you have to check for the change to the dc style. The steps will be now described:

basedn "dc=university,dc=edu"
ldaproot "dc=manager,dc=univesity,dc=edu"
               

DN_TYPE_BASIC_BODY "YES"
DN_TYPE_BASIC_KEYGEN_MODE "SERVER"
DN_TYPE_BASIC_KEYGEN_SHEET "/usr/local/OpenCA/lib/servers/pub/sheets/basic_csr_confirm_request.html"

DN_TYPE_BASIC_BASE "DC" "DC"
DN_TYPE_BASIC_ELEMENTS "DC"

DN_TYPE_BASIC_NAME "Basic User Request"

DN_TYPE_BASIC_BASE_1 "University"
DN_TYPE_BASIC_BASE_2 "edu"

DN_TYPE_BASIC_ELEMENT_1 "Name"
                

A full description of the configuration of your LDAP directory is outside the scope of this document. Important points to note are:

Three configuration files must be configured for the online components to make use of the LDAP directory to store certificates; OPENCADIR/etc/servers/node.conf, OPENCADIR/etc/servers/ldap.conf and OPENCADIR/etc/ldap.xml. Usually it is enough to set the correct options in ldap.xml or in config.xml.

The configuration is splitted into two parts - a OpenCA related part and a LDAP related part. The OpenCA related part consists only of four options - the LDAP activation, automatic LDAP updates during imports and distinguished name manipulations for CA objects like CA certificates and CRLs. These options can be configured in the interface configurations in OPENCADIR/etc/servers/.

The LDAP related part of the configuration can be found in OPENCADIR/etc/ldap.xml. This central configuration file avoids double configurations which can produce many errors and confusion because you are sure that you changed it but you only did it for one interface. The isolated configration allows better names for the configuration options too.

As long as the option updateLDAPautomatic is set to yes the online components will attempt to upload certificates to the directory after an import. Before this can happen the directory must be initialised and the appropriate structure must be implemented. In this version of OpenCA this initialization is done automatically.

The common situation in large directory projects is a big schema and at the end a small request for certificate integration. This is usually no problem if OpenCA has to create and add certificates to an existent and filled LDAP server. OpenCA gets a problem if you want that OpenCA initialize this LDAP server and should create all missing nodes in the directory tree. If this is the case then you must integrate your schema specification into OpenCA's ldap configuration. You can find this schema specification in ldpa.xml. The path to the schema specification is openca/ldap/schema.

First you have to understand the general design of OpenCA's LDAP schema support. We have a very pragmatical idea of directory trees because it is not possible to handle all full featured ideas. We simply use the least significant attribute to select an appropriate schema definition for a distinguished name. Do you want to know what this mean? If you have a RFC 2253 conform distinguished name then you take the RDN on the left side. The used attribute type is used to detect the appropriate schema.

Before you can select a schema with the atribute type you must know what you want to create for a node in the directory tree. If the used distinguished name is the complete subject of a certificate then you must select the schema specification from the XML path openca/ldap/schema/certificate. Otherwise you you have to use openca/ldap/schema/default. If you need to store a CA certificate then you must specify the schema in openca/ldap/schema/ca.

Every RDN entry in the described sections specifies the characteristics for one attributetype. This include things like required (must) or optional (may) attributes and used objectclasses (structural and auxiliary). If you have for example a new attributetype uid_special and a new class MY_CLASS then your RDN section for certificates with this attributetype as last one should looks like this.

        <rdn>
          <attributetype>uid_special<attributetype>
          <must>
            <attributetype>uid_special<attributetype>
          <must>
          <may>
            <attributetype>cn<attributetype>
            <attributetype>mail<attributetype>
            <attributetype>emailAddress<attributetype>
          <may>
          <structural>
            <objectclass>person<objectclass>
            <objectclass>organizationalPerson<objectclass>
            <objectclass>inetOrgPerson<objectclass>
            <objectclass>MY_CLASS<objectclass>
          <structural>
          <auxiliary>
            <objectclass>opencaEmailAddress<objectclass>
            <objectclass>pkiUser<objectclass>
          <auxiliary>
        <rdn>
          

OpenCA's schema definition is perhaps not so flexible as you need but we are open for new ideas. Be free to mail us your ideas. If they are not too proprietary then perhaps we can integrate them :)

This file contains the followin parameters:

This file contains the followin parameters:

The dataexchange of OpenCA is highly configurable. So first we have to describe some general concepts.

If you look at OpenCA from a database viewpoint then OpenCA is a tree of hierarchical organized databases. Every database is used by some web interfaces. So one node of the hierarchy consists of a database and some web interfaces. If we describe the dataexchange then we describe the dataexchange between nodes. This is the reason why we called the management interface node.

A node can exchange data with a node of a higher level of the hierarchy or with several nodes which are on a lower level of the hierarchy. If export data to a higher level of the hierarchy then we UPLOAD data and if we import data from such a node then we DOWNLOAD data. If import data from a lower level then we RECEIVE data and if export data to such a node then we ENROLL data.

If you exchange object in a security relevant area then you must define which object with which state you want to exchange. Therefore you can define in OpenCA which objects with which state you accept from which direction. Also OpenCA allows only to overwrite existing objects if you DOWNLOAD CA-certificates, CRLs, CSRs and CRRs. Status or object injections are not accepted in all other situations. OpenCA includes some default configurations to help you on the way to secure configuration.

The following example is for the import from a higher level of the hierarchy:

DOWNLOAD_CA_CERTIFICATE_STATES VALID
DOWNLOAD_CERTIFICATE_STATES    VALID
DOWNLOAD_CRL_STATES            VALID
DOWNLOAD_CRR_STATES            ARCHIVED DELETED APPROVED
DOWNLOAD_CSR_STATES            ARCHIVED DELETED
DOWNLOAD_MAIL_STATES           CRINS DEFAULT 

The export/import technology itself is another important aspect. You can configure OpenCA to use different methods for the dataexchange with higher and lower levels of the hierarchy. Therefore we implemented options to prepare and cleanup IO operations. This is necessary if you have to start special networkinterfaces or to mount devices. There are also options to configure the EXPORT and IMPORT of the directory with the data and there is an option to TEST the result. EXPORT, IMPORT, START and STOP accept more then one argument. Every argument will be seperately executed. The parameters @__SRC__@ and @__DEST__@ include the directories with the data. The parameter @__DEVICE__@ will be replaced with the value of DEVICE.

EXPORT_IMPORT_UP_DEVICE "/dev/fd0"
EXPORT_IMPORT_UP_START ""
EXPORT_IMPORT_UP_STOP ""
EXPORT_IMPORT_UP_EXPORT "/bin/tar -cvfp @__DEVICE__@ -C @__SRC__@"
EXPORT_IMPORT_UP_IMPORT "/bin/tar -xvf @__DEVICE__@ -C @__DEST__@"
EXPORT_IMPORT_UP_TEST "/bin/tar -tvf @__DEVICE__@" 

The hierarchylevel LOCAL is used for backups, batchprocessors and such things. It is also possible to configure OpenCA for the use with temporary private networks. Here is another example for a CA:

    EXPORT_IMPORT_DOWN_DEVICE "openca.tar"
    EXPORT_IMPORT_DOWN_START "/sbin/ifconfig eth0 up"
    EXPORT_IMPORT_DOWN_STOP "/sbin/ifconfig eth0 down"
    EXPORT_IMPORT_DOWN_EXPORT "/bin/tar -cvfp /usr/local/openca/var/tmp/@__DEVICE__@ -C @__SRC__@" "/usr/bin/scp /usr/local/openca/var/tmp/@__DEVICE__@ openca@ra.openca.org:/usr/local/OpenCA/var/tmp/" "rm /usr/local/openca/var/tmp/@__DEVICE__@"
    EXPORT_IMPORT_DOWN_IMPORT "/usr/bin/scp openca@ra.openca.org:/usr/local/OpenCA/var/tmp/@__DEVICE__@ /usr/local/openca/var/tmp/@__DEVICE__@" "/bin/tar -xvf /usr/local/openca/var/tmp/@__DEVICE__@ -C @__DEST__@" "rm /usr/local/openca/var/tmp/@__DEVICE__@"
    EXPORT_IMPORT_DOWN_TEST ""

# On the CA side do the following: 

$> mkdir /var/www/.ssh
$> cd /var/www/.ssh

# Now we generate a new private public key pair for the ssh connection
# between CA and RA. When prompted, name the key id_rsa_1024_openca.

$> sshkeygen -b 1024 -t rsa
$> cp id_rsa_1024_openca identity
$> chown -R apache:apache /var/www/.ssh

# Copy the id_rsa_1024_openca.pub public key to the RA.
# On the RA side do the following: 

# Add a new user called openca:

$> adduser openca

# Change the password of this user to whatever you want.

$> passwd openca
$> mkdir /home/openca/.ssh
$> cp id_rsa_1024_openca.pub /home/openca/.ssh
$> cp id_rsa_1024_openca.pub /home/openca/.ssh/authorized_keys
$> chown -R openca:openca  /home/openca/.ssh
            

If you create a new node e.g. a second RA then you have to support this node with the dataexchange mechanism. Every interface of OpenCA must have a unique module ID. OpenCA manage the complete dataexchange with the ID of the node interface. The node interface knows which object of which datatype was already received by another node.

If you want to create a new node then you must create the corresponding files in OPENCADIR/var/log. You have simply to create some files in the directories OPENCADIR/var/log/enroll and OPENCADIR/var/log/download depending on the direction which you use for epxort. These directories contain some files of the style $number_$datatype. $number is the module ID of the node to which you want to export the data. The datatype is from the exported objects.

If you created a new module ID (e.g. you setup another RA) then you have simply to touch the file $number_$datatype. The new file is empty and so all objects will be exported.

This is only a short introduction to PostgreSQL. This section should not replace the reading of the PostgreSQL Administration Guide but after the lecture of this section you should be able to setup OpenCA very easily with a real datbase. This is important because PostgreSQL has transaction support which is essential for serious database applications.

If we talk about real world databases then it is a good idea to mention pgadmin III. The old versions pgadmin I and II only support windows. The third version supports Unix too. So there is now a GUI like for MySQL available which can be used to manage the database. There are people who think that GUIs are not necessary but they enhance the management of several things a lot because not everybody has the time and skill to optimize it's PostgreSQL database perfectly.

Another note about security, please never trust database security mechanisms fully. Use at every time a small IP-firewall in front of your database server. The default installation of OpenCA is a datbase server on localhost. If you want to install a database server on a different machines than the OpenCA components then always install these servers at minimum in a DMZ. Databases like PostgreSQL has today it's own strong security mechanisms but they have from time to time some big bugs. OS-based IP-filters like ipf or netfilter are usually more robust.

su - postgres
psql -d template1
psql> create user openca with password '1234567890' createdb nocreateuser;
psql> \q
psql -d template1 -U openca
psql> create database openca;
psql> \q
          

# TYPE    DATABASE  USER      IP_ADDRESS    MASK              USERAUTH  MAP
host      openca    openca    127.0.0.1     255.255.255.255   md5
          

tcpip_socket = true
          

## normal fully portable SQL export
pg_dump --file=backup.sql --format=p        \
        --create --inserts --column-inserts \
        -U openca openca

## tar-based SQL export for pg_restore
pg_dump --file=backup.tar --format=t        \
        --create --inserts --column-inserts \
        --blobs                             \
        -U openca openca

## custom compressed SQL export for pg_restore
pg_dump --file=backup.pgc --format=c        \
        --create --inserts --column-inserts \
        --blobs                             \
        -U openca openca
          

## normal fully portable SQL export
psql -f backup.sql

## tar-based SQL export for pg_restore
## custom compressed SQL export for pg_restore
pg_restore --create --orig-order --verbose -U openca backup.(tar|pgc)
          

Until now nobody created a howto for MySQL.

Oracle is supported by OpenCA via the standard Perl DBD Driver. However, there are some special considerations concerning system setup, configuration and security.

#!/bin/sh

if [ -f ~oracle/bin/oraenv ] ; then
    PATH=$PATH:/usr/local/bin
    ORAENV_ASK="NO"
    . ~oracle/bin/oraenv
fi

openca_start=/usr/local/openca-0.9.2/etc/openca_start
openca_stop=/usr/local/openca-0.9.2/etc/openca_stop

case "$1" in
    start)
        echo -n "Starting OpenCA ... "
        if $openca_start; then
            echo OK;
        else
            echo FAILED;
        fi
    ;;
    stop)
        echo "Shutting down OpenCA ... "
        $openca_stop
    ;;
    restart)
        $0 stop
        $0 start
    ;;
    *)
    echo "Usage: $0 {start|stop|restart}"
    exit 1
esac
	

-- create schema owner
CREATE USER pkiop IDENTIFIED BY "dummy" 
  DEFAULT TABLESPACE DATA01 
  TEMPORARY TABLESPACE TEMP01
  QUOTA UNLIMITED ON DATA01;
GRANT UNLIMITED TABLESPACE TO pkiop;
-- schema owner does not need to log in
ALTER USER pkiop ACCOUNT LOCK;

-- create openca schema
create table pkiop.ca_certificate (ca_cert_key varchar2 (1999) 
  PRIMARY KEY NOT NULL, format varchar2 (1999), data LONG, 
  dn varchar2 (1999), cn varchar2 (1999), email varchar2 (1999), 
  status varchar2 (1999), public_key varchar2 (1999), 
  notafter number (38));

create table pkiop.crl (crl_key varchar2 (1999) 
  PRIMARY KEY NOT NULL, status varchar2 (1999), 
  format varchar2 (1999), data LONG, last_update varchar2 (1999), 
  next_update varchar2 (1999));

create table pkiop.crr (crr_key number (38) PRIMARY KEY NOT NULL, 
  cert_key number (38), submit_date varchar2 (1999), 
  format varchar2 (1999), data LONG, dn varchar2 (1999), 
  cn varchar2 (1999), email varchar2 (1999), ra varchar2 (1999), 
  rao varchar2 (1999), status varchar2 (1999), 
  reason varchar2 (1999), loa varchar2 (1999));

create table pkiop.request (req_key number (38) PRIMARY KEY NOT NULL, 
  format varchar2 (1999), data LONG, dn varchar2 (1999), 
  cn varchar2 (1999), email varchar2 (1999), ra varchar2 (1999), 
  rao varchar2 (1999), status varchar2 (1999), role varchar2 (1999),
  public_key varchar2 (1999), scep_tid varchar2 (1999), 
  loa varchar2 (1999));

create table pkiop.certificate (cert_key number (38) 
  PRIMARY KEY NOT NULL, format varchar2 (1999), data LONG, 
  dn varchar2 (1999), cn varchar2 (1999), email varchar2 (1999), 
  status varchar2 (1999), role varchar2 (1999), 
  public_key varchar2 (1999), notafter number (38), 
  req_key number (38), loa varchar2 (1999));

-- create schema user
CREATE USER OPS$WWWDATA IDENTIFIED EXTERNALLY
  DEFAULT TABLESPACE DATA01 
  TEMPORARY TABLESPACE TEMP01
  QUOTA UNLIMITED ON DATA01;
GRANT CREATE SESSION TO OPS$WWWDATA;
GRANT UNLIMITED TABLESPACE TO OPS$WWWDATA;

GRANT SELECT, INSERT ON pkiop.CA_CERTIFICATE TO OPS$WWWDATA;
GRANT SELECT, INSERT ON pkiop.CRL TO OPS$WWWDATA;
GRANT SELECT, UPDATE, INSERT ON pkiop.REQUEST TO OPS$WWWDATA;
GRANT SELECT, UPDATE, INSERT ON pkiop.CRR TO OPS$WWWDATA;
GRANT SELECT, UPDATE, INSERT ON pkiop.CERTIFICATE TO OPS$WWWDATA;
         

<!-- ====================== -->
<!-- database configuration -->
<!-- ====================== -->
<option>
    <name>dbmodule</name>
    <!-- you can use DB or DBI -->
    <value>DBI</value>
</option>
<option>
    <name>db_type</name>
    <value>Oracle</value>
</option>
<option>
    <name>db_name</name>
    <value></value>
</option>
<option>
    <name>db_host</name>
    <value></value>
</option>
<option>
    <name>db_port</name>
    <value></value>
</option>
<option>
    <name>db_user</name>
    <value>/</value>
</option>
<option>
    <name>db_passwd</name>
    <value></value>
</option>
<option>
    <name>db_namespace</name>
    <value>pkiop</value>
</option>
	 

DBM file are much easier to handle than real SQL databases. If you want to use these database then you must only ensure that the directory which should contain the database files is fully writeable, readable and accessible by the webserver user. This will be handled by OpenCA's installation routine automatically. Sometimes in the past the users choose the wrong webserver user. The result is a message in the logs that the function configError doesn't exist. This happens because the OpenCA script cannot load the library files. The new versions of OpenCA (0.9.1.4+) display correct errormessages in this case. Extra actions by the installing administrator are not necessary.

Please never forget that DBM files don't support transactions. If you implement a real world PKI then it is strongly recommend to use SQL databases to have a consistent state of the PKI even in the case of a system crash. DBM has also problems with multi user access for example on web servers with high loads.

## create GNU backup
tar -czf dbm.tar.gz -C $OPENCADIR/var/ db/

## install GNU backup
tar -xzf dbm.tar.gz -C $OPENCADIR/var/

## create Unix backup
cd $OPENCADIR/var/
tar -cf dbm.tar db
gzip dbm.tar

## install Unix backup
cd $OPENCADIR/var/
gunzip dbm.tar.gz     ## gzip -d is identical
tar -xf dbm.tar
          

We replaced DBM files with SQLite. the background is simple. Both databases work out of the box without user configuration but SQLite has full SQL support. Please note that SQLite only allows one open transaction which write on the database. So SQLite is a database for a single user system. This means that you should only use it for offline machines (e.g. CA) or in test environments. Please never use it for online user interfaces.

The installation is quite simple. You have only to install DBD::SQLite. The Perl database driver includes the complete database software.

The following example shows how to configure sendmail to send mails via a mailserver which requires a login. This basic authentication is today very common to protect the mailservices especially of big providers against spammers. The example was developed and tested with Microsoft Exchange but it should work with any other mailserver (e.g. sendmail or postfix).

divert(-1)dnl
dnl # Example for establishing email distribution with sendmail(client) via Microsoft Exchange Server
dnl # This is the sendmail macro config file for m4.
dnl # If you make changes to
dnl # /etc/mail/sendmail.mc, you will need to generate the
dnl # /etc/mail/sendmail.cf file (by means of the sendmail-cf and m4)

dnl # general: comments start with dnl, statements end with dnl
dnl # command for creating sendmail.cf:
dnl # =>  m4 /etc/mail/sendmail.mc > /etc/mail/sendmail.cf
dnl # requisite: sendmail-cf

dnl # include sendmail-cf path: 
include(`/usr/share/sendmail-cf/m4/cf.m4')dnl
VERSIONID(`setup for Red Hat Linux')dnl
OSTYPE(`linux')dnl

dnl # initiating masquerading
GENERICS_DOMAIN(`localhost.localdomain localhost')dnl

dnl # create genericstable (file in /etc/mail)and insert records for name mapping:
dnl # root: first.last@name.com
dnl # openca: first1.last1@name1.com
dnl # initialising of genericstable
dnl # =>  sendmail -bi -oA/etc/mail/genericstable

dnl # activating masquerading
FEATURE(genericstable)dnl
FEATURE(masquerade_envelope)dnl

dnl # mailserver where we connect to 
define(`SMART_HOST',`<URL mailserver>')dnl

FEATURE(redirect)dnl
FEATURE(nocanonify)dnl
define(`SMTP_MAILER_FLAGS',`e')dnl

dnl # some time-outs
define(`confTO_CONNECT', `1m')dnl
define(`confTO_IDENT', `0')dnl

dnl # since this mailserver requires logon authentication we have to
dnl # provide this information
dnl # create auth-info (file in /etc/mail), insert record:
dnl # AuthInfo:<URL mailserver> "U:<user>" "P:<password>" "M:LOGIN"
dnl # this mailserver requires AUTH LOGIN
dnl # sendmail requires db-file:
dnl # =>  makemap hash /etc/mail/auth-info.db <etc/mail/auth-info

FEATURE(`authinfo', `hash -o /etc/mail/auth-info.db')dnl
dnl # we use SMTP
MAILER(smtp)dnl

dnl # while testing:
dnl # changes in sendmail.mc: compile with m4 to new sendmail.cf
dnl # =>  service sendmail stop
dnl # =>  service sendmail start
dnl # or for testing start sendmail as demon and logging dialog to file:
dnl # => sendmail  -bd  -O LogLevel=14  -X /tmp/out1.log

dnl # for basic checking, set up manual communication with mailserver
dnl # => telnet <URL mailserver) 25
dnl # => ehlo localhost
dnl # ? <receiving basic info>
dnl # =>  AUTH LOGIN
dnl # mailserver replies b|ase64 encoded, we have to reply base64-encode
dnl # => <first user> ?
dnl # => <then password>?
dnl # => MAIL FROM: <valid mail-address>
dnl # => RCPT TO: <vaild mail-address>
dnl # => DATA
dnl # ?
dnl # stop communication with <new line> . <new line>
dnl # QUIT 
        

Debian set the variable LANGUAGE by default. Sometimes this variable has some funny content (e.g. en_DE). OpenCA erases this variable automatically but it is a good idea to do it by yourself before you start the daemon.

If your OpenCA does not show some translated languages and fall back to other languages then you must activate the language on your machine. This is quite simple. You must run dpkg-reconfigure locales and select all necessary languages with UTF-8 encoding. OpenCA enforces the usage of UTF-8. We do not support other proprietary encodings.