Encryption Between Verastream Host Integrator and Your Host

  • 7021544
  • 17-Aug-2006
  • 31-Aug-2021

Environment

Verastream Host Integrator

Situation

For increased security, you can encrypt the communications between Verastream Host Integrator (VHI) and your host.

Note: This technical note specifically addresses connections between VHI and hosts only. For information about encryption and access control between VHI components (such as the client connector and session server), see KB 7021314 and KB 7021567.

Resolution

Host Connection Encryption Support

To encrypt the Telnet communications between Session Server (or Design Tool) and your host, the following technologies are supported:

How to Enable TLS/SSL Encryption

To configure TLS/SSL encryption for the host communication, refer to the following information.

Configuring Your Model

To configure SSL/TLS encryption in your model:

  1. In Design Tool, you must be offline and disconnected.
  1. To modify an existing model, click Connection > Session Setup. To configure a new model, click File > New to display the New Model dialog.
  1. Beginning in version 7.1, check the Transport "Use SSL/TLS" checkbox (for 3270 or 5250). In version 7.0 and earlier, select the Transport Type “Telnet SSL” (for 3270 or 5250) or “Telnet Extended SSL” (for 3270).

Note: The SSL/TLS transport option can only be enabled in the Transport configuration in Design Tool. It cannot be specified in Design Tool Deployment Options, a deployment descriptor deploy_desc.xml file, Administrative Console (version 7.0 or higher), or Administrative WebStation (version 6.6 or earlier).

After connecting to the host using Design Tool, to determine the negotiated cipher, see Settings > View Settings > Host Communication > Telnet > Secure Host SSL Negotiated Cipher. Beginning in version 7.6 SP1, the TLS version and negotiated cipher are also logged in model debug messages (.vmr files).

Enabling FIPS 140-2 Validated Encryption

FIPS is the Federal Information Processing Standards used by US government agencies. Beginning in version 6.6, when using TLS/SSL, you can enable FIPS 140-2 validated encryption. To enable this feature, set an operating system environment variable (VHI_FIPS=1) before starting the Session Server service or Design Tool application.

Note: On UNIX, you may need to export the environment variable so it’s available to the process that runs the Session Server component.

Beginning in version 7.0, you can confirm FIPS 140-2 TLS/SSL encryption is enabled in Administrative Console (session server > Properties > General > Security) and in the session server log. Note: FIPS mode is not supported on the IBM AIX platform.

Enabling TLS 1.0 and TLS 1.1

Beginning in VHI version 7.8 SP1, TLS 1.0 and TLS 1.1 are disabled by default. If your host does not yet support TLS 1.2, you may see errors related to TLS version not supported in Design Tool, the session server log, or model debug messages (.vmr file).

To enable TLS 1.0 and TLS 1.1, set an operating system environment variable VHITELNETALLOWTLS1=1 before starting the Session Server service or Design Tool application.

Note: On UNIX, you may need to export the environment variable so it’s available to the process that runs the Session Server component.

Enabling SSL 3.0

Beginning in VHI version 7.7, SSL 3.0 is disabled by default due to a vulnerability in this protocol (as described in Technical Note 2750). If your host does not yet support TLS, you may see the following errors in Design Tool, the session server log, or model debug messages (.vmr file):

[VHI 3050] SSL Error - Could not complete the SSL connection
[VHI 3053] SSL Error: error:140770FC:SSL routines:SSL23_GET_SERVER_HELLO:unknown protocol

To enable SSL 3.0, set an operating system environment variable VHITELNETALLOWSSL3=1 before starting the Session Server service or Design Tool application.

Note: On UNIX, you may need to export the environment variable so it’s available to the process that runs the Session Server component.

Client Authentication

If the host requires client authentication from VHI, your private key and client certificate must be stored in a file named certificate.pem. The file must be in PEM format with the private key first, followed by the certificate chain in chain order. This file must be stored in a subdirectory named securehost, typically as follows:

  • Version 7.5 or higher on 64-bit Windows: \Program Files\Attachmate\Verastream\HostIntegrator\securehost
  • Version 7.0 through 7.1 SP2 on 64-bit Windows: \Program Files (x86)\Attachmate\Verastream\HostIntegrator\securehost (Note: With version 7.0 only, the securehost subfolder is not created by the installer and you must create it manually.)
  • Version 7.0 or higher on Linux/UNIX: /opt/attachmate/verastream/hostintegrator/securehost
  • Version 6.5 or 6.6 on 32-bit Windows: \Program Files\VHI\securehost

If your certificate and private key are in PFX format, you can use the OpenSSL command line utility (\Program Files\VHI\openssl\openssl.exe in version 6.5 or 6.6) or other conversion tool (such as https://www.sslshopper.com/ssl-converter.html) to convert it to standard PEM format. It is recommended you open the resulting file in a text viewer to verify it is in PEM format with the private key first. PEM certificates are text files containing base64-encoded data and lines such as "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----".

Note: Encrypted private keys and public certificates are not supported.

The client certificate is used for SSL/TLS connections by both Session Server and Design Tool.

Enabling Encryption on the Host

For more information about how to configure your z/OS mainframe (3270) or iSeries host (5250) to support SSL/TLS, see information in Technical Note 2214 or Technical Note 2215 respectively. Note: These technical notes refer to connecting with Reflection, but the host configuration steps also apply to Verastream.

 

Additional Information

Legacy KB ID

This article was originally published as Attachmate Technical Note 10068.