If you start thinking about email security then the starting point is S/MIME or PGP. However at times ethereal admins just use IMAPS and POPS. So far so good. Later they think about server based security and try to implement SMTP over TLS. Certificates issued by OpenCA can be used for SMTP over TLS because the certificates can act both as a client and a server certificate. If you use some other software than OpenCA, or you create a new role for such servers then you should read the documentation of your SMTP server really carefully.

A SMTP server can use two methods for SMTP over TLS. It can use a single certificate which includes the extensions for TLS client and servers, or it can use two certificates - one client and one server certificate. Please read the specs for the certificates carefully and then read specifications for TLS clients and TLS servers. If the SMTP server reports an error after start tls then there is usually a missing extension or a problem with the certificate chain. See Section 3.2.2, “SMTP server”.

Old Netscape clients do not conform with RFC standards. They use the common name as a regexp to match the server name and ignore the subject alternative name completely. A workaround is described in the configuration area of OpenSSL (see Section 3.2.1, “HTTPS server”).

OpenLDAP is an open source software but it's TLS implementation is not the best one. It doesn't check the subject alternative name first, instead it checks the common name of the subject to match the DNS name or IP address. This fails if the certificate subject includes a regexp for old Netscape clients. Two non-standard compliant software packages collide here. Netscape needs regular expressions, OpenLDAP does not support regular expressions and both software packages do not check the subject alternative name first. So it's your job to make a trade-off, or to use Mozilla!

OpenCA includes a directorystructure to store all relevant data in one central place. This place can be specified with --with-openca-prefix. This installation option is recommended for normal installations from the source code. Secure or not the most users want to install packages (e.g. RPM or DEB). Packages have the big advantage that you remove or add a software without any risks. In this case we have to support the package maintainers with configuration options to build packages which conform with the guidelines for the distros. Therefore you can use --with-etc-prefix, --with-lib-prefix and --with-var-prefix too.

Today there are six different components - ca, ra, ldap, pub, node and scep. Every component must have a different name to have distinguished configuration files and distinguished paths. All the names will be calculated automatically. You have only to edit these prefixes if you need a special configuration like a second RA on the same machine.

Every webserver needs some basic informations. These informations are the hostname (--with-web-host), the user (--with-httpd-user) and the group of the server (--with-httpd-group). These are the rudimentary informations which OpenCA needs before you can start configuring the paths. The defaults are an empty hostname, nobody and nogroup.

The most trivial installation case is the default apache installation. In this case you have only to set --with-httpd-fs-prefix to the directory where your apache is. All other directories will be set automtically.

The standard webserver doesn't use Apache's default installation. Therefore it is possible to configure every detail of the installation. The first splitting is into CGI (--with-cgi-fs-prefix) and HTDOCS (--with-htdocs-fs-prefix). The most test systems don't need the other options. They have only to know where the appropriate directories are.

Our software was designed for really big companies and organizations too. They have usually portals for their employees and customers. If you have to integrate an OpenCA interface into such a portal then there are good news for you - you don't have to edit paths and links by hand. You can configure the placement of CGI and HTDOCS area of every interface seperately. The options are --with-(ca|ra|ldap|pub|node|scep)-(cgi|htdocs)-fs-prefix). We think that more flexibility is not necessary. So if you think OpenCA is to unflexible then write a mail to us with your ideas.

OpenCA 0.9.1 supports a lot of options to configure the URLs like the filesystem paths. This is possible with OpenCA 0.9.2 too but it is deprecated to do this with configure. Please read the post-install section. It can happen that these options will be removed from configure.

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 <Registration Authority &lt;pki@your_org.edu>>. You can replace > by &gt; 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 ...

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.

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.

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:

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.

request serial ::= order number * 2^(MODULE_SHIFT) + MODULE_ID

Module ID    ::= 2
Module shift ::= 8

order number :   real serial
-------------:-----------------
      1      : 1 * 2^8 + 2 = 258
      2      : 2 * 2^8 + 2 = 514
      3      : 3 * 2^8 + 2 = 770
              

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.

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.

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.

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.

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.

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.

The first possibility means that there is no login and everybody who pass the channel verification can use the interface. This possibility is nothing else than the deactivation of the access control.

This is not only an option for debugging and testing. You can also use this option if you want to use a RA interface on a server which allows only RA access from the local machine but not over a remote computer.

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

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

<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> 

<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> 

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

This is perhaps the most advanced method to login. The user must sign it's assigned session ID and the access control verifies the signature. The login name is the serial of the certificate because it is the only unique item in a certificate. The configuration is really simple. You have to set the position of the CA chain and that's all.

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

The filtering of the users is not the job of the login because the login has only to identify the user. The filtering has to be implemented in the ACLs. Therefore we cannot recommend the x509 (smartcard) authentication until now.

This module provides basic support for nCipher HSM tokens and was tested with the following configuration:

The current status is considered to be stable.

Features:

Current limitations:

The module was derived from OpenCA::Token::OpenSSL and other existing token implementations.

Error code prefix: 715*

Error codes:
7151010 Crypto Layer not defined
7151012 Token name not defined
7151013 NFAST_HOME not defined (configuration problem)
7151014 NFAST_HOME not accessible (directory does not exist or permission
        denied)
7151015 Unexpected exception during program execution

