Jump to: navigation, search

What You Need

Before starting to configure your secure connections with TLS, you must have done the the following:

  • Generated certificates, with associated private and public keys, and CRLs.
  • Made certificates available for applications on hosts.
  • Installed the Genesys Security Pack, if you are using native applications on Unix platforms.

Each of these requirements are described below.

TLS Certificates

TLS certificates must be generated and installed appropriately on any host that runs Genesys applications that utilize TLS secure connections. A certificate is generated and signed using a certification authority (CA) entity, which is able and authorized to issue certificates signed with its own name.

Important
Genesys strongly recommends that you use the same CA to generate all the certificates for your contact center environment.

The actual process of certificate generation in a specific environment is highly dependent on the security policies of your IT organization and tools used, and can, therefore, be different from the process described in this chapter. Genesys recommends that you consult with your network administrator before generating certificates for secure data exchange between Genesys components.

Certificates can be purchased from well-known certificate authorities, such as VeriSign. Certificates can be generated and self-signed on Linux using the OpenSSL tool, assisted by scripts distributed with the Genesys Security Pack. Windows Certificate Service can be used to generate and sign certificates. You may self-sign your certificates, or you Windows Certificate Service might already be used in your organization as a part of a chain of trusted authorities.

Generated and signed certificates must also be installed to be used by Genesys components. This procedure differs depending on the host operating system on which the certificates are installed.

Tip
TLS certificates can be stored and used in a number of different formats. Different TLS implementations use different certificate formats. Self-signed certificates, generated using OpenSSL and Genesys Security Pack, can be used across all supported Genesys implementations. For certificates obtained from other sources, you must confirm that their format is compatible with your target platforms.


Recommended Certificate Properties

When retrieving or generating a certificate, the following properties are recommended to ensure the connections using this certificate are as secure as possible:

[+] Show properties

Generating Certificates using OpenSSL and Genesys Security Pack

The OpenSSL toolkit can be used to set up a CA infrastructure and issue self-signed certificates. Use this method if certificates are to be utilized in a mixed environment, including Windows and Linux hosts, along with Java PSDK-based components.

Scripts distributed with Genesys Security Pack simplify CA creation and certificate generation. These scripts use the SHA-256 message digest algorithm by default, but allow fallback to SHA-1 if required. Genesys recommends that you do not use SHA-1.

Prerequisites

To generate certificates, you need an OpenSSL command line tool installed on the system. Obtain the most recent valid binary distribution from the OpenSSL official website.

To utilize Genesys Security Pack scripts, you need a set of standard GNU console utilities, including bash, awk and touch.

Generation Process

1. Create a CA directory in which CA files—scripts, configuration files, and generated certificates—will be stored.
2. Copy the create_ca.sh and create_cert.sh scripts from the installation package to the CA directory that you just created. Make sure that these scripts have executable permissions.
3. Run the create_ca.sh script from the bash shell by specifying the proper parameters (described in the table below) in the following command line:
create_ca.sh [-keySz KEY_SIZE] [-dgst DIGEST_ALGORITHM] [-time VALID_TIME] -CN COMMON_NAME [-E EMAIL] [-OU ORG_UNIT] [-O ORGANIZATION] [-L LOCALITY] [-S STATE] [-C COUNTRY]

The parameters are described in the following table:

[+] Show table


For example:

create_ca.sh -CN “Basic Certification Authority” -E “youremail@yourdomain.com” -OU “Department” -O “Genesys Telecommunication Labs” -L “Daly City” -S CA -C US
4. Generate certificates as required. To generate a certificate for a particular host computer, go to the CA directory in which the CA files are stored, and run the create_cert.sh script from the bash shell by specifying the parameters (see the following table) in the following command line:
create_cert.sh [-keySz KEY_SIZE] [-time VALID_TIME] [-dgst DIGEST_ALGORITHM] -host HOST_NAME -CN COMMON_NAME [-IP HOST_IP] [-E EMAIL] [-OU ORG_UNIT] [-O ORGANIZATION] [-L LOCALITY] [-S STATE] [-C COUNTRY] [-SANdomain "list"] [-SANip "list"]

