Maintaining client and server authentication key files

IBM® Connect:Direct® client/server security depends on a key, similar to a password, in a IBM Connect:Direct server and an identical key in each API that communicates with that server. The keys are defined and coordinated by the system administrator. You can edit both key files with any text editor installed on your system.

The client key file is called keys.client on the node on which the API resides. The server key file is keys.server on the node on which the server resides. The key files are located in the directory d_dir/security.

CAUTION:
To mitigate brute force attacks to break the keys.client and keys.server authentication keys, IBM strongly recommends that customers use authentication key values with a minimum length of 15 characters.

Key File Format

A record in a key file can contain up to four keys that match entries in another API or server key file. The key file can contain as many key file records as necessary. The format of a key file entry is illustrated in the following sample:

hostname MRLN SIMP key [key [key [key] ] ]

Key File Parameters

The following table describes the available key file parameters:

Parameter Description Value
hostname The host name of the server with which you want to communicate or the host name of the API you will allow to communicate with your server. The hostname is followed by one or more space characters. If you replace the host name with an asterisk (*) character in the server configuration file, the server accepts a connection from any API with a matching key. You can use only one asterisk per file. Always place the entry with the asterisk after entries with specific host names. 1—16 characters and must be unique within its key file.
MRLN SIMP A required character string, separated from the other fields by one or more spaces. Character string
key The security key. Separate the key from SIMP by one or more spaces. Up to 22 characters long including A to Z, a to z, 0 to 9, period (.), and 
slash (/).
Note: Key values longer than 22 characters do not generate an error; however, only the last 22 characters entered are used. Any characters prior to the last 22 are ignored.

Sample Client Authentication Key File

The following figure illustrates API key lists in the Clients column and server key lists in the Servers column.

  • API A contains key11, key21, key31, and key41. Key11 enables API A to communicate with Server A because Server A also contains the key11 entry. You must ensure that API1 is the host name on which API A resides and that Server1 is the host name on which Server A resides.
  • API D contains key14, key24, and key34. Key14 enables API D to communicate with Server A because Server A also contains the key14 entry. You must ensure that API4 is the host name on which API D resides and that Server1 is the host name on which Server A resides.
  • API C can communicate with Server A and Server B through matching keys. API C also can communicate with Server C and Server D only through the * MRLN SIMP keyany line.

Authentication Process

The IBM Connect:Direct authentication process determines if the user is authorized to access the system.

The goal of IBM Connect:Direct security is to reliably determine the identity of each user without requiring logon repetition. In addition, the security design ensures that all requests originate from the IBM Connect:Direct API, to ensure that the authentication process is not bypassed by an unauthorized user. The following figure displays the components that perform authentication:

Server Authentication Parameters

The server authentication parameters are specified in initparm.cfg. You must have ownership and permissions to modify these files. Ownership is established during the installation procedure.

Additionally, the directory containing the keys.server file must have UNIX permission 0700, and keys.server must have UNIX permission 0600. These files cannot be owned by root.

The following server authentication parameters are used by the CMGR during the authentication procedure:

Parameter Description
server.program The server program to use during the authentication procedure.
server.keyfile The key file to use during the authentication procedure.

Client Authentication Parameters

The client authentication parameters are specified in ndmapi.cfg. You must have ownership and permissions to modify these files. Ownership is established during the installation procedure.

Additionally, the directory containing the keys.client file must have UNIX permission 0700, and keys.client must have UNIX permission 0600.

The following client authentication parameters are used by the CLI/API during the authentication procedure:

Parameter Description
client.program The client program to use during the authentication procedure.
client.keyfile The key file to use during the authentication procedure.

Session Establishment

Session establishment for TCP affects how you set up firewall rules and configure the firewall navigation initialization parameters in IBM Connect:Direct.

TCP Session Establishment

An IBM Connect:Direct TCP client contacts an IBM Connect:Direct TCP server on its listening port. The IBM Connect:Direct client scans the list of ports (specified using the tcp.src.ports initialization parameter) and looks for a port to bind to. The number of times IBM Connect:Direct scans the list is specified using the tcp.src.ports.list.iterations initialization parameter. If IBM Connect:Direct finds an available port, communication with the remote node proceeds.