Enabling the SSL connector on Spotfire Server

The Spotfire server by default will only allow connections to it via HTTP. The following procedure explains how to enable secure communications to the Spotfire Server via HTTPS.

Using self-signed SSL Certificates

It is possible to create self-signed certificates in a keystore, however this process is not recommended for production environments, and should be restricted to test/development systems.

Note that this method will give trust issues in the browser when connecting to the Spotfire server.

Java utilises a keystore for SSL certificate / private key storage. This is a binary file which is a repository of SSL certificates for use with connectors in Tomcat. Keystores can be managed by using the Java keytool utility, which is located as follows:

To create a keystore with a self-signed certificate, use the keytool command as follows:

This example will create a Java keystore file, keystore.jks

keytool -genkey -alias mycert -keyalg RSA -keypass changeit -storepass changeit -keystore keystore.jks

You will then be prompted with a series of questions about the certificate details. Note that the Common Name (first name, last name) must match the hostname of the spotfire server.

The keystore can be verified as follows:

# keytool -list -keystore keystore.jks
Enter keystore password:
Keystore type: JKS 
Keystore provider: SUN 
Your keystore contains 1 entry mycert, 04-Sep-2015, PrivateKeyEntry,
Certificate fingerprint (SHA1): 29:18:8E:DA:B1:58:2C:D4:C0:56:90:A2:9F:B4:0A:72:FB:C6:9A:67

Using existing certificates

If your organisation has already produced an SSL certificate to be used in Spotfire, the following method can be used to be implement these.

The certificate issued must have a common name (CN) for the primary URL of the spotfire server. Additionally this must be listed as a Subject Alternative Name (SAN), along with any other SAN's that are relevant.

Step 1 - Convert certificates if necessary

A PFX / PKCS12 format certificate is preferred since this may used directly by editing the server.xml.

If only a PEM format certificate and private key pair is available then these must be merged into a PKCS12 certificate first. This can be accomplished via the command line.

On Linux enter the following command (e.g.)

openssl pkcs12 -export -out spotfire.pfx -in spotfire.pem -inkey spotfire.key

On Windows certutil can accomplish the same task.
The private key must have a .key extension and have the same base file name.
E.g. the directory may contain a spotfire.cer and spotfire.key file.

certutil –MergePFX spotfire.cer spotfire.pfx

Step 2 - Edit the server.xml

Navigate to the SSLHostConfig section in the server.xml. Update this section as follows to enable the SSL connector.

<SSLHostConfig certificateVerification="none"
                   sslProtocol="TLS"
                   protocols="+TLSv1.2,+TLSv1.1,+TLSv1"
                   honorCipherOrder="true"
                   ciphers="TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                   TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
                   (Various other ciphers)
                   SSL_RSA_WITH_3DES_EDE_CBC_SHA"
    >
        <Certificate certificateKeystoreFile="./certs/spotfire.pfx" certificateKeystorePassword="changeit" certificateKeystoreType="pkcs12" />
    </SSLHostConfig>    

Important note:
If the private key in the PKCS12 certificate contains a password, then the keystore password must match that one.

Step 3 - Import the root CA and any intermediate certificates

Any root CA certificates or intermediate certificates should be imported into the global truststore "cacerts" which is located in (SPOTFIRE BASE DIRECTORY)/jdk/jre/lib/security/cacerts. The default password for this is "changeit"

This can be done via the keytool command as follows (e.g.): Repeat for each certificate that needs to be imported.

keytool -import -file certificate.pem -alias MyCACert -keystore /opt/tibco/tss/10.3.9/jdk/jre/lib/security/cacerts -trustcacerts -storepass changeit

Creating a certificate with keytool

If your organisation cannot produce SSL certificates for you, an alternate approach is to use Java keystores. This is a propriety format to Java, and PKCS12 certificates should be used wherever possible to simply implementation and administration.

To use a Java keystore the following steps should be performed.

It is assumed that our primary spotfire URL is spotfire.example.com with an alternate name of spotfire1.example.com. Users may also access the Spotfire server via its IP address.

All possible methods of accessing the spotfire server need to be declared, otherwise this will lead to trust warnings in the browser.

1) Generate a new private key. Include the SAN parameter to specify SAN's. This must at least contain the primary hostname (same as the common name) as one SAN.

keytool -genkey -alias spotfire -keyalg RSA -keystore keystore.jks -keysize 2048 -storepass changeit
-ext SAN=dns:spotfire.example.com,dns:spotfire1.example.com,ip:10.4.1.88
What is your first and last name?
  [Unknown]:  spotfire.example.com
What is the name of your organizational unit?
  [Unknown]:  Operations
What is the name of your organization?
  [Unknown]:  Skynet Corp
What is the name of your City or Locality?
  [Unknown]:  Austin
What is the name of your State or Province?
  [Unknown]:  Texas
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=spotfire.example.com, OU=Operations, O=Skynet Corp, L=Austin, ST=Texas, C=US correct?
  [no]:  yes
 
Enter key password for <spotfire>
        (RETURN if same as keystore password):
 
Warning:
The JKS keystore uses a proprietary format. It is recommended to migrate to PKCS12 which is an industry standard format using "keytool -importkeystore -srckeystore keystore.jks -destkeystore keystore.jks -deststoretype pkcs12"

2) Generate a new CSR based on this keystore

keytool -certreq -alias spotfire -keystore keystore.jks -file spotfire.csr
-ext SAN=dns:spotfire.example.com,dns:spotfire1.example.com,ip:10.4.1.88

3) Import any root CA's or intermediary certificates into the global truststore (see step 3 above: Import the root CA and any intermediate certificates)

4) Once a new certificate is obtained, import the PEM format certificate as follows:

 keytool -import -trustcacerts -alias spotfire -file spotfire.pem -keystore keystore.jks

If whilst executing this command you get the error

keytool error: java.lang.Exception: Failed to establish chain from reply

This means that the CA or intermediate certificates are not correct or have not been imported correctly. Check and repeat step 3.

Enforcing TLS connections

It’s possible to make use of Tomcats rewrite engine to force clients to rewrite traffic destined to port 80 to port 443 instead. Note that both ports 80 and 443 must be able to accept incoming connections on the server, so do not block access to port 80.

1.)  In the file server.xml add the following line after the ‘<Context‘ section

This adds a new Valve which enables Tomcats rewrite engine.

<Valve className="org.apache.catalina.valves.rewrite.RewriteValve" />

2.) Create the following file

tomcat/conf/Spotfire/localhost/rewrite.config

3.) The content of this file is as follows (alter the hostname as appropriate)

RewriteCond %{SERVER_PORT} =80
RewriteRule ^/?(.*) https://spotfire.example.com$1 [R,L]

Restart the Spotfire server to make this effective.

Useful commands

Converting a Java keystore to PKCS12 format.

keytool -importkeystore -srckeystore [source keystore] -destkeystore [dest_keystore.pfx] -srcstoretype JKS - deststoretype PKCS12

Convert a DER format certificate to PEM

openssl x509 -in cert.der -out cert.pem