7153050 Key is not preloaded/usable
7153051 nCipher 'hardserver' process is not running
7153052 nCipher 'hardserver' process is not operational
7153053 Could not execute 'enquiry' program
7153054 Could not execute 'nfkminfo' program
7153055 Could not execute 'nfkmverify' program
7153056 No operational nCipher modules online
7153057 nCipher security world is not initialized / is not usable
7153058 No preloaded objects found
7153059 External program call timed out

7154001 Key generation not supported
            

All external program calls are subject to a hard timeout that is initially set to 6 seconds. This value can be configured by setting the class attribute CHECKCMDTIMEOUT to the desired value (see constructor).

If an external program does not terminate within a certain timeout, it is killed by SIGALRM and the method fails with a timeout error (7151015). This was introduced in order to handle hanging nCipher utility processes after e. g. switching of an external SCSI HSM.

genKey() - This method is administratively disabled and always returns the error code 7154001.

online() - The online test performs the following tests:

The method returns true without calling external checks if the module accessibility was checked within the last 60 seconds. This value can be configured by setting the class attribute ONLINECHECKGRACEPERIOD to the desired value (see constructor).

The module requires a properly set up nCipher "Security World" including a private key to operate. Key generation is not supported by the module (as it really does not make much sense for a HSM based CA).

See Section 2.4.6, “Example for the setup” for an example.

In order to use the HSM protected key, log in into the CA computer and run /opt/nfast/bin/with-nfast pause in a shell.

You will be prompted to insert as many Operator Cards and input their corresponding PINs as required by the Operator Card Set Quorum.

As long as 'with-nfast' is not interrupted and the last Operator Card is not removed, any application with the proper Unix permissions may use the keys protected by the Operator Card Set.

To log out from the module it is recommended to terminate the with-nfast program (pulling the SmartCard works, too, but is not recommended, because it leaves the program waiting).

A simple login mechanism can be implemented using a special HSM login user. The user must have write access to the file /opt/nfast/kmdata/preload/default. For example create a user 'hsmlogin' with primary group 'kmdata'.

Change ownership and permissions of directory /opt/nfast/kmdata/preload so that 'hsmlogin' can enter ("execute") this directory.

Change ownership and permissions of the file /opt/nfast/kmdata/preload/default so that 'hsmlogin' can write to this file and that the www user running the ca CGI script can read it.

Create a login wrapper shell script /usr/local/bin/hsmlogin and assign this as login shell to the 'hsmlogin' user:

#!bin/sh
exec /opt/nfast/bin/with-nfast pause
	

Login as hsmlogin in order to login into the HSM, use Ctrl-C to logout.

<token>
            <name>CA</name>
            <type>nCipher</type>
            <
                if the token support sessions then you can use session and daemo
n too

                session - token will be logged out at end of session
                daemon  - token will be only logged out explicitly
            -->
            <mode>standby</mode>
            <option>
                <name>DEBUG</name>
                <value>0</value>
            </option>
            <option>
                <name>SHELL</name>
                <value>/usr/local/ssl/bin/openssl</value>
            </option>
	    <!-- nFast install directory (required) -->
            <option>
                <name>NFAST_HOME</name>
                <value>/opt/nfast</value>
            </option>
	    <!-- 
	        WRAPPER defaults to '$NFAST_HOME/bin/with-nfast -M'
                You may override this default here if required, normally this 
		value can be left empty.
            <option>
                <name>WRAPPER</name>
                <value></value>
            </option>
	    -->
            <option>
                <name>KEY</name>
                <value>rsa-rootkey</value>
            </option>
[...]
</token>
            

The key name should be the same as reported by /opt/nfast/bin/nfkminfo -k.

Example for creation of a Security World, Operator Cards and CA key.

Assumptions:

Sample Root Key ceremony:

The different names of HTTPS servers are one of the most problematic things in the todays world. Like for many other cryptographic issues in the web there is a standard for servercertificates - RFC 2818 “HTTP over TLS”.

The standard defines that you have to check the subject alternative name for an appropriate entry (DNS or IP see RFC 2459). If this search fails then check the common name in the distinguished name of the certificate.

If you use Microsofts Internet Explorer then you have no problems. The IE is full standard compliant. The problem is Netscape. They use the common name like a regular expression in Unix. The common name can be in the format “(server1|server2).my_domain.org”. The clever ones would argue now that we must simply set the subject alternative name like defined by RFC 2818 and set a normal common name because the subject alternative is checked first. This is a nice idea but Netscape ignores the subject alternative name if it checks the name of the server versus the content of the certificate.

The solution is a mix between RFC 2818 and Netscape behaviour. You must set the common name in the distinguished name like Netscape defines it. After this you must set all DNS-names and the IPs of the server in the subject alternative name. If you do this then all standard compliant browsers will evaluate the subject alternative name first and will ignore the common name in the distinguished name. So the certificate is standard compliant but supports the cruel behaviour of Netscape too.

Before you think this is a perfect solution then please think about aliases. My personal record are 20 different names for one computer which I have to code in a common name. If you think that it is easy then please remember that a common name can only be 64 characters long.

Mailservers usually include SMTP daemons. SMTP servers act as server and client because they work in a hierarchy. Some server softwares like sendmail require that the SMTP server identifies itself as a SMTP client if it contacts another SMTP server. Usually you only want to issue one certificate per server and not one certificate per service and therefore you have to set the extensions for SSL Client and SSL Server like recommended by OpenSSL (please see "man x509" after you installed OpenSSL). If you use sendmail then you can create a server certificate for the SMTP server and an additional client certificate. Sendmail supports two certificates per server or better per daemon.

