Security Overview for Verastream Host Integrator 7.x

  • 7021314
  • 06-Dec-2013
  • 01-Apr-2018


Verastream Host Integrator version 7.5 or higher


This technical note describes security topics as they relate to a Verastream Host Integrator (VHI) installation in a production environment. Topics include encryption, firewall/NAT support, access control with authentication and authorization, and features for sensitive data such as host passwords.


Foundational Security Considerations

Verastream Host Integrator (VHI) integrates multiple technologies, which also must be individually secured. In any installation, review the overall security of your operating systems, host, network environment, and applications, including the following:

  • Evaluate and implement all security updates as recommended by vendors.
  • Install and configure firewalls where appropriate.
  • On systems where VHI server software is installed, secure the file system.
  • Use strong passwords that cannot be easily guessed or compromised with dictionary attacks.
  • Implement other industry-standard policies and procedures for authentication and authorization access control.

To stay informed about Verastream Host Integrator security updates, regularly review

Be aware that encryption is processor-intensive and may impact server performance, particularly in heavy load scenarios.

Securing Connections

The following diagram depicts VHI components in a typical environment.

Figure 1 - Verastream Host Integrator Typical Production Environment

Connection A, between Web Browser and VHI Web Server

The following information applies to communication between a web browser and web application (HTML5 Web Application project generated by VHI Web Builder, or the built-in “zero-footprint” Terminal3270 or Terminal5250 applications):

  • Beginning in version 7.5, the VHI Web Server supports encrypted HTTPS on port 8443. See also Encryption Using Certificates with SHA256/RSA2048 Digital Signatures.
  • To disable non-secure HTTP on port 8081, set servletengine.port=0 in the %VHI_ROOT%/servletengine/conf/ file, and restart the VHI Web Server service. Note: When HTTP is disabled, some functionality is affected:
    • In Web Builder, launching a web application (such as after rebuild and deployment) will not work. In your web browser, modify the URL to use HTTPS instead.
    • On Windows, the 3270 Terminal Session and 5250 Terminal Session shortcuts in the Start menu will no longer work. Modify the shortcut properties to use HTTPS instead.

Connection B, between Connector and Session Server

The VHI connector API can be called directly by your custom client code, or used by the VHI Web Server or SOAP stack. To enable encryption between the VHI connector and VHI session server, use one or more of the following methods:

  • Option 1: When generating an application in Web Builder, enable the following option in Project Properties, depending on your product version:
    • Version 7.6 or higher: “Require encrypted connection to the VHI server” (enabled by default)
    • Version 7.5 SP1 or earlier: “Require Secure Connection” (disabled by default)
  • Option 2: When writing client application code, make a RequireSecureConnection API call before the connection API call (ConnectToSession, ConnectToModel, ConnectToSessionViaDomain, or ConnectToModelViaDomain).
  • Option 3: In Administrative Console > Session Server Properties > General > Security, check “Enable Security.” However, this option also enables access control and requires User credentials when connecting. See also KB 7021567.

See also Encryption Using Certificates with SHA256/RSA2048 Digital Signatures.

If you have a firewall between the connector and session server, allow TCP port 9623 to the session server. If you are using a load distribution domain (as described in KB 7021566), also allow TCP ports 9641 and 48620 to the management server (see also KB 7021229).

If you have a NAT proxy device between the connector and session server, see Session Server NAT Support.

Connection C, between Web Services Client and Server

The following information applies to communication between your Web Services (SOAP or REST) client and the Web Services server embedded in the VHI session server:

Note: Beginning in version 7.7, your web services client making an HTTPS connection must support TLS (SSL 3.0 is no longer supported to address the POODLE vulnerability, as described in Technical Note 2750).

  • To disable non-secure HTTP on port 9680, in Administrative Console > Session Server Properties > Web Services, uncheck “Enable HTTP Web services.” Note: When HTTP is disabled, some functionality is affected:
    • You cannot test web services using VHI Web Services Explorer as the SOAP client. Use a different client for testing with HTTPS.
    • Verastream Process Designer R3 does not support encrypted SOAP connections. Use a newer version of VPD.
  • To use different port numbers, see “Changing Web Service Ports” in KB 7021229.
  • If session server security has been enabled in Administrative Console (as described in Connection B Option 3), you must supply User credentials for web services calls. There are three ways to do so:
    • Option 1: Specify credentials as the Username and Password environment variable parameters (inband within the SOAP or REST request data payload).
    • Option 2: User credentials can be sent in a channel in the SOAP header, in accordance with Web Services Security message Security 1.1 (WS-Security 2004) and Web Services Security UsernameToken Profile 1.1.
    • Option 3: Credentials can be sent as HTTP Basic Authentication. To enable HTTP Basic Authentication, edit the %VHI_ROOT%/sesssrvr/services/ws/META-INF/service-cfg.xml file to set authnMetadata and authnService to true. The credentials are cached by the web service and not passed to the session server until a subsequent SOAP or REST request is received. If the user is unauthorized, the initial HTTP authentication will appear to succeed but the subsequent request will fail. Note: When Basic Authentication is enabled, you cannot test web services using VHI Web Services Explorer as the SOAP client.

Note: Authentication credentials sent via SOAP, REST, or HTTP Basic Authentication are transmitted over the network as clear text unless an HTTPS connection is used.

  • Beginning in version 7.6 SP1, more WSDL control is available:
    • To disable WSDL metadata for a specific model or pool, see KB 7021311.
    • To just hide a specific table procedure in a WSDL, enable the “Hide in web services and Web Builder” option is in the Tables dialog in Design Tool.

Connection D, between VHI Session Server (or Design Tool) and Your Host

For information about securing communications between VHI and your hosts, see KB 7021544.

