Transport Layer Security (TLS)

GAX employs Transport Layer Security (TLS), a cryptographic protocol that provides security and data integrity for communications over networks such as the Internet. TLS encrypts the segments of network connections at the transport layer from end to end.

GAX supports TLS-enabled connections to the following Genesys servers:

• Configuration Server
• Solution Control Server
• Message Server
• Genesys Deployment Agent

GAX also supports TLS-enabled connections to the GAX database and the LRM database.

For the GAX database connection (either Oracle, Microsoft SQL Server, or PostgreSQL), the database driver and database must also support TLS. For information about configuring your GAX database, refer to the documentation that is specific to the database that you are using:

• Oracle: Oracle Database Advanced Security Administrator's Guide
• Microsoft SQL Server: Use the documentation that came with your database application.
• PostgreSQL: Use the documentation that came with your database application.

For information about TLS and detailed instructions about configuring secure connections, and creating and managing certificates, refer to the Genesys TLS Configuration chapter of the Genesys 8.0 Security Deployment Guide.

Follow the instructions to create a certificate, assign that certificate to a host object (which is required for Genesys Server to run in TLS mode), and configure the use of a secured port for the GAX application.

Next, import the server certificate to the trust storage for GAX to enable authentication for TLS connections.

By default, trust storage is in the JRE folder at the following location:

C:\Program Files\Java\jre6\lib\security\cacerts

The default password is "changeit".

Genesys recommends that you create a separate trust store for GAX.

Perform the procedure below to create a trust store and import the certificates.

Creating a keystore and managing the trust store

Purpose

• To create storage that is separate from the default keystores that come with Java.

Genesys recommends that you do not use the default keystores that are shipped with Java. To ensure a clean separation, you should create a separate storage. If you use a standard cacert file, you must re-import the certificates after each JVM update.

The trust store should contain only the certificates of servers that GAX should trust. If a server sends GAX its certificate during a TLS Handshake, GAX will search for a matching certificate in this keystore. If the certificate is found, the connection is accepted; otherwise, the connection is rejected.

Prerequisites

• Your Keytool should be configured to your path.
• You have JRE or JDK installed.

Start

1. To create an empty keystore, execute the following command lines on your shell: keytool -genkey -alias initKey -keystore trusted.keystore -storetype jks keytool -delete -alias initKey -keystore trusted.keystore
2. Make the trusted.keystore file readable for the user that owns the GAX process.
3. Set a strong password on your keystore.
4. Add a certificate to the trust store by executing the following command line: keytool -import -alias mssql -keystore trusted.keystore -file "cert/demosrc.cer"

   Alias is a name under that the certificate. It can be addressed within the trust store. The option -keystore specifies the keystore file and the option -file specifies the certificate to be imported.

5. To display the whole content of a keystore, execute the following command line: keytool -list -keystore trusted.keystore
6. To display a specific certificate, execute the following command line: keytool -list -v -alias mssql -keystore trusted.keystore
7. To delete a certificate from the keystore, execute the following command line: keytool -delete -alias mssql -keystore trusted.keystore

End

Important

Most systems have multiple trusted stores. You must always use the same store for GAX.

The following options must be set to configure the trust store location for GAX. The options also enable authentication on a global level for all connections that use a secured port.

The best way to set these options is by using the setenv.sh or setenv.bat script:

set JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustStore="D:\certificates\trusted.keystore"
set JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustStorePassword=changeit

Important

GAX does not support Client Authentication. GAX will not authenticate itself by sending a certificate to the server.

Secure Socket Layer (SSL) Security

Genesys Administrator Extension supports Secure Socket Layer (SSL) communications between the GAX server and client-side connections using the web browser interface.

GAX can support connections through HTTP or HTTPS simultaneously. This is defined through configuration of the supported_protocol parameter in the gax.properties file, which can be found in the conf directory of your GAX installation.

Setting up HTTPS for use with Genesys Administrator Extension

1. Create a keystore file to store the private key and certificate for the GAX server.

To create a self-signed certificate, execute the following command:

keytool -keystore keystore -alias gax -genkey -keyalg RSA

As prompted, enter the information required.


2. Start GAX in HTTP-only mode. In the gax.properties file, ensure supported_protocol=http. This is set by default.
3. As a local user (whether in person or via a remote desktop connection), log in to GAX as the local user root.
4. Call the webservice API by entering the following in the address bar of your web browser (for example: http://localhost:8080/gax/api/system/setkeystorepassword?password={password}). The password is stored in an obscured fashion in the gax.properties file. The password specified should be the same as the password specified for the keystore (see Step 1, above).
5. Define the parameter https_port in gax.properties with a port number. The usual default is 443. Please see Configuring GAX Properties for more information.
6. Update the parameter supported_protocol in gax.properties with either https or both.
7. Define the parameter keystore_path in gax.properties with the full path to the location of the keystore file.
8. Restart GAX in HTTPS mode.