Revision as of 22:49, August 26, 2016 by MFreviewers (talk | contribs) (→‎Generating Certificates using OpenSSL and Genesys Security Pack)
Jump to: navigation, search

What You Need

Before starting to configure your secure connections with TLS, you need to 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 can have Windows Certificate Service in your organization be a part of chain of trusted authorities already. 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 have to confirm format is compatible with your target platform(s).


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. 

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] [-dgst DIGEST_ALGORITHM] [-time VALID_TIME] -host HOST_NAME -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_cert.sh -host myHOST.domain1.domain2.com -CN myWorkstation
5. If you are installing certificates on any Java-based PSDK applications, such as Universal Contact 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]
Parameter Description
INPUTFILE Input private key filename.
OUTFILE Output private key filename.
-informat (Optional) Input private key format. For .pem private key files, use rsa Default is rsa.
-outformat (Optional) Output private key format. For PSDK, use pkcs8. Default is pkcs8.
-encrypt (Optional) Use password encryption for the resulting private key file. Password will be requested interactively.
ORG_UNIT (Optional) The name of the organization unit.

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/Genesys Security Pack. See configuration of TLS Connections for details how to configure Certificate revocation functionality for native applications that rely on Genesys Security pack. Note that for Windows native and .Net application you have to turn off certificate revocation check if your certificates are produced as discussed in this section. See See configuration of TLS Connections for details

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.

Installing Certificates on Windows for native applications and applications with .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.

Initial installation

  1. From the Windows Start menu, select Run, and then execute the mmc command to start the Microsoft Management Console (MMC).
  2. On the left pane of MMC, click the Certificates folder. (If there is no Certificates folder on the left pane, see Managing Certificates in MMC.
  3. Right-click the Trusted Root Certification Authorities folder, and select All Tasks > Import from the shortcut menu. This starts the Certificate Import Wizard.
  4. On the first Wizard page, click Next.
  5. On the File to Import page, type the full path to the ca_cert.pfx file or use Browse to navigate to the ca_cert.pfx that was created during CA setup. Make sure you select All Files for the Files of type option, and then click Next.
  6. On the Certificate Store page, select Place all certificates in the following store. Make sure that the Certificate store text box is set to Trusted Root Certification Authorities. Click Next.
  7. Click Finish.
  8. On the left pane, click the Certificates folder.
  9. On the left pane, right-click the Personal folder, and select All Tasks > Import from the shortcut menu. This starts the Certificate Import Wizard.
  10. On the first Wizard page, click Next.
  11. On the File to Import page, type the full name of the <serial_#>_<host_name>_cert.pfx file that was created during certificate generation. Click Next.
  12. On the Password page, click Next. The host certificates in PKSC #12 format are generated with an empty password.
  13. On the Certificate Store page, select Place all certificates in the following store. Make sure that the Certificate store text box is set to Personal. Click Next.
  14. Click Finish.
  15. Press F5 to update the MMC view.
  16. On the left pane, select Certificates > Personal > Certificates.
  17. On the right pane, locate the imported certificate in the list, and double-click it.
  18. In the Certificate dialog box, click the Details tab.
  19. To view the certificate thumbprint, select Thumbprint from the list. The thumbprint, consisting of a string of hexadecimal digits, appears in the lower part of the dialog box.

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:

  1. From the Windows Start menu, select Run, and execute the mmc command to start the Microsoft Management Console.
  2. Select File > Add/Remove Snap-in.
  3. In the Add/Remove Snap-in dialog box, click Add.
  4. In the Add Standalone Snap-in dialog box, select Certificates from the list and click Add.
  5. In the Certificates snap-in dialog box, select Computer account and click Next.
    Important
    To manage certificates for client applications, select My user account.
  6. In the Select Computer dialog box, select Local computer and click Finish.
  7. In the Add Standalone Snap-in dialog box, click Close.
  8. In the Add/Remove Snap-in dialog box, click OK.
    The Certificates item is added under Console Root on the left pane.


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:

  1. From the Windows Start menu, select Run and execute the mmc command to start the Microsoft Management Console.
  2. Open your saved console configuration, or select File > Add/Remove Snap-in.
  3. In the Add/Remove Snap-in dialog box, click Add.
  4. In the Add Standalone Snap-in dialog box, select Certificates from the list and click Add.
  5. In the Certificates snap-in dialog box, select Computer account and click Next.
  6. In the Select Computer dialog box, select Local computer and click Finish.
  7. In the Add Standalone Snap-in dialog box, click Close.
  8. In the Add/Remove Snap-in dialog box, click OK.
    The Certificates item is added under Console Root on the left pane.
  9. On the right pane, right-click the certificate in the list. Select All Tasks > Export from the shortcut menu to start the Certificate Export Wizard.
  10. On the first Wizard page, click Next.
  11. On the next page, select Yes, export the private key, and click Next.
  12. On the Export File Format page, the only available export file format will be PKCS #12. Click Next.
  13. On the Password page, type and confirm your password. Click Next.
  14. On the File to Export page, specify the path and file name for your certificate. Click Next.
  15. Click Finish to complete the export procedure.
Obtaining Certificates from a Remote Computer

To obtain a certificate from a remote computer:

  1. From the Windows Start menu, select Run, and execute the mmc command to start Microsoft Management Console.
  2. Select File > Add/Remove Snap-in.
  3. In the Add/Remove Snap-in dialog box, click Add.
  4. In the Add Standalone Snap-in dialog box, select Certificates from the list. Click Add.
  5. In the Certificates snap-in dialog box, select Computer account and click Next.
  6. In the Select Computer dialog box, select Another computer and either type the name of the remote target computer or click Browse to search for it. Click Finish.
  7. In the Add/Remove Snap-in dialog box, click OK.
    A new snap-in item is added under Console Root in the main snap-in console window.
    You can browse for examples of all the certificates on the target computer, or you can view information about a particular certificate. Depending on the options that you select, MMC also enables you to remotely manage certificates on a target computer.
  8. On the left pane, select Certificates > Personal > Certificates.
  9. On the right pane, double-click the certificate in the list.
  10. In the Certificate dialog box, click the Details tab.
  11. Select Thumbprint from the list. The value, consisting of a string of hexadecimal digits, appears in the lower part of the dialog box.
  12. Use the string of hexadecimal digits for the security configuration.

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 and <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

You have to follow steps described for native applications using Genesys Security Pack if Java application is using file system to access certificates, with consideration that <serial_#>_<host_name>_cert.pem and the private key file converted to pkcs#8 format <serial_#>_<host_name>_priv_key_NEW.pem. You have to follow Java documentation to install certificates for applications that use certificate store, with consideration that that <serial_#>_<host_name>_cert.pem is converted to pkcs#12 (pfx) format . Typically you will:

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


Install Genesys Security Pack

Important
The Genesys 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 Genesys 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 Genesys Security Pack version information, which is difficult to obtain otherwise.

For information about the operating systems supported by the Genesys 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 Genesys 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>
Comments or questions about this documentation? Contact us for support!