One of my recent projects was to design a web service-based API for an existing Fusebox 3 application (more on that later). The data exchange has to be digitally signed, which requires working with public and private keys within ColdFusion.

ColdFusion uses the Java keystore within the JRE to handle keys and matters of trust. A keystore is simply a storage location for keys and certificates. Most keystores are physical files protected with a password. By the way, the default password for the ColdFusion keystore is "changeit."

During the prototyping and development phases, I determined that using a self-signed key was faster and easier than having to go through the process of obtaining a "real" signed key.

Note: Self-signed keys are useful for development, but a real key should be used in production environments.

General Syntax

The general syntax for generating a self-signed key pair using the Java keytool utility is:

view plain print about
2 -genkey
3 -alias <alias of key>
4 -keypass <password for alias>
5 -keystore <path/to/keystore>
6 -storepass <keystore password>
7 -dname "cn=<alias>"
8 -keyalg RSA

My project required using the RSA key algorithm. If you do not specify the algorithm to use, the keytool utility uses DSA.

Using the Keytool Utility

Using the keytool utility requires going to the command line, so GUI-lovers beware! I'm going to use the Windows command line in my examples below.

The keytool utility lives in the bin directory of the Java runtime associated with ColdFusion. The default keystore for ColdFusion, named cacerts is in the lib/security directory, so any references to it must be the full path.

view plain print about
1cd c:\coldfusion9\runtime\jre\bin

To list the current contents of the ColdFusion keystore, use the -list switch:

view plain print about
1keytool -list -keystore c:\coldfusion9\runtime\jre\lib\security\cacerts -storepass changeit

Generating a key pair uses the -genkey switch. In this example, I create a RSA key named mykey stored in the cacerts keystore, and then self-sign it:

view plain print about
1keytool -genkey -alias mykey -keypass secureme -keystore c:\coldfusion9\runtime\jre\lib\security\cacerts -storepass changeit -dname "cn=mykey" -keyalg RSA
3keytool -selfcert -alias mykey -keypass secureme -keystore c:\coldfusion9\runtime\jre\lib\security\cacerts -storepass changeit

To share the public key with another application, you will need to export the certificate from the keystore using the -export switch:

view plain print about
1keytool -export -alias mykey -keypass secureme -keystore c:\coldfusion9\runtime\jre\lib\security\cacerts -storepass changeit -file export\file\path\mykey.cer

Importing a key also uses the keytool utility, this time with the -import switch:

view plain print about
1keytool -import -alias the.key.alias -file path\to\certificate.cer -keystore c:\coldfusion9\runtime\jre\lib\security\cacerts -storepass changeit

Note: Once a key exists in the ColdFusion keystore be sure to restart the ColdFusion Application Server.