ECC Enabling Dogtag

From Dogtag
Revision as of 00:27, 25 March 2008 by Blord (talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


This page describes the process for adding an ECC software token to the Dogtag Certificate System. Although Dogtag does not directly support the ECC cryptosystem, it will be able to take advantage of a third party ECC if you supply one. These plugins need to be PKCS#11 shared libraries.

If you find a bug, please file it in the Bugzilla system.

Package Versions

Dogtag: To enable ECC functionality on the CA, you will need to obtain the latest version of the Dogtag Certificate System. As of this writing, the current version is 1.0.0.

Web Server: If you want to test with a web server, we recommend that you use mod_nss, an Apache plugin utilizing NSS for SSL. Instructions on how to build an ECC enabled mod_nss are located here.

NSS: You'll need a special build of NSS. Instructions are here.

ECC library: You will also need a third party ECC PKCS#11 module. Place the library on the system in a chosen well known location. Example location is /usr/lib.

We have not tested these instructions with HSMs, but we would appreciate feedback if you have successes or problems.

Make sure all the required packages are installed:

rpm -q pki-util pki-common nss nss-tools nss-devel nss-pkcs11-devel mod_nss

Disclaimer: the development and test was only done on RHCS7.3 (that means only on RHEL4) with one third party ECC library.

If you don't have all the packages, use yum to install them before proceeding.

CA Preparation

In order to configure a Dogtag CA for use with ECC, we must first begin with the installation procedure of a Dogtag CA. Here all we want to do is install the RPM's associated with a CA alone. None of the other subsystems come into play with ECC testing. Instructions on how to do this are here: Installing Dogtag.

Once the CA's RPMS have been installed the screen will display a URL that will be used to configure the CA. Note this URL for later but do NOT proceed with the configuration. We must now proceed below to configure the CA for ECC use.

Command Line Tests

Before trying to use the Dogtag CA, you should check to see if you have the right environment setup for exercising the third party ECC library: Assuming that you have obtained a third party module from a specific manufacturer, and you have followed their instructions on setting up the HSM (if it is an HSM) and put their ECC-capable PKCS#11 library under /usr/lib, proceed with the following instructions to setup and test the system. In the following instructions, THIRD_PARTY_MODULE is a name that you make up in order to identify your new module to NSS. THIRD_PARTY_MODULE_TOKEN is the token name that you will see when you list the module as below:

modutil -dbdir <nss db directory> -list THIRD_PARTY_MODULE

Instructions to setup and test the system.

mkdir /tmp/ecc-tests
cd /tmp/ecc-tests
certutil -d . -N
modutil -dbdir . -add THIRD_PARTY_MODULE -libfile /usr/lib/
modutil -dbdir . -nocertdb -changepw "THIRD_PARTY_MODULE_TOKEN"
certutil -d . -G -k ec -q nistp256
 certutil: unable to generate key(s)
 : security library failure.

Note: this command failed because the NSS soft token does not know how to perform ECC operations. This is the expected result.

Now let's test key generation, but we will specify the third party ECC module:

certutil -d . -G -h "THIRD_PARTY_MODULE_TOKEN" -k ec -q nistp256

Let's generate a CSR:

certutil -d . -R -h "THIRD_PARTY_MODULE_TOKEN" -k ec -q nistp256 -s "CN=cfu1003" -a -o req.1003b

If the supports ECC, the last two commands should succeed because we have instructed NSS to use the third party module with the -h command line switch.

CA Configuration

  • Stop the CA as as root as follows:
 /etc/intit.d/pki-ca stop  
  • Note that Dogtag CS maintains a system user called "pkiuser" that assumes privileges over CS files and processes.
  • Next we want to use "root" privileges to prepare a new home directory that will uiltimately belong the the user "pkiuser".
  • Edit /etc/passwd and change pkiuser's home dir to /usr/share/pki/pkiuser. Continuing as "root", change the environment variable HOME to a directory that we will later assign to pkiuser.

Proceed as follows:

cd /usr/share/pki
mkdir pkiuser
export HOME
  • Add the new PKCS#11 module
cd <install root dir>/alias 
# Ex: cd  /usr/var/pki-ca/alias
modutil -dbdir . -nocertdb -add THIRD_PARTY_MODULE -libfile /usr/lib/

(This will create a directory called ".THIRD_PARTY_MODULE" under root's new HOME within the current command shell)

  • Initialize the token's password:
modutil -dbdir . -nocertdb -changepw "THIRD_PARTY_MODULE_TOKEN"

(This will initialize the token's password. This step also creates the file "YourNewModuleuser.db" under $HOME/.THIRD_PARTY_MODULE/YourNewModule)

  • Recursively change everything at and under /usr/share/pki/pkiuser to be owned by pkiuser:pkiuser
cd /usr/share/pki; chown -R pkiuser:pkiuser pkiuser
  • Add the token password to password.conf: e.g.
cd /var/lib/pki-ca/conf
vim password.conf

Add the following line (make sure to add the prefix "hardware-" and escape spaces):


(where "THIRD_PARTY_MODULE_TOKEN" should be the actual module token name, and "yourPassword" should be replaced by the password of the ECC module you just added)

  • Specify the token for signature verification for requests (new feature from the patch mentioned above):
edit <install root dir>/conf/CS.cfg

Add the following line:


Optionally, though not recommended for a production deployment, one can turn off request signature verification by adding the following line:

  • Start the CA.
/etc/init.d/pki-ca start
  • Proceed with the CA's configuration using the configuration wizard URL saved from before. For more information on the configuration process, consult here.
  • When presented with a screen from which to select the module token, select the ECC module token and ECC with desired key strength.

Testing with mod_nss

Build ECC-enabled mod_nss

Before you begin you will need a mod_nss module that is aware of the ECC ciphers. To do this you will need either the mod_nss src.rpm or the mod_nss source tarball mod_nss-1.0.7.tar.gz

If you are rebuilding using the SRPM do the following as root:

  • Extract the package (rpm -ihv mod_nss.<version>.src.rpm).
cd /usr/src/redhat/SPECS
  • Update the %configure section of the spec file and add --enable-ecc to the end of the line.
  • Build the RPM.
rpmbuild -ba mod_nss.spec.

If you are using the source tarball extract it and configure it with something like:

./configure --prefix=/usr --exec-prefix=/usr --bindir=/usr/bin --sbindir=/usr/sbin \
--sysconfdir=/etc --datadir=/usr/share --includedir=/usr/include --libdir=/usr/lib \
--libexecdir=/usr/libexec --localstatedir=/var --sharedstatedir=/usr/com \
--mandir=/usr/share/man --infodir=/usr/share/info --with-nss-lib=/usr/lib \
--with-nss-inc=/usr/include/nss3 --with-nspr-lib=/usr/lib \
--with-nspr-inc=/usr/include/nspr4 --with-apr-config --enable-ecc

Request a server cert

Always make a backup of your certificate database before proceeding, as good practice.

cd /etc/httpd/alias
mkdir saveme
cp *.db saveme
modutil -dbdir . -add THIRD_PARTY_MODULE -libfile /usr/lib/
certutil -d . -R -h "THIRD_PARTY_MODULE_TOKEN" -k ec -q nistp256 -s \
", O=Sfbay Redhat Domain 1023" -a -o certreq.txt

Submit certreq.txt to the CA

After getting the cert back from the CA, save it in the file cert.txt and save the CA cert in ca.txt. Add the certs to the database

certutil -A -d . -n "Server-Cert" -t "u,u,u" -a -h "THIRD PARTY MODULE NAME" < cert.txt
certutil -A -d . -n cacert -t "CT,CT," -a -h THIRD PARTY MODULE NAME" < ca.txt

Configure mod_nss

Edit /opt/fortitude/conf.d/nss.conf Set NSSNickname to "THIRD PARTY MODULE NAME:Server-Cert" Add these to NSSCiphersuite:

+ecdh_ecdsa_aes_128_sha,+ecdh_ecdsa_aes_256_sha,\ +ecdhe_ecdsa_rc4_128_sha,+ecdhe_ecdsa_3des_sha,\

("\" was put in for readability. it's supposed to be one continuous long line)

Restart Apache (/sbin/service httpd restart) and authenticate to the ECC token.

Test by putting this CGI into /var/www/cgi-bin/printenv:

# printenv -- demo CGI program which just prints its environment
print "Content-type: text/plain; charset=iso-8859-1\n\n";
foreach $var (sort(keys(%ENV))) {
  val = $ENV{$var};
  $val =~ s|\n|\\n|g;
  $val =~ s|"|\\"|g;
  print "${var}=\"${val}\"\n";
chmod +x /opt/fortitude/www/cgi-bin/printenv

point a browser to it: e.g.

If you see something like the following line, then your are running your Apache server with an ECC server cert and an ECC-enabled browser:


Tested Browsers

We have tested the following browsers against Dogtag 1.0:

 Firefox 3.0.a7

If you find any bugs when using other browser, please file a bug in Bugzilla.

Trouble shooting:

If ECC token is not logged in (with incorrect password in the log) during configuration:

  1. remove the ECC library in pkiuser's home directory
  2. become root and set home directory to pkiuser's home directory
  3. run modutil to initialize password again (this will create necessary ECC db directories under pkiuser's home directory)

If after ca installation, browser at any point has problem recognize the algorithm (shown in a pop-up), restart the browser and do it again.

For certutil -R, if you see:

certutil: signing of data failed: security library: invalid algorithm.

then most likely you don't have the NSS built with the right flags as described above.

Very often, tomcat does not go away when server is shut down. you need to kill the processes manually.


When customers run into problems, it'd help us to help them if they have useful information. Depending where you suspect the problems are, you can ask them to turn on additional debugging:

Debugging RHCS server

stop server

edit <installation-dir>/conf/CS.cfg

Make sure they have the following parameters:


where debug.level can have values 0 - 10 with 0 being least detailed, and 10 being most detailed.

Debugging NSS (PKCS#11)

Put the following near the top of the file /usr/bin/dtomcat5-rhpki-ca (change the name to match your instance name)

NSS_DEBUG_PKCS11_MODULE="NSS Internal PKCS #11 Module"

Debugging with strace

Prepend the following line with the strace call in /usr/bin/dtomcat5-rhpki-ca (change the name to match your instance name)

To find the right line, search for

elif [ "$1" = "start" ] ; then

and within that elif block, find the "else" block of

"if [ "$1" = "-security" ] ; then" strace -o /tmp/strace.log "$_RUNJAVA" $JAVA_OPTS $CATALINA_OPTS \

Debugging tomcatjss

edit <installation directory>/conf/server.xml

Add the line:


somewhere under the line

<Connector port="9443" maxHttpHeaderSize="8192"

The debug log is in /tmp/tomatjss.log (hardcoded)