SSL Client requires the following extensions:

keyUsage = digitalSignature
extendedKeyUsage = clientAuth
nsCertType = client

SSL Server requires the following extensions:

keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth, msSGC, nsSGC
nsCertType = server

msSGC and nsSGC mean Server Gated Crypto from Microsoft and Netscape.

If you want to configure only one certificate per SMTP server then you have to issue certificates which looks like a christmas tree. They have to include all extensions for clients and servers. A configuration can look like this:

keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = clientAuth, serverAuth, msSGC, nsSGC
nsCertType = client, server

If you want to use OpenCA with F-Secure VPN+ then you should bear in mind that this software can only download a CRL via http or ldap. They don't support https and ldaps. This is important if you configure your CRLDistributionPoints in OPENCADIR/etc/openssl/extfiles/*.ext. You can easily fix this problem by using LDAP for CRL-distribution.

Certificates for VPN+ Gateways and Machine certificates should include the DNS name and IP address in the subject alternative name. The certificates for the persons to authenticate them can be contain anything you want. It must only be valid client certificates.

There are two things which must be changed in the configuration files of the servers.

The LDAP configuration must be adapted to the new dc-style. The variables - which you must modify - are basedn and ldaproot. The basedn is the suffix of the LDAP server. The ldaproot is the dn of the user root to bind to the LDAP server. The ldaproot has not to be changed because it is freely configurable by the administrator of the LDAP server.

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

The configuration of the requests must be changed too because they are prepared for the old style. Please read the following example to get an overview of a dc-styled configuration. Please read the section about the CSR configuration to understand how the normal requests can be configured.

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"
                

Please check the installed or prepared files with the name main.html because several HTML files display the suffix of all the DNs.

You can find these files in lib/servers/ra/mails. They are the default templates for the mails which RA Operators can send to the users. They include the suffix of the LDAP server. This suffix is called Dir Root. This suffix must be changed according to the real suffix of your LDAP server.