Connections between Administrative Console and Management Servers

Encrypted connections are automatically used between Administrative Console and management server, and for replication between multiple management servers in a cluster.

Administrative credentials are required for Administrative Console to connect to the management server. For more information about authorization access control, see KB 7021567. Encrypted LDAPS connections are supported for directory services.

If you have a firewall between Administrative Console and management server, see also KB 7021327.

Connection between Session Server (Log Manager) and Your Mail Server

In Administrative Console (Session Server Properties), you can enable the Email Notification feature and configure specific error messages to send email. Beginning in version 7.6.1026 (7.6 SP1), SMTP Authentication is supported if your mail server requires a username and password for sending email. When SMTP Authentication is enabled:

  • The credentials are stored encrypted in the session server configuration (sesssrvr.config file) using 3DES (Triple DES).
  • If your mail server supports TLS, the credentials are transmitted to the mail server over an encrypted connection.

Encryption Using Certificates with SHA256/RSA2048 Digital Signatures

Beginning in version 7.5, encrypted communication (as described above) uses certificates with SHA-256 and 2048-bit RSA digital signatures. Beginning in version 7.6, this feature is also supported on IBM platforms (Linux on System z, and AIX). However, these certificates are generated in a new installation only; if you upgrade from an earlier version, the existing certificates are kept.

When you access the VHI web services or web applications over HTTPS, your client or browser may report that the self-signed security certificate is not trusted or not issued by a trusted certificate authority. You have several options: proceed through the warning, install the VHI self-signed certificate in your trusted CA store, or replace the self-signed certificate with your CA-issued certificate:

On Windows Server 2003, if you attempt to access the VHI web services or web applications over HTTPS, your web browser may not be able to display the web page or report an “Invalid Server Certificate” error due to lack of SHA-256 support. For more information, see KB 7021250.

US FIPS 140-2 Validated Cryptography

FIPS is the Federal Information Processing Standards used by US government agencies. To enable use of FIPS 140-2 encryption mode for host communication, set an operating system environment variable VHI_FIPS=1 before starting the VHI session server service or Design Tool application.

On UNIX/Linux, you may need to export the environment variable so that it’s available to the process that runs VHI services.

In Administrative Console, you can confirm that FIPS 140-2 cryptography for TLS is enabled for the session server (in Session Server Properties > General > Security).

This feature is not supported for the session server running on IBM platforms (Linux on System z, or AIX).

For more information about the validated cryptographic libraries, see KB 7021285.

Session Server NAT Support

Beginning in version 7.5, connectors, Design Tool, and model deployment utilities can connect to the session server through a Network Address Translation (NAT) device. The %VHI_ROOT%/etc/sesssrvr.config file must be manually edited (after temporarily stopping the session server service) to set the ApptrieveServer > Server property to the fully qualified host name or IP address as the server is known on the client's side of the network. Without this configuration, connection attempts by the connector result in error 4701 "Server services not running” and the session server logs error 3152 "Allocated session timed out waiting for client connection."

Securing Host Passwords

If you use session pools (especially with 3270 or 5250 host sessions), a Model Variable List (MVL) defines the unique host user names and passwords for the session server to use. The variable values are specified in the model deployment package and stored in the session server configuration.

When you are creating a Model Variable List (in Design Tool Deployment Options, mvl_desc.xml file, or Administrative Console), enable “Hidden” or “Hide values” for host passwords. This option provides the following benefits:

  • When creating your model package file, the variable values can be encrypted. In the packagemodel command, if you add the -e "passphrase" option, your phrase will be used to generate a 3DES (Triple DES) encryption key to encrypt the hidden variable values. The same passphrase will also be required to decrypt values when deploying with the activatemodel command. Use a strong password as the passphrase.
  • On the session server, the variable values are automatically encrypted in the sesssrvr.config file using 3DES (Triple DES).
  • The variable values are not visible in Administrative Console.
  • The variable values are redacted in troubleshooting tools, as described in Redacting of Confidential Data below.

Redacting of Confidential Data

In version 7.5.1030 (7.5 SP1) or higher, host passwords and other sensitive data are not visible in the following tools:

  • Model debug messages (.vmr files) recorded by session server or Design Tool
  • Session server log (message.dat file, Administrative Console, LogExport tool)
  • UNIX syslog and Windows Event Log (session server log messages to system)
  • Email and SNMP Notifications of session server log messages

The above tools no longer contain the following data:

  • Values of model variables that are hidden (as described in Securing Host Passwords)
  • Encrypted values set in model operation commands, such as TransmitToAttrEncrypted and TransmitANSIEncrypted
  • Values written to non-displayed terminal fields (3270/5250)
  • Values of attributes that are configured as write-only in the model

Note: Before providing troubleshooting files to Attachmate or others, verify that sensitive data has been removed. In specific unusual configurations or host applications, sensitive data may not be redacted.

Avoiding Injection Issues

In Web Services configuration (in Administrative Console) and web application configuration (in Web Builder), do not enable executeSQLStatement and processString methods unless required. If you enable these features, validate all user input before calling these methods to prevent injection issues.

UNIX/Linux Installations: Non-Root and Permissions

The following information applies to VHI installations on UNIX/Linux platforms:

  • Non-root support: Before installing VHI on UNIX/Linux, create a non-root user and group for running VHI, such as vhiuser and vhigroup. When installing interactively, select a custom installation and specify the owner. If installing from the command line, specify the --owner option. Refer to the Installation Guide at Beginning in version 7.7, subsequent updates of VHI software can be performed by the non-root owner user.
  • File system permissions: Beginning in version 7.6, the UNIX/Linux installer sets appropriate permissions on directories and files it creates.

Additional Information

Legacy KB ID

This document was originally published as Attachmate Technical Note 10151.