The parameters are described in the following table:

[+] Show table


For example:

create_cert.sh -host myHOST.domain1.domain2.com -CN myWorkstation
5. If you are installing certificates on any Java-based PSDK applications that cannot get the certificate information from Configuration Server, convert the private key file to PKCS #8 format. Use the following command: 
convert_priv_key.sh -in INPUTFILE -out OUTFILE [-informat pfx|pkcs8|pkcs12|rsa] [-outformat pkcs8|rsa] [-encrypt]

The parameters are described in the following table:

[+] Show table

Certificate Authority Files

After successful script execution, the following data structure is created:

  • ca_conf—This directory contains the following files:
    • ca_cert.pem—The CA self-signed certificate file for UNIX (or any other implementation where pkcs#8 format is required)
    • ca_cert.pfx—The CA self-signed certificate file for Windows or Java (any other implementation where pkcs#12 format is required).
      Important
      You must copy ca_cert.pem and ca_cert.pfx to each computer that will host Genesys components that might require secure data exchange, even if client certificates are not required.
    • ca_priv_key.pem—The CA private key.
      This file is used to sign all certificates that this CA issues. This file must be read-only, and it must be readable only by the CA administrator account.
    • ca.db—The internal CA database used by the OpenSSL toolkit.
    • serial.num—The internal CA file that contains the serial number of the next generated certificate. The serial number is a unique identifier of the certificate that the CA issues.
    • ca.conf—The internal CA configuration file.
  • repository—This directory contains the files that this CA generates.

Host Certificate Files

After successful script execution, the following files are created in the repository directory:

  • <serial_#>_<host_name>_cert.pem—The host certificate for UNIX.
  • <serial_#>.pem—The auxiliary file for certificate generation for UNIX.
  • <serial_#>_<host_name>_priv_key.pem—The host private key for UNIX.
  • <serial_#>_<host_name>_cert.pfx—The PKCS (Public-Key Cryptography Standards) #12 file format, including the private key and certificate for Windows.

    • where:

    • <serial_#> is the serial number of the generated certificate. This number is unique for all certificates that this CA generates.
    • <host_name> is the name of your host computer, which is the first part of the full DNS host name.

Certificate Revocation Lists

Revocation lists are maintained using plain text files when certificates are managed using OpenSSL or Genesys Security Pack. See Securing Connections Using TLS for details about how to configure Certificate revocation functionality for native applications that rely on Genesys Security pack. Note that for Windows native and .NET applications you must turn off certificate revocation and check if your certificates are produced as discussed in this section.

Generating Certificates Using Windows Certificate Services

This section describes how to create certificates using Windows Certificate Services. If necessary, you can also obtain a certificate from a remote machine. Use these certificates if you intend to run all of your applications on Windows. If you intend to run one or more applications that might require secure connections on UNIX, Genesys strongly recommends that you use OpenSSL to create your certificates. Make sure that certificate templates are properly configured for server and GUI applications to satisfy requirements for necessary certificate attributes, discussed above.

Important
The examples provided in this section assume that Windows Certificate Services have been installed and configured. For information about how to install and configure Windows Certificate Services, see the appropriate Windows documentation.

Generation Process

To generate certificates with Windows Certificate Services, do the following:

1. Generate a certificate on a computer that is running the Windows Server operating system, and that has Windows Certificate Services installed and configured. [+] Show Steps
2. If you did not install the certificate in Step 1, retrieve and install it. [+] Show Steps
3. Configure Microsoft Management Console (MMC). You can use MMC to manage certificates on a Windows platform. See Configuring MMC for Certificate Management.
4. Install the certificate and private key on the computer that hosts Genesys applications. If this computer is different from the one on which you generated the certificate, you must first export the certificate and its private key.

Certificate Revocation Lists

The Microsoft SChannel security provider retrieves Certificate Revocation List (CRL) information for the certificate being verified using a CRL distribution point (CDP) mechanism. If the CDP URL specified in the certificate is not reachable from the current host (or is blocked by a firewall or other network policy), the process of certificate verification might pause for a time interval specified in system settings (15 seconds by default). This might be because the CDP URL is accessible but resides on a slow network resource, or connection quality may be very low, resulting in significant delays when retrieving the CRL. This might lead to various undesired consequences. To avoid these problems, Genesys strongly recommends that you use a local CDP in certificates and make sure all CDPs are accessible without any significant delay. You can also turn off CRL verification using Windows tools; refer to the documentation for your version of Windows.

Installing Certificates on Windows for Native Applications and Applications with a .NET Dependency

Important
For server applications, the certificates must be installed under the Local Computer account. For desktop applications, the certificates must be installed under the Current User account. For more information, see Managing Certificates in MMC.

To install the certificates, use the following procedure:

[+] Show steps

Managing Certificates using MMC on Windows

You can use the Microsoft Management Console (MMC) to manage certificates on a Windows platform.

Configuring MMC for Certificate Management

To configure MMC for certificate management:

[+] Show steps


You can save the MMC configuration in a file by selecting File > Save As.

Exporting Certificates

If the computer that is running Genesys applications is different from the one on which you generated the certificate, you must first export the certificate and its private key, as follows:

[+] Show steps

Obtaining Certificates from a Remote Computer

To obtain a certificate from a remote computer:

[+] Show steps

Installing Certificates on UNIX for Native Applications

Important
You must install the CA self-signed certificate file, ca_cert.pem, the certificate issued by this CA <serial_#>_<host_name>_cert.pem, and the certificate private key <serial_#>_<host_name>_priv_key.pem on each computer that hosts Genesys Server applications that might require secure data exchange.
  1. Copy the ca_cert.pem file to the computer.
  2. Copy the certificate and private key files to a local directory on the computer, as follows: 
    <serial_#>_<host_name>_cert.pem
<serial_#>_<host_name>_priv_key.pem
  3. Make sure that these files are readable by all Genesys applications that are running on this host computer.
Warning
The <serial_#>_<host_name>_priv_key.pem file contains critical security information. Make sure it can only be accessed by personnel authorized to work with this type of information.

Installing Certificates for Applications with Java dependency

If the Java application is using the file system to access certificates, follow the steps described for native applications using Genesys Security Pack, ensuring that <serial_#>_<host_name>_cert.pem and the private key file is converted to PKCS#8 format <serial_#>_<host_name>_priv_key_NEW.pem.


If the Java application is using a certificate store, for the instructions in Java documentation to install the certificates, ensuring that <serial_#>_<host_name>_cert.pem is converted to PKCS#12 (pfx) format . Typically you will:

  1. Use the Java command keytool –import x –file y –keystore z.
  2. If not already created, create a password for the keystore.
Tip
Genesys recommends that you use PEM files with PSDK Java for consistency.

Installing Genesys Security Pack

Important
The Security Pack on UNIX must be installed on each UNIX host computer on which Genesys native applications that use TLS are installed.
Tip
Along with libraries and scripts, a file README.version is installed as a part of Security Pack. If you have to report any security-related issues, you must also include the (cut-and-pasted) contents of this file. The information in this file contains complete Security Pack version information, which is difficult to obtain otherwise.

For information about the operating systems supported by the Security Pack on UNIX, refer to the Genesys Supported Operating Environment Reference Guide.

Genesys Security Pack is consistent with Federal Information Processing Standards (FIPS) starting in release 8.1.1. For information about these standards, and how to enable FIPS in Genesys software, refer to the FIPS section of this Guide.

To install Security Pack, complete the following steps:

  1. Install the Security Pack on each UNIX host with which secure connections will be configured: [+] Show steps
  2. Set the environment variable that corresponds to your operating system (see the following table), to the path to the Security Pack libraries.
    Operating System Environment Variable Name
    AIX LIBPATH
    Linux LD_LIBRARY_PATH
    Solaris LD_LIBRARY_PATH and/or LD_LIBRARY_PATH_64
Warning
Access permissions to the path to the Security Pack libraries, and the libraries themselves, must be set to enable Genesys applications to access them. If necessary, use the chown command to change the access permissions, as follows:
sudo chown <account name> -R <path to Security Pack libraries>
This page was last edited on September 13, 2022, at 07:02.
Comments or questions about this documentation? Contact us for support!