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:
...
- 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.
| Anchor | ||||
|---|---|---|---|---|
|
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 the case of Pentaho, there are two web applications--the servlet interface (pentaho.war) and the portlet interface. Both of these web applications connect via https to the CAS server during the ticket validation process. See section 2.6. in the CAS Protocol documentation.
...
- Execute the following in
%USER_HOME%:Panel 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.
Panel keytool -import -alias tomcat -file %USER_HOME%/tomcat.cer -keystore cacerts -storepass changeit
- Now confirm that the
tomcatentry in%USER_HOME%/.keystoreis the same entry that is in%JAVA_HOME%/jre/lib/security/cacerts. Do this by comparing the fingerprints of the two entries.- Execute the following in
%USER_HOME%:Panel keytool -list -keystore .keystore
Panel title 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 - Note the fingerprint of the
tomcatentry. Execute the following in%JAVA_HOME%/jre/lib/security:Panel keytool -list -keystore cacerts
Panel title 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 - Make sure that the fingerprint for the
tomcatentry incacertsis the same as thetomcatentry in.keystore.
- Execute the following in
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!
...
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.
...
- Copy the Sun JCE provider from {
Program Files}/Java/j2re1.5.n_nn/lib/ext/sunjce_provider.jarfile into thejre/lib/extof the JRE running Tomcat.