12. Configuring SSL Support

Installing and Configuring SSL

You may decide that you want to use SSL to provide additional security for Polarion, especially in cases where you are going to set up LDAP access (see Administrator's Guide, Creating User Accounts). This topic discusses how to configure SSL when using the Apache web server installed and/or configured when you installed Polarion. Everything you need to set up SSL access to Polarion is bundled in the Polarion Windows installation, including default configuration files.

SSL access is configured by standard means in Apache. The only Polarion-specific configuration for SSL is to specify HTTPS protocol for the Subversion repository (described later on).

In-depth documentation on using SSL with Apache is beyond the scope of this Help. For a real understanding of everything described here, and to understand how to actually make an Apache web server secure, it is recommended that you refer to some more sophisticated material on the subject. You will find some links later in this topic that might do for starters.

Warning

Leave the SSLSessionCacheTimeout value at 300 in Apache’s configuration setting to avoid potential broken pipe exceptions.

Configuring SSL on Linux

The general apache2 configuration continues to evolve and varies depending on the distribution. See the links below for updated, distribution specific, instructions.

(All commands and edits should be done with sudo/su).

Unless you've disabled the Resource Traceability feature that's now enabled by default, you will have to import a certificate into your Polarion Java TrustStore.

To point Polarion to your TrustStore, use the following property:

-Djavax.net.ssl.trustStore

If your organization does not have a TrustStore, importing to the Java Key store will also work. See Importing a Certificate to the Java Keystore.

(It must also be done for self-signed certificates.)

Polarion Specific Settings

  1. If you are using a certificate that is not from an authority trusted by Java, import the certificate to the Java keystore, as described in Importing a Certificate to the Java Keystore.

    On Linux, the keytool will be located in the same directory as the version of Java used by Polarion at $JDK_HOME.

  2. Change the Subversion (SVN) protocol setting in Polarion system properties. Edit file $POLARION_HOME$/polarion/etc/polarion.properties, and change the following properties, replacing http with https and removing references to port 80, if present:

    base.url= https://[SERVERNAME] repo= https://[SERVERNAME]/repo/ 

  3. Restart Apache and Polarion.

    If you get an error similar to the following...

    Failed to access the repository https://[SERVERNAME]/repo. Please check its availability, perhaps Apache is stopped? (svn: E175002: Connection has been shutdown: javax.net.ssl.SSLProtocolException: handshake alert: unrecognized_name

    Open the file /etc/apache2/sites-available/ssl and add: ServerName [YOUR SERVER NAME]. For example:

    ServerName polarion.dev.ourdomain.com 

Configuring SSL on Windows

The Open SSL executable is installed at: $POLARION_HOME$\bundled\apache\bin\openssl.exe

Unless you've disabled the Resource Traceability feature that's now enabled by default, you will have to import a certificate into your Polarion Java TrustStore.

To point Polarion to your TrustStore, use the following property:

-Djavax.net.ssl.trustStore

If your organization does not have a TrustStore, importing to the Java Key store will also work. See Importing a Certificate to the Java Keystore.

(It must also be done for self-signed certificates.)

  1. Copy your certificate and keyfile to: $POLARION_HOME$\bundled\apache\conf\.

  2. Activate and configure SSL. Open file $POLARION_HOME$\bundled\apache\conf\httpd.conf in a text editor and...

    • Search for the line containing: LoadModule ssl_module modules/mod_ssl.so and remove the leading comment marker (#). Uncommenting this line activates the SSL module.

    • Search for the line containing Include conf/extra/httpd-ssl.conf and remove the leading comment marker (#).

  3. Optionally deactivate unencrypted http traffic. In $POLARION_HOME$\bundled\apache\conf\httpd.conf, find the line Listen 80 and add a comment marker # at the beginning, leaving the line as: #Listen 80

  4. Set up the certificate file in SSL. Edit file $POLARION_HOME$\bundled\apache\conf\extra\httpd-ssl.conf and search for SSLCertificateFile. Change the path to point to the certificate file. Example:

    SSLCertificateFile "C:\Polarion\bundled\apache\conf\certificate.pem"

  5. Set up the key file in SSL. Edit file $POLARION_HOME$\bundled\apache\conf\extra\httpd-ssl.conf and search for SSLCertificateKeyFile. Change line path to point to the certificate key file. Example:

    SSLCertificateKeyFile "C:\Polarion\bundled\apache\conf\privateKey.key"

  6. If you are using a certificate that is not from an authority trusted by Java (a self-signed certificate, for example), import the certificate to the Java keystore, as described in Importing a Certificate to the Java Keystore.

  7. Change the Subversion (SVN) protocol setting in Polarion system properties. Edit file $POLARION_HOME$\polarion\configuration\polarion.properties, and change the following properties, replacing http with https and removing references to port 80, if present:

    base.url= https://[SERVERNAME] repo= https://[SERVERNAME]/repo/

  8. Restart Apache and Polarion.

    If you get an error similar to the following...

    Failed to access the repository https://[YOUR SERVER NAME]/repo. Please check its availability, perhaps Apache is stopped? (svn: E175002: Connection has been shutdown: javax.net.ssl.SSLProtocolException: handshake alert: unrecognized_name

    Open the file $POLARION_HOME$\bundled\apache\conf\extra\httpd-ssl.conf and add: ServerName [YOUR SERVER NAME]. For example:

    ServerName polarion.dev.ourdomain.com

Additional Resources

Here are some additional resources with information on using https://host -

Importing a Certificate to the Java Keystore

This section is referenced from previous sections on configuring SSL for Linux and Windows. It is important only if you are not using a SSL certificate that is signed by an authority that is trusted in Java. Use of a trusted certificate is preferred and recommended because use of a Java-untrusted certificate (a self-signed certificate, for example) will cause web services communication to fail with SSLHandshakeException. If you opt to use an untrusted certificate, you need to import it into the Java keystore. The general import procedure is described below, followed by examples for Linux and Windows.

To import a certificate to the Java Keystore:

  1. Copy the default keystore $JRE_HOME/lib/security/cacerts as $JRE_HOME/lib/security/jssecacerts

  2. This will leave the original cacerts file available as a backup. JSSE will use the jssecacerts file, if present, instead of cacerts. jssecacerts needs to start as a copy of cacerts, which it overrides rather than extends.

  3. Import the certificate to the jssecacerts keystore using the following command, replacing variables as noted below:

    $JDK_HOME/bin/keytool -importcert -file $CERT -alias $ALIAS -keystore $JRE_HOME/lib/security/jssecacerts -storepass changeit

    • replace $JDK_HOME with your actual JDK home path.

    • Replace $JRE_HOME with your actual JRE home path. (See examples below for Windows and Linux.)

    • Replace $CERT with the path to your certificate the you previously installed to the system.

    • Replace $ALIAS with the preferred alias to be used in the keystore.

    • Note that changeit is the default password for Java's cacerts file. Check whether it has been changed on your system.

  4. When prompted, check the certificate and confirm that is should be trusted. (The prompt to verify and confirm the certificate can be suppressed by adding option -noprompt

Windows Example

The following command should be written as a single line. It must be run as Administrator. If the Java paths on your system contain spaces, they must be contained in a pair of double (straight) quotes, as shown.

"C:\Program Files\Java\jdk1.8.0_121\jre\bin\keytool" -importcert -file C:\Polarion\bundled\apache\conf\certificate.crt -alias labs.polarion.com -keystore "C:\Program Files\Java\jdk1.8.0_121\jre\lib\security\jssecacerts" -storepass changeit 
				

Linux Example (CentOS)

This example following command should be written as a single line:

/usr/java/jdk1.8.0_121/bin/keytool -importcert -file /etc/pki/tls/certs/cert.pem -alias labs.polarion.com -keystore /usr/java/jdk1.8.0_121/jre/lib/security/jssecacerts -storepass changeit
				

Depending on your operating system and version, additional command parameters may be necessary.

Keytool Commands

Here are some potentially useful keytool commands:

keytool -list -keystore %JAVA_HOME%\lib\security\jssecacerts -storepass changeit

keytool -delete -alias mykey -keystore %JAVA_HOME%\lib\security\jssecacerts -storepass changeit

keytool -importcert -help

keytool -help

Configuring Secure Access to the Repository

Polarion's Subversion repository is accessible via HTTPS protocol when SSL is configured for Apache. To set up secure access:

  1. Use a text editor to open the system properties file polarion.properties (follow link for the location).

  2. Locate the repo property. By default the value is set to something like repo=http://localhost:81/repo/ or http://polarion.yourdomain.com/repo/.

  3. Change the protocol in the repo property from http to https.

  4. Make sure the login credentials are correct for HTTPS access.

  5. Restart the Polarion server.