Configuring your On-Premise Contrast Server for HTTPS using a CA signed certificate

Objective

There are several formats in which a Certificate Authority (CA) can provide a signed certificate for use in your On-Premise Contrast Server.  This article details those options and describes the process that should be used to produce the desired end-result: a Java KeyStore (jks) that the Contrast Server's (Tomcat-based) application server will use at runtime. 

Process

Option 1 - You create a KeyStore and provide the CA with a CSR

The process in this case would be to use the Java KeyTool command to create a KeyStore containing a private and public key for a certificate with an alias of contrast-server. In this example the KeyStore is named contrast.jks:

keytool -genkeypair -alias contrast-server -keyalg RSA -keystore contrast.jks

From this KeyStore you would generate a Certificate Signing Request (CSR) (named contrast.csr) like so:

keytool -certreq -alias contrast-server -file contrast.csr -keystore contrast.jks -ext san=dns:your_hostname.your_company.com,ip:10.0.0.1

(Several dns or ip fields may be added as required in order to include these as Subject Alternative Names on the certificate.)

The next step would be to send the resulting CSR file to your CA being sure to retain the JKS file from which the CSR was generated as you will need that in the subsequent step. 

The CA will subsequently provide you with either multiple PEM files with the file extension .crt or .pem (if you open the files and they are readable text then they are PEM files) or a single PKCS #7 file with an extension .p7b, .cer or possibly .crt.  In either case, the provided files need to be imported into the same KeyStore you generate in the original step as follows:

1.  If multiple PEM files were provided, one of these will contain the certificate itself while the others will contain the Root and possibly one or more intermediate certificates.  The certificates must be imported into the KeyStore in a top-down order, with the server certificate itself being imported last and given the same alias that was used when creating the Keystore in the initial step.  For example, if you were provided with root.cer, inter.cer and server.cer you would import as follows:

keytool -import -trustcacerts -alias root -file root.cer -keystore contrast.jks
keytool -import -trustcacerts -alias intermediate -file inter.cer -keystore contrast.jks
keytool -import -trustcacerts -alias contrast-server -file server.cer -keystore contrast.jks

2.  If a single PKCS #7 file was provided (for example certificate.p7b), this file contains the server certificate bundled with all necessary root and intermediate certificates, where appropriate, so can be imported in a single step as follows (again using the same alias that was used when creating the KeyStore):

keytool -import -trustcacerts -alias contrast-server -file certificate.p7b -keystore contrast.jks 

Your Java KeyStore, contrast.jks, is now ready to be used with your Contrast Server as documented here.

Option 2 - The CA provided PEM files and a Private Key

The difference in this case is that no Java KeyStore exists (i.e. you did not generate a CSR).

You will be provided with two PEM files containing the server certificate and the private key.  You may optionally be provided with root and/or intermediate certificates in additional PEM files.  

For example you have server.crt,priv.key and inter.crt. In this case you must use OpenSSL to first combine these into a PKCS #12 file (cert.pfx) and then use KeyTool to convert that into a JKS.  In this example, the certificate is created with an alias of contrast-server and the Java KeyStore is named contrast.jks:

openssl pkcs12 -export -out cert.pfx -inkey priv.key -in server.crt -certfile inter.crt -name "contrast-server"
keytool -importkeystore -srckeystore cert.pfx -srcstoretype pkcs12 -destkeystore contrast.jks -deststoretype jks

(Note: Add additional -certfile options for any additional root or intermediate certificates you were provided with.)

Your Java KeyStore, contrast.jks, is now ready to be used with your Contrast Server as documented here.

Option 3 - The CA provided a PKCS #12 file

Similar to Option 2 (no Java KeyStore exists yet), but in this case you are provided with a single PKCS #12 file (generally with an extension of .p12 or .pfx), for example store.pfx, that contains all of the certificates and the private key in a single file.  In this case you simply need to use KeyTool to convert the file to a JKS:

keytool -importkeystore -srckeystore store.pfx -srcstoretype pkcs12 -destkeystore contrast.jks -srcalias <sourcealias> -destalias contrast-server -deststoretype jks

If the alias name of the certificate in the PKCS #12 file is not known (for example because it was generated by a Windows server), you can retrieve it using the following command:

keytool -v -list -storetype pkcs12 -keystore store.pfx

Your Java KeyStore, contrast.jks, is now ready to be used with your Contrast Server as documented here.