You must modify the files OPENCADIR/etc/openssl/openssl.cnf and OPENCADIR/etc/openssl/openssl/*.conf. The policy and req sections must be changed to support requests and certificates with subjects in the dc-style. If you don't know how to configure OpenSSL then please read the documentation of OpenSSL.

If you generate the initial request for the CA request then please ignore all the fields for the normal subjectstyle. Simply enter nothing in all field until the software displays the window which show you the complete subject. There you have to enter the complete subject of the CA request. The subject is in RFC 2259 format and all “DC” must be written in big letters because OpenSSL is case sensitive.

The standard data exchange between RA and CA is done via /dev/fd0 (floppy). If the CA and RA are really big then it is recommended to change the data exchange location to a simple file on the local system (for example OPENCADIR/var/tmp/fd0). Please always remember that your apache must be able to access this file. You can also do a chown and set the owner to apache's user.

You also have to edit the dataexchange sections of the .conf files in OPENCADIR/etc/servers/ to point to the new file (edit the lines EXPORT_IMPORT_*_DEVICE).

It is recommended to erase the file after transfers, because the exchange can contain private keys of users.

If the CA and RA are located on different machines in a secure environment with perhaps an offline CA it can be difficult to do the dataexchange via simple files (the files have to be transferred between CA and RA, either via a diskette or ftp (not secure)). OpenCA offers the possibility to do the dataexchange automatically via scp.

The RA exports resp. imports from a file located on the system it is installed on (same as local datatransfer). Thus the RA configuration is the same as for the local dataexchange:

To use scp you must have a working openssh environment with an ssh client on the CA side and an ssh server on the RA side. On the CA side determine the apache home directory by looking at the etc/passwd file (in redhat 8 and 9 this is /var/ww). Do the following:

# 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
            

Now go back to the CA side to edit the files ca.conf and ca_node.conf. The ca_node.conf file already contains a sample scp datexchange section. Comment out the dataexchange section used for local datexchange. Uncomment the scp part and edit it:

After the installation of PostgreSQL there is usually a use postgres. Please use su - postgres to use this identity. After this step you should login into the database with psql. This is possible because the database template1 is always present on new databaseservers. The first real step is the creation of the user openca with create user. After this you logout and login again as the newly created user. Now you create the database openca. After this the database itself is ready for use but you should make the database a little bit more secure. Sometimes the database is already secure then you have problems to issue the psql commands. Please edit the pg_hba.conf first to get the access permissions for the openca user.

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
          

You can restrict the database via PosgrSQL's own configuration. The directory /etc/postgres contains usually a file pg_hba.conf which controls the access to the database. There should only be one entry which looks like follows:

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

This configuration restricts the access to the PostgreSQL database to the database openca via users from localhost. Nobodyelse can access the database now. Please remove all the other access rights - especially the lines which use IP-based trust settings. After the configuration you must restart PostgreSQL. The tables can be created with OpenCA's web interfaces.

Please ensure that the PostgreSQL server is connected to the network. Usually the TCP/IP socket is deactivated.

tcpip_socket = true
          

Sometimes the command of PostgreSQL changes. So please try to run the command \h in psql to see a list of the actual available commands.

PostgreSQL maintains three programs to dump a database - pg_dump, pg_dumpall and pg_dumplo. We describe pg_dump here because we don't like to backup all other databases and we don't like ot backup large objects only. The following options are used:

## 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
          

If we have different backup methods then we have different recovery procedures too. The main difference is that we can use the plain text export directly with psql to import the database. This is possible because this file only includes pure SQL statement. The PostgreSQL specific exports must be processed with pg_restore because they include support for BLOBs too. There is only one command for both PostgreSQL formats because pg_restore detects the used format automatically.

## 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)
          

Oracle databases are accessed via the Perl DBD::Oracle module which uses Oracle OCI client libraries to access database services. Both must be installed on the system.

If the location of the Oracle OCI client shared library is incorrectly configured the OpenCA daemon will not start up properly.

As a consequence, the OpenCA application must be able to locate the Oracle shared library libclntsh.so. Because the client library is usually not installed in a standard library path but rather below the Oracle home directory, the explicit location of this library must usually be configured on the system:

In config.xml set the db_type to 'Oracle'. The db_name, db_user, db_passwd and db_namespace variables may or may not be set according to your configuration (see below).

The Oracle client library requires some environment variables that must be set. As a minimum, the ORACLE_HOME variable must be set. This can be done via the etc/database/DBI.conf configuration file or by sourcing the oraenv file that should have been set up for your Oracle instance by your Oracle DBA.

Depending on your setup it may be useful to source the ora_env file in the OpenCA rc start script like in the following example. In this case, usually no environment variables need to be set up in the DBI.conf file.

#!/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
	

Internal authentication is the classic authentication method and is also the easiest to configure. It is similiar to the methods used for the other database types and requires the explicit configuration of a database user, a password and a database name. The disadvantage, however, is the need to configure the database password in the configuration file which is not always desired. If this is an issue, consider the external authentication method discussed below.

The db_user and db_passwd parameters must be set to the correct username and password values for the OpenCA database. These are identical to the parameters specified in the CREATE USER user IDENTIFIED BY "password"; command that is used to create the user in the Oracle database.

The db_name parameter must be set to the database name configured in the TNSNAMES.ORA configuration file. As it is possible to specify aliases in this file, this may also point to an alias name of the database. In order to verify if your db_name is set correctly run the command tnsping with the db_name parameter as its only argument. The command must be run with the same environment variables that are set for the OpenCA daemon.

If the tnsping command above fails then the database setup is incorrect and must be fixed. Debugging this error is beyond the scope of this document, as there are lots of possible error causes.

If privilege separation should be used (see below) then the db_namespace parameter must be set to the name of the database user owning the OpenCA schema.

Internal authentication is easy to configure but has the significant drawback of requiring a cleartext password for the database user in the configuration file.

External authentiation grants a Unix user access to the database without the need of a password.

This authentication type usually only works for databases running on the local machine. Although it is possible to configure external authentication for remote machines this is not recommended due to security reasons.

In order to set up an Oracle user for external authentication for the Unix user 'wwwdata' use the following Oracle command (the string 'OPS$' must be prefixed to the Unix user name): CREATE USER OPS$WWWDATA IDENTIFIED EXTERNALLY; After the required permissions (e. g. CREATE SESSION) are granted to the user you can test this by trying to access the database using sqlplus / as the user wwwdata. Make sure that the environment (in particular the ORACLE_SID environment variable) is set up properly for this user. The database monitor should now start without a password prompt.

To make this work with your OpenCA setup you must use the Unix user name that is configured as httpd_user in your etc/openca_start startup file.

Assuming the 'OPS$...' user has been created and the database schema is already set up properly, the database configuration for OpenCA must be completed.

This example describes an example setup using Oracle external authentication, privilege separation and script based database setup. When used this way, the database is prepared by the setup script and NOT via the web frontend (CA/Initialization...).

-- 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>
	 

The advantage of DBM files is the use of plain files. You can simply use tar to backup and recover this database.

## 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
          

This link has no function as the user has not logged onto the Public Interface.

This link displays the CA poliy as a web page.

By hitting this link the user is presented with a page titled "Download and Install CA Certificates". This page contains links to CA certificates in various formats.

In order for the user to "trust" certificates generated through OpenCA they must have the Certificate Authority root certificate installed. This page provides an easy mechanism for them to do that. Most users will just click the "CA-certificate in format CRT" and follow the instructions presented to them by their environment (e.g. In IE they have the option to "Open" the file and then "Install Certificate").

Apache Web server administrators would use the link "CA-certificate in format PEM" to download the certificate in the appropriate format for inclusion in the Apache configuration files.

By hitting this link the user is presented with a screen entitled "Download and Install CRLs". This page contains links to certificate revocation lists in various formats.

Many certificate aware clients (like Microsoft Outlook and Netscape Navigator) make use of certificate revocation lists to ensure that certificates are still valid and have not been revoked.

Three links are provided each containing the current CRL in a different format depending on the client. Normal client users would download the CRL in DER format for inclusion in their browser. Web server administrators would use the PEM format. The text format is downloaded as a human readable file.

This link presents the user with a page offering a number of certificate request methods. There are subtile differences between methods which are described below. Each one of the links will take the user to a form. The user will fill in the form and submit the data. The data submitted will be used to create a certificate signing request (CSR) which will go to the certificate Authority to sign and return as a certificate.

The form data has the following fields:

After submitting the form the next set of screens the user sees will depend on the client being used and the type of request selected. After the CSR has been generated and submitted the user will be issued with a Certificate Request ID. This takes the form of an integer number. It is important that the user notes this number down as it is required when retrieving their certificate.

Once the user has requested their certificate the Certificate Authority will process the certificate request. This may involve a face to face identification of the user at the Trust Center. When the certificate has been created the user will be informed by email. This email will also include a Certificate Revocation Number (CRIN), this number should be kept in a safe place as it will be required if the user to needs to revoke their own certificate in the future.

This link provides the mechanism for a user to retrieve the requested certificate and install it in the browser.

The user is presented with a screen and a set of instructions. The most important being that the user must be using the same computer that was used to request the certificate. This is important because both IE and Netscape type browsers need to link the certificate back to the CSR and private keys, this can only be done if the computer that was used to generate the CSR is used to retrieve the certificate.

The user should enter their "Serial Number" in the space provided. The serial number can be:

Upon pressing the "Continue" button, OpenCA attempts to install the certificate into the user's browser. The screens presented to the user depend on the browser being used.

By pressing this link the user is presented with a screen displaying the session server and client certificate details. In most cases this screen will only display the details of the web server certificate used to secure the session (as this screen is not usually access via pages requiring client side authentication).

The user is offered the opportunity to "Sign" a set of data to test the client certificate. Upon pressing the "Sign" button the user is asked to choose the certificate they wish to use to sign the test data. Once they have chosen their certificate they may be asked to enter the pass phrase securing their private keys (this depends on how the user installed the certificate and private keys during key generation time). Once they that completed this the results of the signing process are displayed.

This screen gives the user the opportunity to revoke their own certificate. To do this they need to fill in the form and press "Continue". The Certificate Serial number can be obtained by examining the certificate (using browser functions) or by looking up the certificate in the valid certificates list. The CRIN code was sent to the user at certificate creation time.

Following this link the user is presented with a screen displaying all valid certificates. The screen shows 20 certificates at a time. The user can scroll through the valid certificates by using the "Extra References" link in the top right of the screen.

For each certificate the screen shows:

A user can view the content of a certificate by clicking the serial number of the certificate they wish to view. OpenCA presents a screen displaying the certificate details. At the bottom of this screen are two new links where the user can download the certificate (and install it into their browser) or initiate the revocation procedure (in order to do this the user must have the CRIN number for the certificate being viewed, this number is presented to the certificate holder at certificate creation time, so only the certificate holder can revoke their own certificate).

Clicking this link shows the user a list of all the expired certificates. The screen shows 20 certificates at a time. The user can scroll through the expired certificates by using the "Extra References" link in the top right of the screen.

Clicking this link shows the user a list of all the revoked certificates. The screen shows 20 certificates at a time. The user can scroll through the revoked certificates by using the "Extra References" link in the top right of the screen.

Clicking this link shows the user a list of all the suspended certificates. The screen shows 20 certificates at a time. The user can scroll through the suspended certificates by using the "Extra References" link in the top right of the screen. Suspended certificates are certificates that have had the revocation process started but not yet revoked by the Certificate Authority.

This link provides a screen to enable users to search for a certificate on the system. The screen allows the user to search based on the criteria of name, email or distinguished name. Wild cards are allowed (e.g. Chris*) in each of the fields. You do not have to fill in each of the fields for the search function to find a match, but the more search data you enter the finer the granularity of the search.

Following this link the user is presented with a list of all the current certificate requests at the Registration Authority. The screen shows 20 requests at a time. The user can scroll through the list by using the "Extra References" link in the top right of the screen.

Following this link the user is presented with a list of all the current certificate revocation requests at the Registration Authority. The screen shows 20 revocation requests at a time. The user can scroll through the list by using the "Extra References" link in the top right of the screen.

Pressing this link takes the user to the RA Node interface. From here the RA user can control data flow to and from the RA.

Pressing this link takes the user to the LDAP Administration interface. From here the RA user can control the import and deletion of data from the LDAP Directory (if it is configured).

Pressing this link logs the user out of the interface.

This link shows new CSRs at a specific Registration Authority with a certain Level of Assurance (as specified by the user at certificate request time). The RA Operator chooses the RA and LoA.

The screen shows all the new CSRs.

Each one of the requests must be processed in turn. By clicking the serial number of the request the operator is presented with the details of the request. Four options are then available to the RA Operator:

This screen displays any re-newed certificate siging requests. The list of options is the same as the "New" function.

This screen displays any already processed CSR's

In some circumstances CSR's require two signatures, those requests are displayed here. The functionality is the same as "New" requests.

This section shows new certificate revocation requests. The RA Operator can process them by clicking on the CRR serial number.

This section shows CRRs that have been approved and exported to the CA.

Some CRRs require two signatures before they can be processed, these are displayed here. The RA Operator proccess them like "New" requests.

This link displays the user submitted requests and enables the RA Administrator to presses them.

The following lists of certificate requests can be displayed.

This link displays the user submitted revocation requests and enables the RA Administrator to presses them.

The following lists of certificate revocation requests can be displayed.

This link displays information about certificates in the PKI.

The following lists of certificates can be displayed.

This link displays information about CA certificates in the PKI.

The following lists of CA certificates can be displayed.

This link displays information about CRLs in the PKI.

The following lists of CRLs can be displayed.

This allows the RA Operator to search for a specific certificate based on Name, Email, DN or Role.

This allows the RA Operator to search for a specific certificate signing request based on Name, Email, DN or Role.

This allows the RA Operator to search for certificates expiring in the next "N" days (default 31).

This link takes the user to the main CA Server page. This link is only available if the CA is accessable. In the normal OpenCA configuration the CA is offline and so this link will fail.

This link takes the user to the top Registration Authority page.

This section takes the user to a screen to manage the LDAP server, if one has been configured.

Pressing this link takes the user to the OpenCA public interface. This interface is described elsewhere in this document.

Logs the user out of OpenCA.

If the PKI has been configured with Crypto Tokens holding the CA provate key in an online mode, then this link will stop the token deamon.

This screen is used to set up your OpenCA RA. It is intended that the screen be used once and once only. There are two links:

This link is used to exchange data with other areas of the PKI infrastructure (e.g. CA). Depending on your implementation of OpenCA, only some of the following sections will apply.

This section allows the RA Administrator to backup and recover the OpenCA RA database. It is good practice to perform a data base backup regularly.

Use this link to update the searchable attributes in the database after a software update. *** does anyone have a better explanation of this function ?

Pressing this link sends the "New User" emails out to new users. These emails tell the users that their certificates are aready for collection and gives them a link to the public interface to collect their certificates.

Pressing this link sends new users an encrypted CRIN mail. The CRIN mail contains a pin code that the user must enter when revoking their own certificates. The user should be able to decrypt the message as they would have created the private key during their certificate request process. The message is encrypted using the public key in the certificate request.

I don't know what this does !!!???

This is a link to a housekeeping utility to delete temporary files.

This link runs a function that rebuilds the CA Chain, this is useful if your have a CA hierachy and need to tell the environment about the chain of CA certificates.

This function lets the RA Operator search the log files for log entries of a specific class and level.

I do not know what this does !!!

Pressing this link uploads the CA certificate to the LDAP server. The main screen shows this process and indicates the upload status and success or failure.

Pressing this link uploads the current valid certificates to the LDAP direcrectory and removes revoked certificates from the directory. The main screen shows the status and indicates success or failure.

Pressing this link uploads the current certificate revocation list (CRL) to the LDAP directory. The main screen shows status and indicates success or failure.

This link displays a main screen showing the CA certificate. Clicking on the serial number of the certificate displays a new page showing the certificate details.

As this page is from the LDAP server, there are 4 LDAP related options:

This link displays a list of expired CA certificates.

This link displays a list of the valid certificates. Clicking the serial number of a certificate displays the certificate details.

As this page is from the LDAP server there a 4 LDAP related options:

This link displays a list of the expired certificates. Clicking the serial number of a certificate displays the certificate details.

As this page is from the LDAP server there a 4 LDAP related options:

This link displays a list of the suspended certificates. Clicking the serial number of a certificate displays the certificate details.

As this page is from the LDAP server there a 4 LDAP related options:

This link displays a list of the revoked certificates. Clicking the serial number of a certificate displays the certificate details.

As this page is from the LDAP server there a 4 LDAP related options:

This link displays a list of the certificate revocation lists (CRLs). Clicking the Ver (***is this a bug, I think you should click the CRL serial number ***) of the CRL displays the CRL details lists the revoked certificates.

Clicking on the serial number of a revoked certificate displays the certificate details screen in the same way as pressing the "View Certificates Valid" link.

As this page is from the LDAP server there are 2 LDAP related options:

This link initializes the database. If you use OpenCA::DB then the backend consists of DBM files. If you use OpenCA::DBI then the backend consists of an SQL database. Today we support MySQL, PostgreSQL, IBM DB2 and Oracle. If you need another database then please contact us.

Here we do the keygeneration for the CA. You have to enter the algorithm for the key itself, the algorithm for the encryption of the key and the length of the key. If you entered all the cryptographic paramters then you must enter the passphrase if you use an software token from OpenSSL. If you use a hardware token then you must active this token by the appropriate action.

If you start creating a new certificate request for the CA certificate then you will be prompted for several informations which will be needed to create a certificate of the style “emailAddress=...,cn=...,ou=...,o=...,c=...”. After you entered all the data OpenCA will display the complete subject of the request. This is the last time when you can modify the subject. If you need another style e.g. dc style then you can enter in this field a subject of your kind. After you entered all parameter for the request the private must be activated (usually via a passphrase).

There are two general options for a CA certificate in OpenCA. You can use the CA as a root CA then you have to create a selfsigned certificate or you can setup a sub CA then you have to go to another CA and let it sign your request. Both variation need a different handling.

The last steps can also be done on the interface for the nodemanagement but it is a good idea to do it during the intialization to get a consistent state. The rebuild of the CA chain is necessary to verify digital signatures correctly. If you want to setup a sub CA then you must add all CA certificates of the CA chain in PEM format to the directory OPENCADIR/var/crypto/chain/ before you rebuild the chain.

The really last step is the export of the configuration to the online server(s). The most OpenCA users ignore this step and handle all the communication between the different nodes of the PKI hierarchy via the interface for the node management. If this is you first OpenCA usage then you should export the configuration and import it into the online server.

You have to enter all the informations on the first screen. Please use only keylengths of 512, 1024 and 2048 bits. Other keylengths are actually not supported. It is highly recommended to use at minimum 1024. We recommend that you use 2048 bit because of the last theoretical papers on RSA algorithm. 1024 bits are still safe but it can happen that 1024 will cracked in the next years. If you entered all informations correctly and click ok then you will see a second screen. If you do something wrong then you will see the first screen again.

The second screen shows you the entered informations again. Please check the details. If you click ok then your Internet Explorer will start to generate a new key and request. If the operation succeeds then OpenCA will show you a success page with the serial number of the request. Please remeber this serial before you get in touch with the registration authority.

SPKAC request are used by Netscape, Mozilla and Opera. All three browser support the special tag keygen which is used to generate the private key and the request.

On the first screen you have to enter all the informations. The keylength can be ignored because you must select it on the second screen again because there is no way to set a default. If you entered all informations correctly and click ok then you will see a second screen. If you do something wrong then you will see the first screen again.

The second screen shows you the entered informations again. Please check the details. Now you have to select a keylength. It is highly recommended to use at minimum 1024. We recommend that you use 2048 bit because of the last theoretical papers on RSA algorithm. 1024 bits are still safe but it can happen that 1024 will cracked in the next years. If you click ok then your browser will start to generate a new key and request. If the operation succeeds then OpenCA will show you a success page with the serial number of the request. Please remeber this serial before you get in touch with the registration authority.

There are two methods to submit a pregenerated PKCS#10 - the webinterface or SCEP. SCEP will be covered completely seperate from this section. If you have a PKCS#10 request then you can upload it to the PKI's database. If it is rejected with an errormessage related to the subject (the distinguished name) of the request and you don't know what you are doing wrong then please contact your registration authority. It is possible configure some restrictions to enforce usable requests.

This is not a real request type. It is more a webformular that send an information to the RA that you want a smartcard. The request does not contain any cryptographic informations. It is simply used to collect some first informations about you.

This technology uses the same webpages like Microsoft Internet Explorer or Mozilla but there is a big difference. The browsers will generate the private key and request by themselves and only send them to the server but this interface will only send your entered data to the server and the server will create the key and request. You can use this technology for exaple if you need a certificate for a server and you have absolutely no idea from PKIs or you have a browser like konqueror which can use certificates and keys but is not able to generate requests.

On the first screen you have to enter all the informations. If you choose a keylength then it is highly recommended to use at minimum 1024. We recommend that you use 2048 bit because of the last theoretical papers on RSA algorithm. 1024 bits are still safe but it can happen that 1024 will cracked in the next years. If you entered all informations correctly and click ok then you will see a second screen. If you do something wrong then you will see the first screen again.

The second screen shows you the entered informations again. Please check the details. If you click ok then your data will be send to the server again and the server creates a private key and a request for you. Please remember the PIN. It is used to protect the private key. The databases on the server have no backup from this PIN! If all operations succeeds then OpenCA will show you a success page with the serial number of the request. Please remeber this serial before you get in touch with the registration authority.

The automatic browserdetection is used to determine which mechanism should be used to handle your kind browser. Please use this only if you need a personal user certificate because it really difficult to extract a certificate for a server from a browser and convert it to an appropriate format. If you use an Internet Explorer then please read section for Microsoft client requests. If you use Mozilla, Netscape, Opera or a Mozilla derivate like Phoenix or Firebird then please read the section for SPKAC requests. All other user browser will covered by the section for serverside key and request generation.

There are several fields which you have to fill in. Here is an overview how they will used:

You can directly download a certificate into your browser by entering an appropriate serial number. You must know the serial number of the certificate, of the request or you ID in the batch processors. The browser will be automatically detected by the software. Please remember that this method only works if you generated the private key with the browser and the private key is still in your keystore on computer.

There are three different ways to download a certificate. You can download passive data, or you can download the private key and the certificate or you can install the certificate of another user. If you already have the private key and you want to install a new certificate in your browser then please use the direct download, because this is the only software part which sends special HTML-pages for direct certificate installation.

If you use a Mozilla-like browser and you want to request a certificate from an OpenCA-based PKI then you have to go to the public web interface and klick onto the User area. There you can choose an option request a certificate. After this you can choose between several options (see Figure 7.1).

You can choose the link for the automatic browser detection or more error proof the link for SPKAC-based requests. SPKAC is a special format defined by Netscape. This format is used by Netscape, Mozilla and Opera.

Please fill in your data at the next page. If you submit your data and the software finds no mistakes then you will see the data again. Please check them carefully to avoid additional work for your registration authority. If you now submit the form again then your browser generates a new private key and creates a new request with this key. This request will be send by your browser to the web server from your PKI.

Please print the last page or at minimum write down the displayed informations about the necessary procedure and the displayed serials. These serials are necessary to install the later issued certificate.

There were several problems with Mozilla and signing in the past. The most problems should be fixed if you are using Mozilla 1.7+ or Firefox 0.9.3+.

You must have the complete CA chain of a certificate and you must trust the CA certificate. If these requirements are meet then you can use a certificate to sign an HTML form. This is completely done in Javascript. No additional plugins are required.

The settings for Key Usage, Extended Key Usage and the CDPs is no problem with OpenSSL and we don't describe here in detail how you can configure this in OPENCADIR/etc/openssl/extfiles/domaincontroller.ext. The Basic Constraint and Subject stuff is the same like for every other certificate too.

keyUsage = digitalSignature, keyEncipherment

extendedKeyUsage = clientAuth, serverAuth
            

The Subject Alternative Name is the first difficult thing. OpenSSL 0.9.7 does not support othername. The solution is to encode the GUID in binary format into the subject alternative name.

2.5.29.17=DER:30:32:A0:1F:06:09:2B:06:01:04:01:82:37:19:01:A0:\
12:04:10:01:02:03:04:05:06:07:08:09:10:11:12:13:14:15:16:82:0F:\
64:6E:73:2E:73:6F:6D:65:68:6F:73:74:2E:64:65
            

You can find a detailed description of DER: in openssl.txt of the OpenSSL documentation. 2.5.29.17 is the OID of the subject alternative name. The example GUID is 01020304050607080910111213141516. Please remember that the GUID is allways a 16-byte string and the numbers are hexadecimal encoded. A 16 is a decimal 22. The DNS name is dns.somehost.de (64:6E:73:2E:73:6F:6D:65:68:6F:73:74:2E:64:65). If you need more infos about ASN.1 encodings then please read the ASN.1 specs. We only know that the 10 in front of the GUID and the 0F in front of the DNS name are the length of the values.

The next complicated stuff is the certficate template name but this is a fixed extension so we can copy it from already existing certificates :)

# Certificate Template "DomainController" (bmp string)
1.3.6.1.4.1.311.20.2=DER:1e:20:00:44:00:6f:00:6d:00:61:00:69:00:6e:00:43
:00:6f:00:6e:00:74:00:72:00:6f:00:6c:00:6c:00:65:00:72
            

After you read all these complicated issues you understand perhaps why I can only recommend you to use OpenSSL 0.9.8 if you want to issue certificates for domain controllers. The biggest problem is the subject alternative name which can only be created in binary format which requires to change the extension configuration file of the used role for every issued certificate to encode the correct GUID and DNS name of the domain controller. Nevertheless you can do it with OpenSSL 0.9.7.

The first important note before you start with OpenSSL 0.9.8 - you cannot compile OpenCA with OpenSSL 0.9.8. You must install OpenCA with an OpenSSL 0.9.7 and then you must change the path of the OpenSSL binary from the 0.9.7 binary to the 0.9.8 binary. We know that this is not really comfortable but the header files changed from 0.9.7 to 0.9.8 in an incompatible way and we only migrate our sources if there is a 0.9.8 stable release.

The standard things like Key Usage, Extended Key Usage, Subject, CDPs and Basic Constraints do not change between the different OpenSSL versions. The certificate template name extension of Microsoft must be copied as binary too but it is like the other standardized extensions a static string.

The important improvement of OpenSSL 0.9.8 is the support for othername in the subject alternative name. The new OpenSSL version allows a much easier specification of proprietary extensions even if they are in binary format.

subjectAltName=@altname_sec

[ altname_sec ]
otherName=1.3.6.1.4.1.311.25.1;FORMAT:HEX,OCT:01020304050607080910111213141516
DNS=dns.somehost.de
            

The GUID is the same GUID like in the example for OpenSSL 0.9.7. The big question is now how can I put it into my OpenCA? The answer is short. You have to choose otherName as attribute for the subject alternative name at the RA interface and then you have to enter 1.3.6.1.4.1.311.25.1;FORMAT:HEX,OCT:01020304050607080910111213141516.

We know that it is a big problem for the most admins to enter OIDs and cryptical things like OpenSSL formats. Therefore we added some extra stuff for Microsoft only. You can use the field MS_GUID as a subject alternative name attribute too. There you have only to enter the pure GUID in HEX format. The rest is handled by OpenCA.

Please use the patch for OpenSSL which you can find at our ftp server. The patch othername.tgz includes a fix for Microsoft's othername usage. The following documentation only refers to this patched version of OpenSSL.

OpenCA's role User already includes the required extensions for Microsoft's smartcard logon. Generally you can add the OID for secure email (1.3.6.1.5.5.7.3.4) and other things to such a certificate. The smartcard certificate is not limited to logon. To be more Microsoft-like you can add a certificate template name to the certificates like for domain controllers. This is not required but it looks more nice :)

# Certificate template "SmartcardUser" (bmp string)
1.3.6.1.4.1.311.20.2=DER:1e:1a:00:53:00:6d:00:61:00:72:00:74:00:63:00:61
:00:72:00:64:00:55:00:73:00:65:00:72
            

Now we have to deal with the UPN. This UPN must be placed in the othername of the subject alternative name. If you use the patched option and the othername is supported by the RA configuration then you have to enter 1.3.6.1.4.1.311.20.2.3:UTF8String:account@domain in the value field after you selected otherName. The keyword UTF8String is case-sensitive. If you do all correct then you can now issue a wonderful certificate for smartcard logon.

The only difference between OpenSSL 0.9.8 and 0.9.7 is the handling of the othername. OpenSSL 0.9.8 support this by default without patching. You have to enter 1.3.6.1.4.1.311.20.2.3;UTF8:account@domain. Please notice that OpenSSL 0.9.8 uses UTF8 and not UTF8String.

We know that it is a big problem for normal users to enter OIDs and other cryptical things like which have nothing to do with the UPN. Therefore we added some extra stuff for Microsoft only. You can use the field MS_UPN as a subject alternative name attribute too. There you have only to enter the pure UPN like an emailaddress. The conversion to OpenSSL's format is handled by OpenCA.

OpenCA still includes some statical webpages which will be created the command getStaticPage. If you want to change the content of a static page then please change this file.

There are two possibilites for additional functions - you can write a new one or you can use and already existing one.

There are some scripts which are able to hide references. viewCSR, viewCRR and viewCert are such scripts. There is an option CmdRefs_viewCSR in the config file. There you can specify which functions should be available via this interface. Please remember that this has nothing to do with security! The access control will be handed the normal access control and by the installation of the scripts. Link hiding is no security. The following options are actually supported:

Perhaps a small hint - if you setup more than one public (or any other) interface then please check that configure_etc.sh only configures this interface. If you don't check this then configure_etc.sh will reconfigure the other public interfacers too and this will crash their paths.