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 C.5. 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 C.6. ./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 C.7. 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.

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 C.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 C.8. 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 C.9. 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. Microsoft Smartcard Logon

The original mail was from Dejan Kulpinski which exactly describes for the first time how to establish a Smartcard Logon to Windows 2000 domain using OpenCA certification authority. The mail is present in the mail archives of OpenCA-Users@lists.sf.net.

Warning

Before the original article starts one important note. If you use a TTP certificate for Microsoft domaincontroller then the SMTP based replication of Microsoft doesn't work. Microsoft officially commits this problem but doesn't comment the reasons.

4.14.1. Original Description for 0.9.1

Well the story is pretty long, so I start from the beginning.

Microsoft Knowledge Base Q291010 defines the requirements a DC certificate must have in order to be able to authenticate smartcard logon users. One of them is that key pair must be genarated using RSA/Schannel CSP. The most simple way for doing this is to install Microsoft CA services and to issue a certificate request using a form, where You can choose this CSP and generate a key pair and certificate request in PKCS#10 format.

Then you need to create a role for DC certificate because of specific extensions it must have. The first is the subjecAltName extension that has to have other name = GUID of DC and DNS name = DNS name of DC. Since I have already installed Microsoft CA services, it has generated DC certificate, so the most simple thing for me was to export it to OpenCA machine and parse it with openssl asn1parse utility (I'll send you a detail description if you need) to get a DER formatted subjectAltName. Then I did a hex dump of this DER file and put the result after the "subjectAltName=DER:" in ext file of newly created role. The second is the Certificate Template extension that is specific to Microsoft and unknown to openssl so I didi the same thing with asn1parse and put the result after the "1.3.6.1.4.1.311.20.2=DER:" in ext file (1.3.6.1.4.1.311.20.2 is the OID of Certificate Template extension). You can just use this (but subjectAltName is specific to You so use asn1parse): That is it. Next, you have to generate a smartcard user certificate that also must have some specifics (so new role again). Beside the "CRL Distribution Points" extension that is standard, the "Enhanced Key Usage" extension must contain Cleint Authentication and Smartcard Logon. So you have to put something like where 1.3.6.1.4.1.311.20.2.2 is the OID of SmartCard logon, and 1.3.6.1.5.5.7.3.4 is the OID of SecureMail (if you want to use this certificate for Secure mail too). Certificate Template extension must have a value "SmartcardUser" or "SmartcardLogon (again, with SmartcardUser you can also use the certificate for SecureMail). You can use the this: And the last thing, subjectAltName extension must have other name = Principal name = user_principal_name (for example jsmith@domain.com). To be able to issue the certificates to different smartcard users without the need to create the extension for each, I have used the OpenCA possibility to automatically set user email in subjectAltName (but in this case you have to use jsmith@domain.com as user email, not John.Smith@domain.com because this is not the principal name). Then I put next in smartcard user ext file: where 1.3.6.1.4.1.311.20.2.3 is Principal Name OID. Remember that is works only with openssl version 0.9.8 (you can download a snapshot of 0.9.8-dev version and use it) The last problem is that OpenCA automatically adds the word "email:" before the actual email address. To eliminate this I have been told to remove it in $OPENCA_PREFIX/lib/functions/crypto-utils.lib

4.14.2. Additional Notes for 0.9.2

OpenCA 0.9.2 is much more flexible. You don't need to patch the code to include the othername into the subject alternative name. You have to add "otherName" to the configuration option CSR_SUPPORTED_SUBJECT_ALT_NAMES. You can find this option in OPENCADIR/etc/servers/ra.conf. If you edit the request then you must choose "otherName" as a part of the subject alternative name and the value must be OpenCA 0.9.2 only need configuration adjustments to work with Microsoft Smartcardlogin if you use OpenSSL 0.9.8.

4.15. 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.16. 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.17. 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.