JBoss/Tomcat, Certificates and OpenSSL

A fairly basic HOWTO / cookbook that will attempt to cover:

• Generating certificates (CA, server and client) with OpenSSL
  • Including converting them to PKCS12 format
• Generating key and trust stores for use in JBoss
• Configuring JBoss for server and client (browser) authentication
• Some basic notes about client (browser) configuration
  

<!-- /editable --><!-- /wrapper --><!-- /header -->

NOTE: Use decent passwords or all of this is a waste!!

1. Creating Certificates - OpenSSL

Setup

Configure

Configure OpenSSL openssl.cnf

export SSLDIR=<where your certificates live>/demoCA

mkdir ${SSLDIR}

mkdir ${SSLDIR}/certs
mkdir ${SSLDIR}/crl
mkdir ${SSLDIR}/newcerts
mkdir ${SSLDIR}/private
touch ${SSLDIR}/index.txt
echo "0001" > ${SSLDIR}/serial
echo "0001" > ${SSLDIR}/crlnumber

Usage

Note: This does not seem to work correctly under cygwin rxvt. Use the default cygwin terminal window!

0. Certification Authority (CA) certificate

0.a Generate a key for the CA certificate - this should have a larger keysize as it secures all other certificates
openssl genrsa -des3 -out ./demoCA/private/cakey.pem 2048

0.b Convert the key you generated into a self-signed CA certificate..

The cakey.pem file should reside in the demoCA/private/ directory when it is being used. It must be kept very safe! So perhaps store it on removable media while it is not needed.

@param req Specifies that this produces a Certificate REQuest
@param -new Specifies that this is a NEW request (not a renewal etc...)
@param -x509 Specifies that this produces an x509 Certificate
@param -key <key filename> The file that contains the Key for this request
@returns -out <ca certificate filename> The filename of the CA Certificate

openssl req -new -x509 -key ./demoCA/private/cakey.pem -out ./demoCA/cacert.pem

1. Generate a key

This is the first step to creating any Certificate (be it CA, Client, Server, etc...). It is used to generate the certificate request. You must generate a separate key for each certificate!

@param genrsa Specifies that this should generate an RSA Key
@param -des3 Specifies that this key needs a password
@param <keysize> Specifies how long the key should be 1024 is probably a minimum these days
@returns -out <certificate key filename> The filename of the keyfile
openssl genrsa -des3 -out certificate-key.pem 1024

2. Generate a certificate request

This is a request for a certificate this would be sent to Verisign etc... or used by your own internal CA to generate the certificate

@param req Specifies that this produces a Certificate REQuest
@param -new Specifies that this is a NEW request (not a renewal etc...)
@param -key <key filename> The file that contains the Key for this request
@returns -out <certificate request filename> The filename of the request
openssl req -new -key certificate-key.pem -out certificate-req.pem

3. Generate and sign a certificate (from certificate request)

This builds the certificate from the request using a specific CA. You can set days of validity or a start and end date here too. Otherwise it takes the defaults from the config file

@param x509 Specifies that this produces an x509 Certificate
@param ca Specifies that this is a CA action
@param -req Specifies that this is from a request
@param -in <Request filename> The certificate request used to create this certificate
@returns -out <certificate filename> The filename of the Certificate
openssl ca -in certificate-req.pem -out certificate.pem -notext

3b. Generate and sign a certificate (from certificate request) for a sub CA

Add the extension that this new certificate will be a ca

openssl ca -extensions v3_ca -in certificate-req.pem -out sub-ca-cert.pem -notext

4. Convert a certificate into DER format:

@returns x509 Specifies that this produces an x509 certificate
@param -in <Request filename> The certificate request used to create this certificate
@returns -outform der Specifes that this produces x509 der format file
@returns -out <certificate filename> The filename of the Certificate
openssl x509 -in certificate.pem -outform der -out certificate.der

5. Convert a certificate to pkcs12 format

This procduces a PKCS12 format file that contains both the certificate and the key. This type of file is suitable for installation into the client's browser (eg Microsoft Internet Explorer or Mozilla Firefox etc...)

