Creating the JettyKeyStore for JIS

Folks, I realize that there is a lot of confusion around this complex topic. I’ll try to clarify this in this post.
I’ll refer to Https and SSL as the same thing in this post.

To start with, JIS relies on Java technologies for SSL support so everything you know and love about Java JSSE also applies for JIS.
JIS does not rely on OpenSSL and is therefore not affected by the latest OpenSSL heartbeat bug.

To support Https, JIS requires that a standard Java KeyStore file with the following properties exists:

  1. Name JettyKeyStore (without extension) and placed in the …\classes folder.
  2. Keystore format is JKS.
  3. Certificate format X509.
  4. Keystore password and key password has to be the same. And this password has to be specified in the jacadasv.ini [Http] KeystorePassword setting.

These are usually the default formats when creating the keystore yourself. However, if you are migrating the keystore from another format (such as Microsoft PFX) make sure to specify JKS as the keystore format and X509 as the certificate format.

When launching the JIS server for the first time the server creates two files in case they do not already exist:
JettyKeyStore - a Java keystore with a private/public key pair.
server..cer - certificate file.

The purpose of these files is to provide SSL support out of the box with a test certificates so that you can use Https and SSL during development with browser warning.
However this key store file cannot be used “as is” in production since browsers will display a certificate warning as the certificate generated by JIS is not signed by a certification authority.

Creating a certified JettyKeyStore requires following the procedures documented by Java JSSE, I recommend that you start with understanding the keytool command: http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/keytool.html and work from there using the specific instructions provided by your certificate authority to familiarize yourself with the process.

I’d like to underscore the following common mistakes when generating the KeyStore file:

  1. When you create a keystore and a private key, using the “keytool -genkey” command, make sure to specify the fully qualified server domain name correctly in reply to the mis-leading “What is your first and last name” question. For example “apxdemoenv.softwareag.com” is the fully qualified domain name for the JIS mobile demo site.
    Once the keystore is created, generate a certificate signing request (CSR), using the “keytool -certreq” command, and send it to the certification authority of your choice.

See for example documentation from Verisign https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&actp=CROSSLINK&id=AR227
Note that you can use any certification authority which support Java, JKS and X509 formats for this process.

Here is how your keystore should look when you list it using keytool -list -v

The keystore information:

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

Alias name: apxdemo
Creation date: 11/11/2012
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate1:
Owner: CN=apxdemoenv.softwareag.com, OU=R&D, O=Software AG (Israel) Ltd., L=Or Yehuda, ST=Israel, C=IL
Issuer: CN=apxdemoenv.softwareag.com, OU=R&D, O=Software AG (Israel) Ltd., L=Or Yehuda, ST=Israel, C=IL

  1. Submit your CSR (certificate signing request) for the specific domain to the certificate authority of your choice to get a “Certificate Reply”. This process takes time and costs money. Consult your IT department, as most chances are that they already have a procedure for this in place.

  2. Import the certificate reply
    Using the “keytool -import -trustcacerts” command, import the certification authority primary and secondary intermediate certificates into the same keystore used for generating the CSR then import the certificate reply into the same keystore using the same alias you gave the private key when generating the keystore and the CSR.
    Make sure you receive the message “Certificate reply was installed in keystore” when importing the certificate reply.

See more information: https://search.thawte.com/support/ssl-digital-certificates/index?page=content&actp=CROSSLINK&id=SO15518

Your keystore should now look like this (notice the PrivateKeyEntry and the two intermidiate trustedCertEntry)

keytool -list -keystore ApxDemoKeyStore

Enter keystore password:

Keystore type: JKS

Keystore provider: SUN

Your keystore contains 3 entries

secondary, 12/11/2012, trustedCertEntry,

apxdemo, 12/11/2012, PrivateKeyEntry,

primary, 12/11/2012, trustedCertEntry,

Troubleshooting:
If things does not work as expected, use the -Djavax.net.debug=all Java command line option to generate diagnostic information.
jacadasv.ini
[VMCommandLine]
JavaOptions=-Djavax.net.debug=all

See the following link for more information: http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/ReadDebug.html