Configuring TCP/IP server nodes to use SSL

Configure a TCP/IP configuration to use SSL to secure connectivity to and from the TCPIP server nodes.

You can create or modify TCP/IP server connections that use SSL, by creating or modifying a configurable service. You can specify:
  • The type of protocol.
  • The allowed cipher suites.
  • A key alias.
  • Whether a connecting client should provide authentication information.
By default, SSL is not enabled for any configurable services. The nodes use the standard integration node keystore and truststore configuration.

Before you begin

Set up a public key infrastructure (PKI) at integration node level by following the instructions in Setting up a public key infrastructure.

About this task

Follow these steps to configure the TCPIP nodes to use SSL:

  1. Changing a TCP/IP server configuration to use SSL
  2. Creating a TCP/IP server configuration that uses SSL

Changing a TCP/IP server configuration to use SSL

About this task

Use the mqsichangeproperties command to change an existing TCPIPServer configurable service.

Procedure

  1. The following command changes a TCPIPServer configurable service to use TLS with any available cipher suite. Connecting clients are not asked to authenticate. 
    mqsichangeproperties MYBROKER 
  -c TCPIPClient 
  -o myTCPIPServerService 
  -n SSLProtocol  
  -v TLS
  2. Restart the integration server that contains the message flows.

Creating a TCP/IP server configuration that uses SSL

About this task

Use the mqsicreateconfigurableservice command to create a TCPIPServer configurable service.

Procedure

  1. The following command creates a TCPIPServer configurable service for making connections on port 1455. It uses the SSL protocol TLS with a specific list of allowed cipher suites. Connecting clients are required to authenticate. 
    mqsicreateconfigurableservice MYBROKER 
     -c TCPIPServer 
     -o myTCPIPServerService 
     -n Port,SSLProtocol,SSLCiphers,SSLClientAuth 
     -v 1455,TLS,SSL_RSA_WITH_RC4_128_MD5;
        SSL_RSA_WITH_3DES_EDE_CBC_SHA,require
  2. Restart the integration server that contains the message flows.

Using an SSL key alias

About this task

A key alias identifies the key that is to be used for the SSL connection, if the keystore for your integration node or integration server contains more than one key. Use the mqsichangeproperties or mqsicreateconfigurableservice as appropriate, with the SSLKeyAlias property. The default value "" or none, means that an SSL key alias is not used. Any other string identifies the alias.

Note: If the keystore contains more than one key, and no key alias is defined, the Java™ virtual machine arbitrarily chooses a key at run time.

The following command creates a TCPIPServer configurable service for making connections on port 1455. It uses the SSL protocol TLS with the cipher suites SSL_RSA_WITH_RC4_128_MD5 and SSL_RSA_WITH_3DES_EDE_CBC_SHA. It requires the client to authenticate itself, and uses the key alias MyKey to identify the key to be used.

mqsicreateconfigurableservice MYBROKER 
  -c TCPIPServer 
  -o myTCPIPServerService 
  -n Port,SSLProtocol,SSLCiphers,SSLClientAuth,SSLKeyAlias 
  -v 1455,TLS,SSL_RSA_WITH_RC4_128_MD5;SSL_RSA_WITH_3DES_EDE_CBC_SHA
     ,require,MyKey

The following command changes a TCPIPServer configurable service to use the first key retrieved from the keystore, with SSL protocol TLS. SSLClientAuth is disabled.

mqsichangeproperties MYBROKER 
  -c TCPIPClient 
  -o myTCPIPServerService 
  -n SSLProtocol
  -v TLS

Testing your configuration

About this task

To test your configuration, connect an SSL-enabled client, such as another program, or a web browser, to the server port. Connection error messages, such as handshake failures, or untrusted keys, indicate that you must change the configuration.

Client identity

About this task

If SSL client authentication is requested or required, and the client successfully authenticates, the distinguished name is present as an identity source token in the properties parser, in the tree propagated from the Open terminal at connection time. This applies only to the TCPIPServerInput node.
  • The IdentitySourceToken field is set to the distinguished name from the client certificate.
  • The IdentitySourceType field is set to the string username.
  • The IdentitySourceIssuedBy field is set to the issuer of the certificate presented by the client.
If SSL client authentication is requested, and the client does not provide the required credentials, the fields are set to blank.