kb69: Using a trusted SSL certificate with Longitude's Web UI

Longitude provides a self-signed certificate when it is installed for basic site encryption. Since this certificate is not signed by a trusted certificate authority, Firefox 3.x may not allow you to view the Longitude Management Console in SSL using the default certificate, and other browsers may display security warnings.

To resolve these issues, you will need to configure the Longitude Management Console to use an SSL certificate from a trusted authority. Heroix is not a certificate provider, and cannot provide a trusted certificate - you will need to create a certificate site request (CSR) and provide this to a certification authority. The authority you purchase the certificate from will usually provide you with specific instructions for creating an acceptable CSR. Longitude uses a Tomcat web server, with a home directory of Longitude\tomcat. The default files used to configure SSL are all in Longitude\tomcat\conf, and are:

In general, the sequence of steps to install a new certificate is:

1. Create a keystore to hold the certificate information
   • Go to a command prompt in the Longitude\tomcat\conf directory, and use the "keytool" command. The syntax would be:

     keytool -genkey -alias {aliasForEntryInKeystore} -keyalg {RSA|DSA} -keystore {nameOfKeystore}.jks

   • for example:

     keytool -genkey -alias longitude -keyalg RSA -keystore longitude.jks

2. After entering this command, you will be prompted for information about the web server:
   • You will be asked to create a password - remember this, you will need it later
   • You will be asked for your "first and last name" - this is the FQDN for the longitude server, and should be the address used to access the Longitude Web UI (e.g. Longitude.heroix.com)
   • you will be asked for you organizational unit (becomes a property of the certificate - not critical)
   • you will be asked for your organization (becomes a property of the certificate - not critical)
   • you will be asked for your City or Locality (becomes a property of the certificate - not critical)
   • you will be asked for your State or Province (becomes a property of the certificate - not critical)
   • you will be asked for your two letter country code (becomes a property of the certificate - not critical)
   • it will repeat the information you've entered, and ask if it's correct - if it's not, take the default "no", and re-enter the information.
   • you will be asked for a key password - the default is the same password you used previously.
3. after running this command, you will now have a keystore file (with a .jks extension).
4. Use the information in the keystore file to create a certificate site request (CSR)
   • run this from the same directory you created the keystore.jks file:

     keytool -certreq -alias {aliasForEntryInKeystore} -file {outputfile}.txt -keystore {nameOfKeystore}.jks

   • from our previous example:

     keytool -certreq -alias longitude -file csr.txt -keystore longitude.jks

   • you will be prompted for the keystore password (the first one you entered above - the one I told you you would need later). The certificate site request will be the csr.txt file.
5. Find a trusted certificate authority, and send them the csr.txt file. They will send you back a certificate.
6. Save your certificate file (usually {domain}.key) to the Longitude\tomcat\config directory.
7. MAKE A BACKUP COPY OF Longitude\tomcat\conf\server.xml!!!!!!!! Keep it someplace safe. You may need to back out of this.
8. Edit the Longitude\tomcat\conf\server.xml file to use your keystore.
   • the SSL section of the file has the following default values:

     <Connector port="7238" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" debug="0" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keystoreFile="./conf/httpsKeys.pkcs12" keystorePass="changeit" keystoreType="PKCS12" />

   • Modify this file to change this section to:
     <Connector port="7238" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" debug="0" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keyAlias="{yourAlias}" keystoreFile="./conf/{yourFile}" keystorePass="{yourPasswrd}" />
   • From our example:
     <Connector port="7238" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" debug="0" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keyAlias="longitude" keystoreFile="./conf/longitude.jks" keystorePass="myPasssword" />

   ***Please note:
   When you purchase a certificate from a trusted authority, they will usually provide instructions for applying that certificate. Please modify Longitude's server.xml file as they specify.
   ****

9. Restart the Web UI
10. After the Web UI has initialized, try to access the Longitude management console using https over port 7238.