SSL Configuration for Knowledge Center Servers

The Jetty web server supplied with the Genesys Knowledge Center Server and CMS includes a pre-configured, self-signed certificate. This allows you to use HTTPS out of the box in a sandbox deployment. In common case, you should use a certificate issued by a third-party Certificate Authority. The procedures on this page provide examples of ways to load SSL certificates and configure Jetty. These examples may vary depending on your environment.

Loading an SSL Certificate and Private Key into a JSSE Keystore

Important

In a development environment, you can use self-signed certificates, but in a production environment you should use a certificate issued by a third-party Certificate Authority, such as VeriSign.

Prerequisites

• An SSL certificate, either generated by you or issued by a third-party Certificate Authority. For more information on generating a certificate, see http://www.eclipse.org/jetty/documentation/current/configuring-ssl.html.

Start

1. Depending on your certificate format, do one of the following:
   • If your certificate is in PEM form, you can load it to a JSSE keystore with the keytool using the following command:

     keytool -keystore keystore -importcert -alias alias -file certificate_file -trustcacerts
     

     Where:

     keystore is the name of your JSSE keystore.

     alias is the unique alias for your certificate in the JSSE keystore.

     certificate_file is the name of your certificate file. For example, jetty.crt.

   • If your certificate and key are in separate files, you must combine them into a PKCS12 file before loading it to a keystore.
     1. Use the following command in openssl to combine the files:

        openssl pkcs12 -inkey private_key -in certificate -export -out pkcs12_file

        Where:

        private_key is the name of your private key file. For example, jetty.key.

        certificate is the name of your certificate file. For example, jetty.crt.

        pkcs12_file is the name of the PKCS12 file that will be created. For example, jetty.pkcs12.

     2. Load the PKCS12 file into a JSSE keystore using keytool with the following command:

        keytool -importkeystore -srckeystore pkcs12_file -srcstoretype store_type -destkeystore keystore

        Where:

        pkcs12_file is the name of your PKCS12 file. For example, jetty.pkcs12.

        store_type is the file type you are importing into the keystore. In this case, the type is PKCS12.

        keystore is the name of your JSSE keystore.

Important

You will need to set two passwords during this process: keystore and truststore. Make note of these passwords because you will need to add them to your Jetty SSL configuration file.

End

Configuring Jetty

Important

You need to configure "https" port in Knowledge Center Server or CMS application as entry point for secure connection.(See Configuring the Knowledge Center Server Application or Configure the CMS Application)

Start

1. Open the Jetty SSL configuration file in a text editor: Installation Root Directory/etc/jetty-ssl.xml.
2. Find the <New id="sslContextFactory" class="org.eclipse.jetty.http.ssl.SslContextFactory"> element and update the passwords and paths:

   <Configure id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
     <Set name="KeyStorePath">
       <Property name="jetty.base" default="." />/<Property name="jetty.keystore" default="<path to keystore>"/>
     </Set>
     <Set name="KeyStorePassword">
       <Property name="jetty.keystore.password" default="OBF:<obfuscated_keystore_password>"/>
     </Set>
     <Set name="KeyManagerPassword">
       <Property name="jetty.keymanager.password" default="OBF:<obfuscated_keymanager_password>"/>
     </Set>
     <Set name="TrustStorePath">
       <Property name="jetty.base" default="." />/<Property name="jetty.truststore" default="<path to truststore>"/>
     </Set>
     <Set name="TrustStorePassword">
       <Property name="jetty.truststore.password" default="OBF:<obfuscated_keymanager_password>"/>
     </Set>
     <Set name="EndpointIdentificationAlgorithm"></Set>
     <Set name="NeedClientAuth"><Property name="jetty.ssl.needClientAuth" default="false"/></Set>
     <Set name="WantClientAuth"><Property name="jetty.ssl.wantClientAuth" default="false"/></Set>
     <Set name="ExcludeCipherSuites">
       <Array type="String">
         <Item>SSL_RSA_WITH_DES_CBC_SHA</Item>
         <Item>SSL_DHE_RSA_WITH_DES_CBC_SHA</Item>
         <Item>SSL_DHE_DSS_WITH_DES_CBC_SHA</Item>
         <Item>SSL_RSA_EXPORT_WITH_RC4_40_MD5</Item>
         <Item>SSL_RSA_EXPORT_WITH_DES40_CBC_SHA</Item>
         <Item>SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</Item>
         <Item>SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</Item>
       </Array>
     </Set>

   Note: You can run Jetty's password utility to obfuscate your passwords. See http://www.eclipse.org/jetty/documentation/current/configuring-security-secure-passwords.html.

3. Save your changes.
4. Open the Jetty SSL module configuration file, Installation Root Directory/server/modules/ssl.mod (for Knowledge Center Server) or Installation Root Directory/modules/ssl.mod (for CMS), in a text editor.
5. Comment out all properties settings after the line that says etc/jetty-ssl.xml except for lines containing:
   • [files]
   • [ini-template]
6. Save your changes.

End

Choosing a Directory for the Keystore

The keystore file in the example above is given relative to the Jetty home directory. For production, you should keep your keystore in a private directory with restricted access. Even though the keystore has a password, the password may be configured into the runtime environment and is vulnerable to theft.

You can now start Jetty the normal way (make sure that jcert.jar, jnet.jar and jsse.jar are on your classpath) and SSL can be used with a URL, such as https://your_IP:https_port_of_application/