Known host checking

Use known host checking to control which hosts the integration node can connect to, and to verify the identity of those hosts.

Known host checking enables the integration node to protect the messages in the message flow from unauthorized attempts to intercept the data (sometimes known as man-in-the-middle attacks). Known hosts files contain the SSH keys of the hosts to which the integration node can connect. On z/OS® systems, known hosts files and SSH identity files are stored in EBCDIC format, and on other operating systems they are stored in ASCII format.

Before it connects to a host to receive or transfer a file (using the FileInput or FileOutput nodes), the integration node checks the host key against the keys that are stored in the known hosts file. If the host key does not match an existing entry for the host in the known hosts file, the connection fails. If the host is new (and has no entry in the known hosts file), the result depends on whether strict known host checking is turned on or off.

You can specify whether strict known host checking is turned on or off by setting the Strict host key checking property of the FTP Server policy (see FTP Server policy (FtpServer)).

Strict known host checking

When strict known host checking is turned on (by setting the Strict host key checking property to Yes), the integration server connects only to known hosts with valid SSH host keys that are stored in the known hosts file. If you use strict known host checking, you must create your own known hosts file, in OpenSSL PEM format, containing the SSH keys of your trusted hosts. When the integration server attempts to make a connection to a host, it checks the host key against the contents of the known hosts file. If the key is not in the known hosts file, the connection fails and a BIP3371 error occurs.

You can have multiple known hosts files and specify a different one for each policy. The known hosts files that you provide for strict known host checking are not modified by the integration server.

Non-strict known host checking

When strict known host checking is turned off (by setting the Strict host key checking property to No) the integration server connects only to known hosts with valid keys or to new hosts to which it has not connected before. If the integration server attempts to connect to a new host (to which it has not connected previously), the integration server makes the connection, accepts the host's SSH key, and stores it in the known hosts file. When the integration server tries to connect to the same host on subsequent occasions, the host key is checked against the key stored in the known hosts file, and, if the key matches, the connection is made. However, if the host key is different from the one stored in the known hosts file, the connection attempt fails and a BIP3371 error occurs.

When strict known host checking is turned off, the known hosts file is managed by the integration server. One known hosts file exists for each integration server.

BIP3371 error message

The BIP3371 error message might indicate that there has been an unauthorized attempt to intercept a message. However, the connection failure (and resulting BIP3371 error message) might be caused by a change to the host's SSH key at some time following its first connection to the integration server. For example, if the SSH server is reinstalled, it is assigned a new key, which is not found in the known hosts file and is therefore not accepted by the integration server. As a result, the connection fails and the BIP3371 error message is shown.

If you know that the SSH host key has changed (as a result of a recent SSH server reinstallation, for example), you can solve the connection failure by modifying the known hosts file:
  1. Stop the message flow.
  2. Edit the known hosts file.

    If you have strict known host checking turned off, remove the host's entry from the known hosts file that is managed by the integration server. The known hosts file is in the \components\BROKERNAME-NAME\EG-UID\config\known_hosts subdirectory of the directory in which IBM® App Connect Enterprise is installed. For example, on Windows the default directory is C:\ProgramData\IBM\MQSI\components\BROKERNAME-NAME\EG-UID\config\known_hosts. On UNIX systems the default directory is /var/mqsi/components/BROKERNAME-NAME/EG-UID/config/known_hosts.

    When the integration server attempts to reconnect, it adds the new host key to the known hosts file.

  3. Restart the message flow.