action.skip

Using SSL/TLS

Telnet Secure Socket Layer (SSL) and Transport Layer Security (TLS) security protocols are available for 3270 and 5250 session types, and Telnet Extended SSL/TLS support is available for 3270 session types. These Telnet options apply to the connection between a host and the Host Integrator session server or Design Tool. They do not apply to the connection between the client and the Host Integrator session server.

How to enable TLS/SSL encryption

To configure SSL/TLS encryption in your model:

  1. The Design Tool must be offline and disconnected.

  2. To modify an existing model, click Connection > Session Setup. To configure a new model, click File > New to display the New Model dialog.

  3. Select the Transport "Use SSL/TLS" checkbox (for 3270 or 5250).

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

Enabling FIPS 140-2 Validated Encryption

The Federal Information Processing Standards (FIPS) is used by US government agencies. 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 you start the session server or Design Tool.

Note

On Linux, you may need to export the environment variable so it is available to the process running the session server.

To confirm FIPS 140-2 encryption is enabled:

  1. Open the Administrative Console.

  2. You can verify that FIPS is enabled on the Session Server > Properties > General > Security panel and in the session server log. FIPS mode is not supported on the IBM AIX platform.

Altering the configuration of TLS connections

The configuration of host TLS connections is performed using an OpenSSL Configuration file, %VHI_ROOT%/bin/openssl-vhi.cnf. In this file, you will find a section [hostssl] where you can make changes to the configuration.

Note that the configuration file is read once, at startup. To see the effect of your edits, restart the Design Tool or Session Server.

Disabling TLS 1.3

If your host fails to negotiate TLS 1.3 connections, you can disable the use of this protocol version. In the configuration file, change MaxVersion = TLSv1.3 to MaxVersion = TLSv1.2.

Enabling SSL 3.0, TLS 1.0, or TLS 1.1

TLS 1.1 and earlier protocol versions are disabled by default. If your host does not yet support TLS 1.2 or TLS 1.3, 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 these protocols:

  1. change MinVersion = TLSv1.2 to MinVersion = TLSv1.1, MinVersion = TLSv1, or MinVersion = SSLv3
  2. uncomment the CipherString line by removing the initial # character
  3. In this line, change :@SECLEVEL=1 to :@SECLEVEL=0.

Modifying the ciphers offered to the host

If you wish, you can control the ciphers offered in the handshake. The CipherString setting controls the ciphers used for TLS 1.2 and earlier; the Ciphersuites setting controls the ciphers used for TLS 1.3. Refer to the OpenSSL 3.0 documentation to see possible values for these settings.

Client Authentication

If the host requires client authentication from Host Integrator, your private key and client certificate chain must be stored in a PEM file.

If your file is named %VHI_ROOT%/securehost/certificate.pem add the following line to the hostssl section:

Certificate = ${ENV::VHI_ROOT}securehost/certificate.pem

The file must be in PEM format with the unencrypted private key and the certificate chain in chain order.

If your certificate and private key are in PFX format, you can convert it to OpenSSL PEM format using the OpenSSL command line utility in the %VHIROOT%/bin folder.