Funnelback logo

Documentation

Use SSL for search results

Adding a SSL connector

Search results are served by default over HTTP, on the port chosen during the installation.

To serve search results over SSL you must add a new Connector to the Jetty configuration. Edit the file SEARCH_HOME/web/conf/funnelback-jetty-http.xml and locate the XML section with the name addConnector. There should already been the definition of the non-SSL connector, on the port search.port. You need to add another SSL connector next to it using a similar syntax:

 ...
 <-- Default non-SSL connector below -->
 <Call name="addConnector">
   <Arg>
     <New class="org.eclipse.jetty.server.nio.SelectChannelConnector">
       ...
       <Set name="port"><SystemProperty name="search.port" /></Set>
       ...
     </New>
   </Arg>
 </Call>
 ...
 <-- Add the following SSL connector -->
 <Call name="addConnector">
   <Arg>    
     <New class="org.eclipse.jetty.server.ssl.SslSocketConnector">
       <Set name="Port">443</Set>
       <Set name="maxIdleTime">30000</Set>
       <Set name="keystore"><SystemProperty name="funnelback.installdir" />/web/conf/keystore</Set>
       <Set name="password">funnelback</Set>
       <Set name="keyPassword">funnelback</Set>
       <Set name="truststore"><SystemProperty name="funnelback.installdir" />/web/conf/keystore</Set>
       <Set name="trustPassword">funnelback</Set>
     </New>
   </Arg>
 </Call>
 ...

This example will add a new SSL connector on port 443 to serve search results. After modifying the configuration, you will need to restart Jetty.

Caveats

  • Make sure the port you chose is not already used by the Admin UI. The Admin UI runs over SSL by default on the port you chose during the installation.
  • The SSL connector described above will use the same SSL certificate as the Admin UI. To customise the SSL certifacte, see below.

Changing the SSL certificate (Admin or Public UI)

Funnelback comes with a self-signed certificate for the wildcard host *, and with the password set to funnelback. Funnelback cannot ship with a valid SSL certificate because:

  • SSL certificates are tied to a specific hostname, and the hostname of the Funnelback server(s) cannot be known in advance
  • Getting a valid certificate from a certification authority cannot be automated: The certification authority should be known in advance (whether it's an internal certification authority that runs on the local network, or a third-party certification authority) and the certificate request require human validation.

For this reason, a warning will always be displayed by your web browser unless you install a valid certificate on the Funnelback server. To use your own SSL certificate for either the Admin UI or Public UI, please follow these instructions.

It's assumed that you obtained your certificate from a valid certification authority, and that the certificate is already in the PKCS12 format (the OpenSSL tools suite are usually used to convert SSL certificate formats). Most of the steps are using the keytool command-line program provided with Java (Under SEARCH_HOME/linbin/java/bin/ on Linux and SEARCH_HOME\wbin\java\bin\ on Windows).

The first step is to inspect your custom SSL certificate and retrieve its alias:

keytool -list -keystore ssl-pkcs12-certificate.pfx -storetype PKCS12

Keystore type: PKCS12
Keystore provider: SunJSSE

Your keystore contains 1 entry

funnelback-ssl, Feb 17, 2012, PrivateKeyEntry,
Certificate fingerprint (SHA1): B3:04:98:FC:79:89:3D:CE:D2:D8:14:07:9E:36:72:D9:31:81:9B:E2

The alias is listed towards the end. In this example it's funnelback-ssl

The next step is to generate a Java keystore containing your certificate:

 keytool -importkeystore -deststorepass <KEYSTORE_PW> -destkeypass <KEY_PW> -destkeystore target-keystore.jks -srckeystore ssl-pkcs12-certificate.pfx -srcstoretype PKCS12 -srcstorepass <CERT_PW> -alias funnelback-ssl
KEYSTORE_PW
This is the password of the new Java keystore that will be created. A keystore can contain multiple keys, each keys having their own password. However usually the keystore will contain only one key and the same password as the key password is used.
KEY_PW
This is the password for the specific SSL key.
target-keystore.jks
This is the location of the resulting Java keystore file
ssl-pcks12-certificate.pfx
The path to your custom PKCS12 SSL certificate
CERT_PW
The password of your custom SSL certificate
custom-alias
Descriptive name for the key (Can be anything)
funnelback-ssl
Use the alias found with the previous command

This command should generate a file name target-keystore.jks. This file is containing your SSL certificate ready for Java to use. The last step is to tell Jetty to use this keystore instead of the default Funnelback one. Edit SEARCH_HOME/web/funnelback-jetty-http.xml for the Public UI or SEARCH_HOME/web/funnelback-jetty-https.xml for the Admin UI, and locate the SSL connector definition with the class org.eclipse.jetty.server.ssl.SslSocketConnector:


<New class="org.eclipse.jetty.server.ssl.SslSocketConnector">
  <Set name="Port">...</Set>
  <Set name="maxIdleTime">30000</Set>
  <Set name="keystore"><SystemProperty name="funnelback.installdir" />/web/conf/target-keystore.jks</Set>
  <Set name="password">funnelback</Set>
  <Set name="keyPassword">funnelback</Set>
  <Set name="truststore"><SystemProperty name="funnelback.installdir" />/web/conf/target-keystore.jks</Set>
  <Set name="trustPassword">funnelback</Set>
</New>

The parameters you need to change are:

keystore
The path to the keystore file generated previously (target-keystore.jks). This file can be inside SEARCH_HOME/web/conf/ or elsewhere, in which case you need to remove the <SystemProperty name="funnelback.installdir" /> reference and use the absolute path.
keyPassword
This is the password for the key, KEY_PW in the previous command
trustStore
Same value as keystore
trustPassword
Same value as keyPassword

top ⇑