4. Configuration Issues

4.1. How can I configure my httpd.conf for virtual hosts?

Here is a small example for the configuration of a virtual host for OpenCA.

Example E.11. virtual host configuration

<VirtualHost _default_:443>
      ServerName 157.159.100.42:443      
      ServerAdmin pascal.verrecchia@int-evry.fr      
      DocumentRoot /srv/ra/apache/htdocs      
      ErrorLog /usr/local/apache/logs/error_log      
      Options MultiViews Indexes Fol ................
...........

</VirtualHost>
It is important to bind the address and the port this mean that you should include the following statement in you httpd.conf:
BindAddress Your_address_IP:80
Listen 80
You can also add BindAddress * to be sure.

4.2. How can I configure virtual hosts with ./configure?

Here is a small example from an OpenCA user which the developers never planned but it works.

Example E.12. ./configure and virtual hosts

--with-ca-htdocs-url-prefix=http://ca.dskt6807.zhwin.ch \
--with-node-htdocs-url-prefix=http://node.dskt6807.zhwin.ch \
--with-ra-htdocs-url-prefix=http://ra.dskt6807.zhwin.ch \
--with-ldap-htdocs-url-prefix=http://ldap.dskt6807.zhwin.ch \
--with-pub-htdocs-url-prefix=http://pub.dskt6807.zhwin.ch \
The example is from OpenCA 0.9.1. Please do these configuration in config.xml if you use OpenCA 0.9.2 or later.

4.3. I have some users which should not be published in LDAP. Does it be possible with OpenCA?

Yes, it is possible. There is an option LDAPexcludedRoles in the configuration files of the node and the ldap interface. If you add a role there then all certificates which have this role will not be published via the LDAP server.

4.4. Does it be possible to authenticate users by their certificates at the apache before they will be authenticated by OpenCA itself?

Yes, you can edit the httpd.conf in the appropriate way. Please don't do this for the public interface.

Example E.13. Client authentication with mod_ssl

<VirtualHost ra.mycompany.de:4443>

   ServerName ra.mycompany.de
   DocumentRoot /RA/apache/htdocs
   ServerAdmin nicolaie.szabadkai@mycompany.de
   SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown 
downgrade-1.0 force-response-1.0 

   SSLEngine on
   SSLCertificateFile          /RA/ssl.crt/server.pem
   SSLCertificateKeyFile       /RA/ssl.key/key.pem
   SSLCertificateChainFile     /RA/OpenCA/var/crypto/chain/cacert.crt
   SSLCACertificateFile        /RA/OpenCA/var/crypto/cacerts/cacert.pem
   SSLCARevocationFile         /RA/OpenCA/var/crypto/crls/cacrl.pem
   SSLVerifyClient require
   SSLVerifyDepth  10
   SSLOptions +StdEnvVars +ExportCertData +StrictRequire 

   ErrorLog /var/log/httpd/ra.srv.err.log
   CustomLog /var/log/httpd/ra.srv.req.log "%t %h %{SSL_PROTOCOL}x 
%{SSL_CIPHER}x \"%r\" %b" 

   ScriptAlias "/cgi-bin/" "/RA/apache/cgi-bin/"
   <Directory "/RA/apache/cgi-bin">
       AllowOverride None
       Options FollowSymLinks
       Order deny,allow
       Deny from all
       Allow from 10.1.114 10.100.1 10.1.102
       SSLRequireSSL
       SSLRequire ( %{SSL_CLIENT_S_DN_O} eq "MyCompany" \
               && %{SSL_CLIENT_S_DN_CN} =~ m/ramanager?/ )
   </Directory>

   ...
</VirtualHost>
If you no go to the RA then you have to choose a certificate which your browser will use to authenticate you to the Apache. Please note, that for Apache 2.0.* you also need to add in the line "SSLOptions +OptRenegotiate" in order for Apache to re-negotiate the access permissions correctly.

4.5. I want to update my 0.9.2 installation. Is this dangerous?

It is necessary that you update your OpenCA installation from time to time. This can happen if there is a new security advisory or some normal bugs are fixed. Since OpenCA 0.9.1 there are bugfix releases. These releases only update the software. They never touch the configuration. If you have a 0.9.1.3 and you have to update to 0.9.1.4 then simply use the same configuration like for 0.9.1.3. The installation with make never overwrites the etc or var area of your already existing installation. Nevertheless it is strongly recommended to backup your complete installation before you start such critical operations like an update.

