 OCSP with Apache mod_nss
Brian Allshouse
In recent years, there has been a substantial push within the Department of Defense (DoD) and commercial industry to move to a single sign-on solution for their network infrastructures and Web-based assets. There has also been a large influx of products that support certificate-based logins. Unfortunately, most mainstream products are for Windows environments, and we haven't seen much attention given to requirements for Unix-based systems. This has created some interesting problems for Unix systems administrators in the ability to efficiently use certificates (e.g., smartcards, soft certs) to authenticate to Web sites. Because our focus is Unix, the Apache Web server is at the forefront of our discussion.
Although Apache itself can be configured to handle both Certificate Revocation Lists (CRL) and certificate-based authentication, it does not have an automated mechanism for handling the CRLs. CRLs are an important part of the authentication process because they will inform us whether the certificate being presented as an authentication token is still valid (i.e., it hasn't expired or been revoked). Because of the revolving door of personnel that most large organizations face, CRLs for Web servers are becoming increasingly important as well as increasingly cumbersome to manage. A contributing factor to the job of managing these requirements is the fact that CRLs constantly must be updated, in many cases daily, and this normally requires some sort of manual intervention.
In these cases, an Apache Web server that can support the Online Certificate Status Protocol (OCSP) can become an important asset to any organization using single sign-on. Thankfully, our friends at Red Hat created an Apache module called "mod_nss". Red Hat Linux and Solaris 9 systems running Apache 2.0.54 or greater can use "mod_nss" for enabling OCSP support for their Web sites. Extensive testing using Solaris 9 and Fedora Core 5 has proven that "mod_nss" is a direct mapping of Apache "mod_ssl" with the exception that it uses NSS calls instead of OpenSSL calls. When you bring it all together, you get added features such as OCSP, client-certificate authentication, CRLs, hardware accelerators, TLSv1, and SSLv3. Also, "mod_nss" is scheduled to be FIPS certified this year.
Where to Start
You'll need to start by having Apache version 2.0.54 or greater installed on a Solaris 9 server (used for our install). The other prerequisites for building "mod_nss" are NSPR 4.6.4 or above and NSS 3.11.4 or above. OCSP will not work properly with earlier versions of NSS. The packages can be downloaded from:
ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases/
or
ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/
Be sure to download the pre-built binaries for Solaris 9, 32-bit, OPT release (unless you plan on compiling them from source). Once you've downloaded NSPR and NSS, unzip and untar them both in /usr/local/src.
[root@web_server]# > cd /usr/local/src
[root@web_server]# > gunzip nspr-4.6.4.tar.gz
[root@web_server]# > tar xvf nspr-4.6.4.tar
[root@web_server]# > gunzip nss-3.11.4.tar.gz
[root@web_server]# > tar xvf ns-3.11.4.tar
You will also need the NSS and NSPR directories in your library search path (LD_LIBRARY_PATH) to link and run the module. You can just append these paths to your existing LD_LIBRARY_PATH in your environment initialization file.
[root@web_server]# > echo "LD_LIBRARY_PATH=/usr/local/nss-
3.11.4/lib:/usr/local/nspr-4.6.4/lib" >> .kshrc
Next, download the "mod_nss" module from the Fedora Directory Server Project Web site, which is located here:
http://directory.fedoraproject.org/sources/mod_nss-1.0.4.tar.gz
You can also get the latest CVS version by following the instructions found here:
http://directory.fedoraproject.org/wiki/Mod_nss
Building Your Module
You will need to use the --with-nspr and --with-nss options with configure; these options require that the packages be installed in the same parent directory (e.g., /usr/local/nspr, /usr/local/nss). It will look in this parent directory for include/ and lib/, etc. if --with-nss or --with-nspr are not given; configure will look for the NSS and NSPR development packages and use these libraries if they are found.
[root@web_server]# > gunzip mod_nss-1.0.4.tar.gz
[root@web_server]# > tar xvf mod_nss-1.0.4.tar
[root@web_server]# > cd mod_nss-1.0.4
[root@web_server]# > ./configure --with-apxs=/path/to/apxs/ \
--with-nspr=/path/to/nspr/ --with-nss=/path/to/nss/
[root@web_server]# > gmake
[root@web_server]# > gmake install
Running gmake will create an example configuration file called "nss.conf". This is installed during the "make install" process. Also as part of that process, apxs is used to install the "mod_nss" module into Apache. The "mod_nss" shared library is also copied into the appropriate location and Apache's httpd.conf file is updated in order to load the module. The install also attempts to rename the existing ssl.conf file to ssl.conf.old. However, if needed, you can use both "nss.conf" and "ssl.conf" provided they are listening on different ports. The "nss.conf" file is copied into Apache's configuration directory; the install uses apxs to determine where the configuration directory is. You may also need to add the following to your httpd.conf file in order to load "nss.conf".
Include conf/nss.conf
This will tell Apache to load your "mod_nss" configuration file. This file will also be where you add your VirtualServer(s) configuration for your SSL servers.
Create Your Certificate Database and Import Your Certs
There are several tools provided with NSS, which can be very useful while working with your certificates and CRLs. Here is a brief description of them:
certutil -- Used for generating certificate signing requests, installing certificates and managing certificate trust flags.
crlutil -- Used for managing certificate revocation lists (CRLs).
modutil -- Used for managing the PKCS11 modules database (secmod.db). Also used for adding modules and modifying the properties of existing modules.
pk12util -- Used for importing and exporting keys and certificates.
Here are examples of some commands that will be helpful in the configuration process. You'll need to have both the NSPR and the NSS libraries in your "LD_LIBRARY_PATH". Also keep in mind that if you don't use the -d option to specify your database, these commands will default to ~/.netscape.
creating a database: certutil -N -d /path/to/database
listing all your certs: certutil -L -d /path/to/database
extract a server cert in ASCII: certutil -L -n <server-cert> -d
path/to/database -a
extract a cert & key in PKCS#12: pk12util -o server.p12 -n
<server-cert> -d /path/to/database
import cert and key from PKCS#12: pk12util -i server.p12 -n
<key-to-import> -d /path/to/database
Start by creating a directory for your databases:
[root@web_server]# > mkdir /usr/local/apache/nss
Next, download the certificates for your root certificate authorities as well as the current certificate revocation lists. These are usually made available via a secure Web site, but you may need to contact your certificate authority if you don't have Web access to these files, particularly if you're using an outside entity as your CA.
If you must download each individual CA cert and CRL separately, be aware that this can take a significant amount of time depending on how many users your organization has. You'll also need to download the cert from your OCSP responder system. Again, you may need to contact your CA to obtain this information.
To import a CA certificate (this will also create your databases):
[root@web_server]# > certutil -A -n "myca" -t "CT,," \
-d /usr/local/apache/nss -a -i /path/to/cacertificate
The above will need to be executed for each one of your CA certificates. The "myca" above is just a nickname for the CA that your certificate came from. You should give it a nickname that pertains to your CA (e.g., CA1).
To import a CRL:
[root@web_server]# > crlutil -I -n "myca" -t 1 \
-d /usr/local/apache/nss -i /path/to/crlfile
You will need to run this for each individual CRL, and you should provide meaningful nicknames as you did before.
Import the CA cert for the OCSP responder:
[root@web_server]# > certutil -A -n "my_ocsp" -t "CT,," \
-d /usr/local/apache/nss -a -i /path/to/cacertificate
Remember the nickname given to your OCSP responder certificate, because you'll need to add it to your "nss.conf" file later.
Import your server's existing SSL Certificate:
[root@web_server]# > openssl pkcs12 -export -in \
/path/to/certificate -inkey /path/to/keyfile -out \
server.p12 -name "Server-Cert"
[root@web_server]# > pk12util -i server.p12 -d /usr/local/apache/nss
Validate your server certificate:
[root@web_server]# > cd /usr/local/apache/nss
[root@web_server]# > certutil -V -n Server-Cert -u V -d .
certutil: certificate is valid
Edit Your Config File
The following entries should be in your "nss.conf" file. For testing, I kept these outside my VirtualServer declaration.
NSSCertificateDatabase /usr/local/apache/nss
NSSVerifyClient require
NSSOCSP on
NSSOCSPDefaultResponder on
NSSOCSPDefaultURL http://ocsp.example.org
NSSOCSPDefaultName my_ocsp
At the time of writing, NSSOCSPDefaultResponder, NSSOCSPDefaultURL, and NSSOCSPDefaultName are all undocumented features so they will not be in your example "nss.conf" file; you will need to add them manually.
Test Your Installation
Begin by starting or restarting your Apache daemon.
[root@web_server]# > /etc/init.d/apache restart
To complete the process, you need to test your configuration by attempting to connect to your Web site using a client certificate issued by one of the CAs you have loaded into the certificate database on your Web server. If you experience connectivity problems, use your Apache logs for troubleshooting. Another good tool for troubleshooting is "tcpdump".
The Fedora directory server site and the Mozilla site also provide documentation on "mod_nss" and NSS. Additionally, you may want to refer to the RFC for more information on OCSP.
Brian Allshouse is a *NIX Systems Administrator, for Sabre Systems Inc. (http://www.sabresystems.com) a Department of Defense technology contractor. Brian has been supporting the Navy for the past 7 years and does freelance consulting in his spare time. Brian currently works and resides in the Southern Maryland area with his wife, Analisa, and sons, John and Dylan. He can be reached at: bmallshouse@sabresystems.com or brian@brianallshouse.com.
|