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 strictHostKeyChecking parameter of either the mqsicreateconfigurableservice command or the FtpServer configurable service. For more information about the settings that you can specify with an FtpServer configurable service, see FtpServer configurable service.

Strict known host checking

When strict known host checking is turned on (by setting the strictHostKeyChecking parameter to Yes), the integration node 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. You specify the location of your known hosts file using the knownHostsFile parameter of the mqsicreateconfigurableservice command. When the integration node 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 node or configurable service. The known hosts files that you provide for strict known host checking are not modified by the integration node.

Non-strict known host checking

When strict known host checking is turned off (by setting the strictHostKeyChecking parameter to No) the integration node connects only to known hosts with valid keys or to new hosts to which it has not connected before. If the integration node attempts to connect to a new host (to which it has not connected previously), the integration node makes the connection, accepts the host's SSH key, and stores it in the known hosts file. When the integration node 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 node. One known hosts file, managed by the integration node, 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 node. 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 node. 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 on, correct the entry for the host in the known hosts file that you specified in the knownHostsFile parameter of the mqsicreateconfigurableservice command.
    • 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 node. The known hosts file is in the \components\BROKERNAME-NAME\EG-UID\config\known_hosts subdirectory of the directory in which IBM® Integration Bus 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 node attempts to reconnect, it adds the new host key to the known hosts file.

  3. Restart the message flow.