Page Comparison

{scrollbar}

{quote}*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.{quote} 

h1. SSL Overview

For the purpose of this document, SSL, and its successor [TLS|http://en.wikipedia.org/wiki/Secure_Sockets_Layer], 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.

h2. Self-Signed Certificates


h3. Tomcat Setup (Using a Self-Signed Certificate)

Enabling SSL in Tomcat follows the [Tomcat documentation|http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html].  Where the Pentaho setup deviates from the Tomcat documentation, it is documented below.

h3. 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:TrustingTheCertificate}

h3. 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|http://www.ja-sig.org/products/cas/overview/protocol/index.html].

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

# Execute the following in {{%USER_HOME%}}:
{panel}
keytool \-export \-alias tomcat \-file tomcat.cer \-storepass changeit \-keypass changeit \-keystore .keystore
{panel}
# Execute the following in {{%JAVA_HOME%/jre/lib/security}}:
{quote}*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.
{quote}
{panel}
keytool \-import \-alias tomcat \-file %USER_HOME%/tomcat.cer \-keystore cacerts \-storepass changeit
{panel}
# 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.
## Execute the following in {{%USER_HOME%}}:
{panel}
keytool \-list \-keystore .keystore
{panel}
{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
{panel}
## Note the fingerprint of the {{tomcat}} entry. Execute the following in {{%JAVA_HOME%/jre/lib/security}}:
{panel}
keytool \-list \-keystore cacerts
{panel}
{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_
{panel}
## Make sure that the fingerprint for the {{tomcat}} entry in {{cacerts}} is the same as the {{tomcat}} entry in {{.keystore}}.

h2. Certificate Authority-Signed Certificates


h3. Using keytool

The instructions given in the [Tomcat documentation|http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html] 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|http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/keytool.html]}}.  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|http://www.openssl.org/]?

h3. 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|http://www.mail-archive.com/users@tomcat.apache.org/msg34006.html] 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.
{panel:title=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}}
{panel}
The next issue is related to the actual import into the keystore.
{panel:title=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.
{panel}
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|http://www.comu.de/docs/tomcat_ssl.htm] that uses the {{java.security.\*}} API to programmatically add the private key as well as the CA-signed certificate to a keystore.

h2. 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|http://www.bouncycastle.org] 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.

h2. References

* [Wikipedia on SSL|http://en.wikipedia.org/wiki/Secure_Sockets_Layer]
* [Generate certificate chains for testing Java applications|http://www-128.ibm.com/developerworks/java/library/j-certgen/]
* [http://www.comu.de/docs/tomcat_ssl.htm]
* [OpenSSL|http://www.openssl.org/]
* [SSL Configuration HOW-TO|http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html]
* [keytool|http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/keytool.html]

{children}