Using JDK keytool To Generate Keys and Certs

In a previous post, I stepped through use of IBM's KeyMan GUI to generate SSL keys and certificates, placing them in KeyMan's "token", or as more commonly known, a keystore. I then attempted to use this keystore in both a Windows and Linux deployment of my webapp, and met with mixed success - since I used the Windows version of the KeyMan tool, this worked out OK for the Windows webapp, but not so much for the Linux deployment.

My subsequent attempts to use KeyMan's Unix shell script (km) instead - under a Cygwin environment - were much the same: on deployment, an "Invalid keystore format" exception was issued. Clearly, this is about the difference between DOS and Unix file formats. The next obvious step was to simply execute the km script directly under Linux, foregoing any file encoding or translation issues that might be happening with Cygwin. Here, however, after appearing to generate the key pair, the KeyMan GUI went into some kind of blocking wait - or maybe an infinite loop? a deadlock? There was no way to tell; the GUI simply became unresponsive. Followup exercises to include setting KM_HOME in the environment, unpacking the native library support ZIP file and setting the LD_LIBRARY_PATH to point to them, and etc. all proved fruitless.

Finally, I reverted to using the JDK keytool utility, and - no surprise - this works out just fine in both Windows and Linux (i.e. in terms of generating a keystore that is recognized by the webserver). Here is the script I use to generate things, in both Linux and Cygwin:

######################################
#
# generate-keystore.sh - Generate key and certificate
#
######################################

CN=MyKeystore
OU='Web - Development'
ORG='My Biz Inc.'
COUNTRY=US
ALIAS=MyBizKeystore
PASS=password
KEYSTORE=keystore
CERTFILE=cert
EXPIRY=730

# remove it if it's there
[ -f "$KEYSTORE" ] && /bin/rm $KEYSTORE

# generate the keystore with a self-signed cert and an RSA keypair
$JAVA_HOME/jre/bin/keytool -genkeypair -keyalg RSA \
-dname "cn=$CN, ou=$OU, o=$ORG, c=$COUNTRY" \
-alias $ALIAS -keypass $PASS -keystore $KEYSTORE \
-storepass $PASS -validity $EXPIRY

# export the certificate so we can look at it
$JAVA_HOME/jre/bin/keytool -exportcert -alias $ALIAS -file $CERTFILE -keystore $KEYSTORE -storepass $PASS

# print the certificate
$JAVA_HOME/jre/bin/keytool -printcert -file $CERTFILE

If you bump into this error message in the generate step:

Incorrect AVA format

...you'll want to make sure you didn't embed any commas or other special characters in the values you provide. For example, I started out with an Organizational Unit (OU) of 'My Biz, Inc.' - but that provoked the error message. Embedded dashes and periods are apparently OK, but note that I've enclosed any values with embedded spaces in single quotes. That's more a shell issue than a keytool problem.

If you bump into an error message something like this, in the print-certificate step:

lengthTag=109, too big

...you might be trying to pass in the entire keystore to the printcert command; that's why I export the certificate first in the script above, using just that piece as the argument to print it out.

Using KeyMan To Generate Keys and Certs

This post continues my series around Jetty. Previous posts discuss setting up a basic embedded Jetty application, and then some adjustments to repeat that exercise in a Cygwin environment. My next step is to configure SSL...now, I recall earlier adventures using Java's keytool to manage this, and have hoped for something better. Jetty's documentation pointed me to KeyMan, which is by far a nicer way to go - it provides a decent intuitive GUI to help create, delete, and otherwise manage keys and certificates, among other things. Here's an outline of how to use KeyMan to create a PKCS#12 keystore with a self-signed certificate and public-private key pair:

• Download, install (unpack zip, etc.), read the README.txt. I did nothing with the km.setup file, but did edit the km.bat as instructed. Turns out that, since I'm on cygwin, that wasn't needed; instead, I execute the km program. Click on the "New" icon to create a new "token" (i.e. repository for keys, certs, etc.):

• Choose the PKCS#12 Token from the next dialog, and hit the checkmark ("Complete Dialog") to proceed:

• Next, you need to store a key and a certificate in this token. Select "Actions -> Generate Key" from the token management window that appears:

• The default algorithm is RSA-1024; that's strong enough for my needs. Click the Complete Dialog checkmark...this takes a second to complete, offering a cool little progress bar while you wait. The new key shows up in the All Certificate Items viewport of the token management window; now we need a certificate to go with it. Click "Actions -> Create Certificate...". Self-signed is good enough for my needs. Click checkmark and fill in the fields as needed (only "Your name" is required):

• A verification appears when you check "Complete Dialog" here, with the option to label this certificate. Enter a label if you wish, and again move on with the checkmark:

• Save the token to a file by selecting File -> Save. This first prompts you for a passphrase, then a file location.

Prove to yourself that the keystore (token, repository, whatever) is really there and that you can view it in human-friendly form by first exiting the program, restarting it and selecting the "Open existing..." icon, then "Local resource..." and "Open a file...". Browse to the file location you just saved to, enter the passphrase, and you should see your token listed in the Private Certificates category (in the dropdown). Click right on that item and you'll see all the informational details entered when you created the certificate.

Next, I'll see about using that keystore for my Jetty SSL setup. Meanwhile, here are some useful links around KeyMan, SSL and Jetty's SSL instructions:

Solaris Keytool: http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/keytool.html
Windows Keytool: http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/keytool.html
KeyMan: http://www.alphaworks.ibm.com/tech/keyman
OpenSSL: http://www.openssl.org/docs/HOWTO/
OpenSSL FAQ: http://www.openssl.org/support/faq.html
Jetty SSL: http://docs.codehaus.org/display/JETTY/How+to+configure+SSL