Unknown macro: {scrollbar}

Note: This document is only applicable for the CAS server. There is no need to enable SSL on the servlet container running the Pentaho BI Server.

SSL Overview

For the purpose of this document, SSL, and its successor TLS, are identical. SSL provides security in several ways, including:

Verification of server identity.
Encryption of data between client and server.

A frequent source of trouble in setting up SSL is the configuration of the server certificate. Below is a breakdown of the parties involved to get SSL setup.

certificate issuer, also known as certificate authority: A certificate issuer is a company that vouches for the identity of the server. The company vouches for the server by signing the server's certificate with its private key. Because everyone in the world has access to the certificate issuer's public key, they can verify that the certificate was in fact signed by the certificate issuer.
certificate recipient: A certificate recipient is the web server. It's the server to which a user's browser will connect via HTTPS.
browser: The browser receives the certificate from the server and will only proceed without user interaction if the signer of the certificate (the certificate authority) is "trusted." You'll receive a browser warning dialog window if the signer of the certificate is not trusted. This can happen when the certificate is "self-signed." This means that the certificate recipient signed (using its private key) its own certificate. This is only appropriate for development and should not be used in production.

Self-Signed Certificates

Tomcat Setup (Using a Self-Signed Certificate)

Enabling SSL in Tomcat follows the Tomcat documentation. Where the Pentaho setup deviates from the Tomcat documentation, it is documented below.

Creating a Self-Signed Certificate

When creating the certificate, you will be prompted with What is your first and last name? Enter just the word localhost at that prompt. Otherwise the HostnameVerifier will fail.

Trusting the Self-Signed Certificate

Why does one need to trust the certificate? Usually, only clients that are connecting to servers via https need to trust the certificate of the server. And while the client (the web browser in one case) must trust the certificate of the CAS server, there is another client that must trust the CAS server. That client is the web application using CAS services--in this case, the Pentaho BI Server. The Pentaho BI Server connects via https to the CAS server during the ticket validation process. See section 2.6. in the CAS Protocol documentation.

Note: If you do not trust the certificate, you'll get the following error: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Execute the following in %USER_HOME%:

keytool -export -alias tomcat -file tomcat.cer -storepass changeit -keypass changeit -keystore .keystore
Execute the following in %JAVA_HOME%/jre/lib/security:
Note: You might need to run the command below as an administrator. Also, if you are setting up security with the PCI on Windows, the start-pentaho script sets %JAVA_HOME% to the PCI's jre directory: pentaho-demo\jre. So run the command from pentaho-demo\jre\lib\security. Furthermore, if you're on Windows, and you have created the tomcat.cer in C:\Documents and Settings\User, you will need to put double quotes (") around the -file argument because of the spaces in the path name.

keytool -import -alias tomcat -file %USER_HOME%/tomcat.cer -keystore cacerts -storepass changeit
Now confirm that the tomcat entry in %USER_HOME%/.keystore is the same entry that is in %JAVA_HOME%/jre/lib/security/cacerts. Do this by comparing the fingerprints of the two entries.
1. Execute the following in %USER_HOME%:
  
  keytool -list -keystore .keystore
  
  Output of keytool -list -keystore .keystore
  
  Keystore type: jks
  Keystore provider: SUN
  Your keystore contains 1 entry
  tomcat, Mar 1, 2007, keyEntry,
  Certificate fingerprint (MD5): xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx
2. Note the fingerprint of the tomcat entry. Execute the following in %JAVA_HOME%/jre/lib/security:
  
  keytool -list -keystore cacerts
  
  Output of keytool -list -keystore cacerts
  
  Keystore type: jks
  Keystore provider: SUN
  Your keystore contains n entries
  entries omitted
  tomcat, Mar 1, 2007, trustedCertEntry,
  Certificate fingerprint (MD5): xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx
  entries omitted
3. Make sure that the fingerprint for the tomcat entry in cacerts is the same as the tomcat entry in .keystore.

Certificate Authority-Signed Certificates

Using keytool

The instructions given in the Tomcat documentation cover the generation of a private and public key pair, the creation of a signing request, and the importation of the signed certificate into the keystore using keytool. If this is your scenario, consult that documentation. However, what if the generation of the private and public key pair and the creation of the signing request are done using a tool, such as OpenSSL?

Using OpenSSL

When keytool is not used to generate the private and public key pair, there are some extra steps when importing a CA-signed certificate. As a user from a Tomcat mailing list states, "the signed cert is only what Tomcat sends to the browser; it needs the private key in order to decipher the stuff that the browser encrypts using the public key." Because you did not use keytool to generate the private and public key pair, you need to import both the private key and the CA-signed certificate!

The first issue is related to key and certificate format. By default, OpenSSL uses the PEM format. The Tomcat documentation says that, "OpenSSL often adds a readable comments before the key; keytool does not support that." The trick is to convert both the key and certificate to DER format.

Excerpt from http://www.comu.de/docs/tomcat_ssl.htm

Convert the key:
openssl pkcs8 -topk8 -nocrypt -in YOUR.KEY -out YOUR.KEY.der -outform der

Convert the certificate:
openssl x509 -in YOUR.CERT -out YOUR.CERT.der -outform der

The next issue is related to the actual import into the keystore.

Excerpt from Tomcat documentation

You import a certificate for two reasons:

to add it to the list of trusted certificates, or
to import a certificate reply received from a CA as the result of submitting a Certificate Signing Request (see the -certreq command) to that CA.

Which type of import is intended is indicated by the value of the -alias option:

If the alias points to a key entry, then keytool assumes you are importing a certificate reply. keytool checks whether the public key in the certificate reply matches the public key stored with the alias, and exits if they are different.
If the alias does not point to a key entry, then keytool assumes you are adding a trusted certificate entry. In this case, the alias should not already exist in the keystore. If the alias does already exist, then keytool outputs an error, since there is already a trusted certificate for that alias, and does not import the certificate. If the alias does not exist in the keystore, keytool creates a trusted certificate entry with the specified alias and associates it with the imported certificate.

Number 2 above is the closest matching reason, but it assumes that you used keytool to generate the signing request. This assumption doesn't hold true in the case when OpenSSL is used to generate the signing request. In this case, rely on a small Java program that uses the java.security.* API to programmatically add the private key as well as the CA-signed certificate to a keystore.

Consideration for Mozilla Browsers

Some cryptographic algorithms used by Mozilla browsers during SSL connections are not provided by the JVM. The solution is to add other security providers.

If using Sun JRE 1.4.2:

Download the Legion of the Bouncy Castle security provider.
Copy the JAR into jre/lib/ext directory of the JRE running Tomcat.
Edit jre/lib/security/java.security and add security.provider.n=org.bouncycastle.jce.provider.BouncyCastleProvider where n is the highest unused integer available in the file.

If using Sun JRE 1.5.n:

Copy the Sun JCE provider from {Program Files}/Java/j2re1.5.n_nn/lib/ext/sunjce_provider.jar file into the jre/lib/ext of the JRE running Tomcat.

Enabling SSL on the CAS Server