@param -in <certificate filename> The input client certificate file
@param -inkey <certificate key filename> The input client key file used to generate the orignal certificate request (@see Generate Key)
@param -certfile <CA certificate filename> The CA Certificate to attach as the certificate chain
@param -name "<A nice name for the certificate>" The name displayed in Internet Explorer or other browsers
@returns -out <certificate p12 format output filename>
openssl pkcs12 -export -in certificate.pem -inkey certificate-key.pem \
-certfile ./demoCA/cacert.pem -out client.p12 -name "Name of Certificate"

6. Create a Certificate Revocation List (CRL)

This command creates the initial (empty) CRL for your CA, valid for 90 days. Once this CRL expires, you can simply create a new one.

openssl ca -gencrl -crldays 90 -out ./demoCA/crlFile.pem

To revoke an actual certificate:

openssl ca -revoke certificate.pem

You now need to publish this information in a CRL file:

openssl ca -gencrl -crldays 90 -out ./demoCA/crlFile.pem

You can view the list of revoked certificates in a CRL using the following command:

openssl crl -in ./demoCA/crlFile.pem -text -noout

2. Building Trust and Key Stores

This section describes how to build key and trust stores (ie you do not need to keep a copy of each client certificate in the server).

• Create a CA (see earlier section)
  
• Create a server certificate as above, sign it with the CA certificate and convert to PKCS12 format
• Create any number of client certificates as above, sign them with the CA certificate, convert them to PKCS12 format and send them to the clients and get them to install them in their browsers (see later section on client installation).

2.2 Trust Store

A trust store contains trusted certificates. These can be individual certificates of specific people, or more likely and more useful CA certificates of Authorities that are trusted. ANY client certificates signed by CA certificates that are in the trust store will be trusted. So make sure that there are no other certificates in the trust store (eg Verisign CA) unless you want people with certificates issued by those other CAs to also be able to access your application.

Import the PEM format CA certificate into the server truststore:

    keytool -import -v -keystore server.truststore -storepass 123456 -file ca-cert.pem

Then copy the server.truststore file to the jboss conf directory

cp server.truststore ${jboss.server.home.dir}/conf/

2.2 Key Store

The key store is where the server keeps its keys (certificates that it will present to the client). The client (browser) will need to trust this certificate explicitly or the CA that signed it so as not to display a warning message about "untrusted certificate". So in this case you can either

A) import a server certificate in PEM format (as decribed in 2.2) into the keystore. The client will then need to trust that certificate explicitly - which IMHO is not neat, esp if the server certificate expires at some time.

B) import the CA signed server certificate with the certificate chain PKCS12 format into the keystore. The client then only needs to trust the CA certificate - which if you have sent them their own PKCS12 certificate - will happen automatically at their end (or at least as part of the installation)

Import server certificate (in PKCS12 format) into the server keystore:

Unfortunately keytool cannot handle PKCS12 format certificates so a work around is as follows:

To do this a java class taken from Jetty is used. Download Jetty (if required) and locate the PKCS12Import.java file. This needs to be compiled and then run (from within the jetty-5.1.11RC0/classes/org/mortbay/util directory):

java -classpath ../../../../lib/org.mortbay.jetty.jar org.mortbay.util.PKCS12Import server.p12 server.keystore
Enter input keystore passphrase: <this is the passphrase of the p12 file>
Enter output keystore passphrase: <this is the passphrase of the keystore>

The next two steps are not required but neater if you need to look inside the keystore later. The PKCS12Import class puts the host certificate and key into the keystore with an alias of 1. To rename the alias the following steps are required :
keytool -keyclone -keystore server.keystore -alias 1 -dest <host_name>

Then delete the alias 1 from the keystore using:

keytool -delete -keystore server.keystore -alias 1

To check the content of your keystore
keytool -list -v -keystore server.keystore
This should contain the entry of type keyEntry, which is a chain of certificates.