4.6. I want update to 0.9.2. How can I update my sql database?

There are two general methods. You can use backup/restore or you add the columns by hand.

If you want to use the first possibility then you have to do the following:
  1. Create a backup from the database with the node interface.

  2. Remove all tables and sequence generators.

  3. Update OpenCA.

  4. Go to the node interface.

  5. Initialize the database.

  6. Go to the recovery page of OpenCA.

  7. Import the database.

  8. Restore OpenSSL's files.

If you want to update the database by hand then you have to do the following:
  1. Login to the database.

  2. alter table request add scep_tid TEXTTYPE;
    alter table log add scep_tid TEXTTYPE;
    alter table request add loa TEXTTYPE;
    alter table certificate add loa TEXTTYPE;
    alter table crr add loa TEXTTYPE;
    alter table log add loa TEXTTYPE;
    TEXTTYPE differs for every database. The following table contains the correct type names for every supported database.

    Table E.1. Texttypes for different databases

    Databasetype
    mysqlTEXT
    Pgtext
    DB2long varchar
    Oraclevarchar2 (1999)
  3. Go to the node interface.

  4. Administration.

  5. Databasehandling.

  6. Update searchable attributes.

4.7. If I run openca-ocspd then I obtain a segmentation fault.

Some releases include an incomplete sample config. You have to add something like this to your ocspd.conf:

Example E.14. OCSP configuration for LDAP

[ OCSPD_default ]
....
dbms		= ocsp_crl

[ ocsp_crl ]
crl_url	= ldap://my.ldap.server
crl_entry_dn	= cn=MyCA,ou=CA,o=MyOrg,c=MyCountry
Alternatively you can use http too:

Example E.15. OCSP configuration for http

[ ocsp_crl ]
crl_url	= http://my.ca-public.server
crl_entry_dn	= /crl/cacrl.crl

4.8. I installed a second public interface, run configure_etc.sh and now are all the paths in the other public interface wrong.

Before you run configure with the changed config.xml for the second public interface you have to reduce the scope of the files in configure_etc.sh to the new interface.

After such a crash you can configure config.xml to the old values, set the paths in configure_etc.sh to the first interface only (!!!) and then run configure_etc.sh again.

4.9. I issue a certificate for a mailserver but sendmail doesn't work and reports an errormessage which includes “reason=unsupported certificate purpose

Please read the notices about SMTP servers in the OpenSSL section of the administration guide. If you only have one certificate for your mailserver then it must include the extensions for SSL servers and SSL clients. The extensions for SSL servers are not enough because SMTP servers act as clients too.

4.10. My (Microsoft) client hangs after it tries to start a secured connection

There are some situations where clients hang after they try to connect to a TLS or SSL secured server. Examples are Microsoft Outlook clients which connect to mail servers which use TLS or Microsoft Internet Explorers which try to connect to a https server.

Usually the certificate contains a CRL distribution point (CDP) which uses https or ldaps as protocol. The result is that the client tries to verify the server certificate and opens a connection to the server which stores the CDP. If this server presents a certificate which contains a CDP with TLS protection then you have a perfect loop. This can also happen if you try to verify a client certificate which includes a TLS or SSL secured CRL distribution point.

There are two solution for this problem. First you can use only http and ldap or other supported protocols for CRL distribution which don't use TLS and SSL. This is not a big security risc because CRLs are protected by the signature of the corresponding CA. Second you use https or ldaps for client certificates but http or ldap for server certificates. This will produce only one loop if the server certificate will be verified.

If you already enrolled an infrastructure and now you are running into problems with hunderds or thousands of client certificates then you should use the second option to solve your problems. If you enroll new certificates for the servers then you have no problems with your endusers - you have not to explain the problems, the installation of new certificates and the reasons why you don't expect such problems. You “only” install some new server certificates and all problems are fixed like a simple network problem.

4.11. Outlook freezes when receiving a signed Mail but worked already fine for some days

The CDP of the certificate from the signature points to a SSL-secured website which was signed by the same CA than the mail certificate. Best solution: Change the CDP to non-https url or a https-url signed by another CA and reissue the mail certificates. If you dont want to reissue all your mail certs it's ok to just change the webservers CDP URL and reissue the webserver certificate.

