Environment
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:
- TLS/SSL: Beginning in VHI version 7.8 SP1, TLS 1.2 will be the only version enabled by default when connecting to 3270 and 5250 hosts. To enable older versions see Enabling TLS 1.0 and TLS 1.1 below.
- Beginning in VHI version 6.5, encrypted Telnet is supported for 3270 and 5250 host terminal types:
- TLS 1.1 and 1.2 are supported beginning in VHI version 7.6 SP1.
- TLS 1.0 is supported in VHI version 6.6 and higher.
- SSL 3.0 is supported in VHI version 6.5 and higher. However, it is disabled by default beginning in version 7.7 (see Enabling SSL 3.0 below).
- See How to Enable TLS/SSL Encryption below.
- SSH: Beginning in VHI version 7.6 SP1, SSH is supported for VT terminal types. For more information, see http://docs2.attachmate.com/verastream/vhi/7.7/en/topic/com.attachmate.vhi.help/html/reference/ssh_overview.xhtml.
- Reflection Security Proxy Server: Beginning in VHI version 7.1, you can establish an encrypted TLS/SSL connection using Attachmate Reflection Security Proxy Server (requires Reflection for the Web version 10.2.505 or higher, or Reflection Security Gateway 2014, available separately). This option is appropriate for hosts not supporting TLS/SSL or SSH, or to use access control features in the proxy server. For more information, see http://docs2.attachmate.com/verastream/vhi/7.7/en/topic/com.attachmate.vhi.help/html/reference/config_reflection_proxy.xhtml. Note: This feature is supported in Design Tool only, not the runtime session server.
How to Enable TLS/SSL Encryption
To configure TLS/SSL encryption for the host communication, refer to the following information.
To configure SSL/TLS encryption in your model:
- In Design Tool, you must be offline and disconnected.
- To modify an existing model, click Connection > Session Setup. To configure a new model, click File > New to display the New Model dialog.
- 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.
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.
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.
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.