Then copy the server.keystore file to the conf directory as well

cp server.keystore ${jboss.server.home.dir}/conf/

3. Configuring Tomcat for Authentication

This section describes how to use the key and trust stores created in Section 2.

Where only the CA certificates is stored in the server.truststore (ie you do not need to keep a copy of each client certificate in the server) you need to be able to use Certifcate Revocation Lists (CRLs) see further down for how to implement this. Basically this translates to:

3.1 Allow all signed by CA (via the CA certificate in the trust store)

In jboss-3.2.4+ the tomcat-5.0.x container has its configuration in the jbossweb-tomcat50.sar/server.xml descriptor.

Edit jbossweb-tomcat50.sar/server.xml and uncomment the following section and update the keystoreFile and truststoreFile sections to match the ones you have created:

<!-- SSL/TLS Connector configuration using the admin devl guide keystore-->
<Connector port="8443" address="${jboss.bind.address}"
maxThreads="100" strategy="ms" maxHttpHeaderSize="8192" emptySessionPath="true"
scheme="https" secure="true" clientAuth="true"
sslProtocol = "TLS"
keystoreFile="${jboss.server.home.dir}/conf/server.keystore"
keystorePass="123456"
truststoreFile="${jboss.server.home.dir}/conf/server.truststore"
truststorePass="123456" />

• Start your JBoss server and attempt to reach it at for example: https://localhost:8443/jmx-console/index.jsp
• This should fail.
• Now install a revoked client pkcs12 certificate into your browser.
  
• Attempt to connect again. It should also fail. It may show a nice error it may not depending on the browser.
  
• Now remove the revoked one and install a good client pkcs12 certificate into your browser
  
• Attempt to connect again. It should work this time
  
  • if you have not signed the server certificate with the CA certificate you will be warned of an untrusted certificate.
  • if you have signed the server certificate you will need to also install the CA certificate into your browser.
  • if it is the same CA as your client certificate it should just be trusted without a warning.

3.2 Deny revoked certificates (via the CRL)

For CRL to work in JBoss/Tomcat the ${jboss.server.home.dir}/deploy/jbossweb-tomcat55.sar/tomcat-util.jar must contain the classes:

• org.apache.tomcat.util.net.jsse.JSSE15Factory
• org.apache.tomcat.util.net.jsse.JSSE15SocketFactory
  