4.12. During the request generation OpenCA fails and reports a too short textfield

Old versions of OpenCA include a hardwired minimum length for HTML-textfields. The minimum length was three. You can change this limit in basic_csr. New versions of OpenCA can be configured. Please read the “installation and configuration guideSection 4, “CSRs”.

4.13. Can I place my organization's logo on the web interface?

Yes, please check etc/config.xml. There are two options menu_logo_left and menu_logo_right which can be used to place logos in the menuframe. Please be careful with this feature because it can reduce the usability of the software.

4.14. Cannot create new OpenCA tokenobject

The correct errormessage is usually: Please check the configurationfile OPENCADIR/etc/token.xml. The reference to OpenSSL must be correct with the full path and not only openssl.

4.15. How can I use a Luna token with OpenCA 0.9.1

You have to edit two files - OpenCA's ca.conf and Chrysalis-ITS's Chrystoki.conf. First you should configure OpenCA in OPENCADIR/etc/servers/ca.conf. After this you must configure the Luna device. Now OpenCA 0.9.1 should be ready for Chrysalis-ITS LunaCA 3.

4.16. How can I include a complete certificate chain into a PKCS#12 file?

If you enroll a certificate and a private key to a user via file in PKCS#12 format then you usually want to include the complete certificate chain. This is necessary because many software products doesn't work if the chain is incomplete. This can be normal mail programs or VPN clients. The price is no argument in this case.

Otherwise there can be problems if you try to install certificates which are already present at the target system. The worst case is the destruction of already exeisting certificate chains by overwriting an old CA certificate. Therefore OpenCA only includes the CA certificate which issued the enrolled certificate. Nevertheless it is possible to include as many certificate as you want.

Here are the steps to include other certificates into the PKCS#12 file - it is a typical Open Source solution:
  1. Go to OPENCADIR/lib/cmds

  2. Edit send_cert_key_pkcs12. There is a line
    my $cacert = getRequired ('....
                    
    This line defines a file which includes all (CA) certificates which will be included into the PKCS#12 file. Usually we only include our CA certificate. Now you have to setup an individual for your chain.
    my $cacert = "/my/openca/dir/var/crypto/cacerts/blaine.pem";
                    
  3. The next step is to create an individual file for the chain. Now you have to create the file blaine.pem. This file has to include all needed CA certs in PEM format. Please remember to include a begin and end line before and after every CA certificate like for every normal PEM-formatted CA certificate.

4.17. Unknown login type

If you get an errormessage which indicates that there was an unknown login configured then please see Section 3.7, “Conflicting Modules”.

4.18. Cannot initialize cryptoshell but OpenSSL path is correct

If you get an error message that OpenCA cannot initialize the cryptoshell and after the startup no daemon is up - wether the XML cache nor the OpenCA daemon then you have perhaps uncleanly stopped OpenCA's daemons. Please check OPENCADIR/var/tmp/ for any socket files. If OpenCA was killed during shutdown without an explicit shutdown by openca_rc or openca_stop then the still existing socketfiles can block the startup of the daemons. This behaviour is a must to avoid implicit killed daemons if you try to start your daemon twice.

4.19. Emailaddress in subjectAltName but not in CA subject

How can one create a CA certificate so that the DN does not contain the email address, but the alternate name does? You can configure this in OPENCADIR/etc/openssl/openssl.cnf. Set the subject alternative name for the v3_ca to the required emailaddress. Don"t add the emailaddress to the subject of the new request.

4.20. Missing environment variables from SSL

Sometimes users see the following error message: This means originaly that you are using a symmetric key which is shorter than specified in OPENCADIR/etc/access_control/ra.xml. Usually the symmetric cipher must have a length greater or equal 128. If you are using a Mozilla browser then you can klick on the small lock to get informations about the used session cipher. The empty brackets at the end of the errormessage means that there is no keylength specified. This is a perfect indication of a problem with the environment variables. Usually the standard environment variables for SSL are not activated in your Apache. You can confgure it like follows: Please NEVER set the required symmetric keylength to 0. This is security hole.

4.21. Problems with the country name during PKCS#10 requests

Sometimes there are problems with PKCS#10 requests. OpenCA displays an error messages like this one: Please check config.xml. Usually you forgot to configure the country name. If you don't want to run configure_etc.sh again then please check the files in OPENCADIR/etc/servers/ for the configuration of the country code.