To arrange this it is necessary to do some recompilation with a JDK1.5 target. If you do not update this jar CRL will NOT work! A copy of the recompiled jar containing the required libraries is here on an as is basis, (I have no idea if this affects other functions, security concerns, performance etc... so use at own risk, don't run with scisors blah blah).

Create a CRL (see earlier on this page) and copy the CRL into the conf directory so that the server can access it.

    cp crlFile.pem ${jboss.server.home.dir}/conf/server.crlFile

Edit jbossweb-tomcat50.sar/server.xml and include the extra line:

<!-- SSL/TLS Connector configuration using the admin devl guide keystore-->
<Connector port="8443" address="${jboss.bind.address}"
maxThreads="100" strategy="ms" maxHttpHeaderSize="8192" emptySessionPath="true"
scheme="https" secure="true" clientAuth="true"
sslProtocol = "TLS"
keystoreFile="${jboss.server.home.dir}/conf/server.keystore"
keystorePass="123456"
truststoreFile="${jboss.server.home.dir}/conf/server.truststore"
truststorePass="123456"
crlFile="${jboss.server.home.dir}/conf/server.crlFile" />

Restart your JBoss server and attempt to reach it at for example: https://localhost:8443/jmx-console/index.jsp

• This should still work.
• Now remove the good client certificate from your browser and install a revoked client PKCS12 certificate into your browser.
  
• Attempt to connect again. It should now fail. It may show a nice error it may not depending on the browser.
  
• Now remove the revoked one and install a good client PKCS12 certificate into your browser .
  
• Attempt to connect again. It should work again.

NOTES:

Some articles imply that the format for the crlFile is independent of the keystore format. This does not appear to be the case.

Broken Example: Here you have the keystore type set as PKCS12 even though the CRL is a PEM format file (and hence not PKCS12 format). PKCS12 contains the private key as well as the certificate and public key - which is not applicable for the CRL file so this seems to be why it's getting confused.
<Connector port="8443" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="true" sslProtocol="TLS"
crlFile="/ca/crl/crl.pem"
keystoreType="PKCS12" keystoreFile="/ca/ssl/idp.p12"
keystorePass="123456" />

The only way I know of making it work is to remove the keystoreType field and building the keystores as described earlier on this page.

5. Client Configuration

There is a good description of the various issues at play here: http://wiki.mozilla.org/PSM:CertPrompt

Note this is not an extensive configuration guide (as these are more prevalent on the web), just some notes about either of these two browsers.

In general it is fairly easy to install certificates (both client and CA) in both of these browsers. Most users should be able to accomplish this with a reasonable set of instructions. Getting the browser to present the right certificate can be more challenging.

SSL sends a list of CA certificates that are acceptable for Client Authentication. Most HTTP servers build this list automatically whenever that server has CA Certificates which are configured to validate user certificates. Browsers sometimes use this information to present a certificate to the Server.

5.1 MS Internet Explorer

• Extras/Tools --> Internet options --> Inhalt / Content --> Certificates
• Import --> Next --> Certificate Filename --> Password for the certificate
• Allow it to automatically store the certificate (this way CA and client certificates will end up in the correct place)
• Finish
• You will be asked do you trust the CA certificate and do you want to install it. Select Yes.

Some notes:

• If you install a client certificate PKCS12 file that contains also a CA Certificate the CA Certificate will be automatically installed under trusted certificates. (This is the last step in which occurs after you push finish above).
• If there are multiple certificates that are valid for a given domain IE will prompt the user which certificate they would like to use. This can be nice, but if users have revoked or expired certificates they should remove them otherwise these will still appear in the list.
• After restarting IE, it will always prompt for a certificate, even if no certificate is valid.?IE lists all the user certificates without reguard to the certificate list presented to it?. Once IE has a cert selected for the site (or the user as selected no certificate for the site), IE will always use that certificate (or lack of certificate) for that site. The only way to change that is to use the button to clear IE's SSL cert cache. IE will prompt the user even if there is no valid certificate available.
• Tools/Extras --> Internet Options --> Security --> Customise
  • "Don't prompt for client certificate selection when no certificates or only one certificate exists"
  • Turning this On (dont prompt) may be useful for a basic user where only one certificate is available.
  • Turning it Off (do prompt) may provide better debugging chances.

5.2 Mozilla Firefox

• Tools --> Options --> Security --> View Certificates
• Import --> Certificate Filename --> Password for the certificate
• Finish
• The CA certificate will be automatically installed as part of this process.

Some notes:

• If you install a client certificate PKCS12 file that contains also a CA Certificate the CA Certificate will be automatically installed under trusted certificates.
• Select one Automatically
  • If there is only one certificate that is valid this is better as the user is saved an extra selection box.
  • If there are multiple certificates that are valid for a given domain FF will NOT prompt the user which certificate they would like to use. This can be nasty as if users have a revoked or expired certificates as well as a valid one they might not be able to access the site. Users will need to be prompted to remove old certificates properly.
• Ask me every time
  • If there are any certificates that are valid for a given domain FF will prompt the user which certificate they would like to use (even if there is only one valid one). This may be a way to see any problems with certificates on the users machine.

6. References

http://www.openssl.org/
http://www.gagravarr.org/writing/openssl-certs/ca.shtml
http://www.drh-consultancy.demon.co.uk/pkcs12usg.html
http://churchillobjects.com/c/11201g.html

http://wiki.jboss.org/wiki/Wiki.jsp?page=SSLSetup

http://wiki.mozilla.org/PSM:CertPrompt

http://mail-archives.apache.org/mod_mbox/jakarta-tomcat-user/200408.mbox/[e-mail]%3E