Use a certificate exit to authenticate a TLS server

In this scenario, we can authenticate a TLS connection by using a certificate exit.

Before starting

• Before you start to use this scenario, make sure that we have completed the prerequisite tasks listed in Getting started with IBM MQ Internet Pass-Thru.
• Install Java 8.0 JDK.
• Add the Java bin subdirectory to the PATH environment variable.

This scenario performs the same function as the Authenticating a TLS server scenario, with the addition of a certificate exit.

The sample exit used in this scenario is SampleCertificateExit.java. It is provided with MQIPT in the samples/exits subdirectory of the MQIPT installation directory.

By changing the value of the SSLExitData property, the TLS connection between the two MQIPT servers can be allowed or rejected.

This diagram shows the connection from the IBM MQ client (called client1.company1.com on port 1415) through two instances of MQIPT to the IBM MQ server (called server1.company2.com on port 1414).

Procedure

To use a certificate exit to authenticate an TLS server, complete the following steps:

1. On the MQIPT 1 system:
   1. Create a directory called exits in the MQIPT home directory by issuing the following command in a command prompt:

      md C:\mqiptHome\exits

   2. Open a command prompt and enter the following commands to compile the exit. You do not have to do this if you have not changed the exit code as the compiled sample exit is supplied with MQIPT.

      C:
      cd \mqipt\samples\exits
      javac -classpath C:\mqipt\lib\com.ibm.mq.ipt.jar;. SampleCertificateExit.java

   3. Enter the following command to copy the compiled exit class file SampleCertificateExit.class to the C:\mqiptHome\exits directory:

      copy C:\mqipt\samples\exits\SampleCertificateExit.class C:\mqiptHome\exits

   4. Edit mqipt.conf and add the following route definition:

      [route]
      ListenerPort=1415
      Destination=9.100.6.7
      DestinationPort=1416
      SSLClient=true
      SSLClientKeyRing=C:\mqipt\samples\ssl\sslSample.pfx
      SSLClientKeyRingPW=<mqiptPW>1!PCaB1HWrFMOp43ngjwgArg==!6N/vsbqru7iqMhFN+wozxQ==
      SSLClientExit=true
      SSLExitName=SampleCertificateExit
      SSLExitPath=C:\mqiptHome\exits
      SSLExitData=allow

   5. Open a command prompt and start MQIPT:

      C:\mqipt\bin\mqipt C:\mqiptHome -n ipt1

      where C:\mqiptHome indicates the location of the MQIPT configuration file, mqipt.conf, and ipt1 is the name to be given to the instance of MQIPT. The following messages indicate that MQIPT has started successfully:

      5724-H72 (C) Copyright IBM Corp. 2000, 2020 All Rights Reserved
      MQCPI001 IBM MQ Internet Pass-Thru V9.2.0.0 starting
      MQCPI004 Reading configuration information from mqipt.conf
      MQCPI152 MQIPT name is ipt1
      MQCPI021 Password checking has been enabled on the command port
      MQCPI011 The path C:\mqiptHome\logs will be used to store the log files
      MQCPI006 Route 1415 has started and will forward messages to :
      MQCPI034 ....9.100.6.7(1416)
      MQCPI035 ....using MQ protocol
      MQCPI036 ....SSL Client side enabled with properties :
      MQCPI031 ......CipherSuites <null>
      MQCPI032 ......keyring file C:\mqipt\samples\ssl\sslSample.pfx
      MQCPI047 ......CA keyring file <null>
      MQCPI038 ......peer certificate uses UID=*,CN=*,T=*,OU=*,DC=*,O=*,
      	                                           STREET=*,L=*,ST=*,PC=*,C=*,DNQ=*
      MQCPI129 ......using certificate exit C:\mqiptHome\exits\SampleCertificateExit
      MQCPI131 ......and certificate exit data 'allow'
      MQCPI078 Route 1415 ready for connection requests

2. On the MQIPT 2 system:
   1. Edit mqipt.conf and add the following route definition:

      [route]
      ListenerPort=1416
      Destination=Server1.company2.com
      DestinationPort=1414
      SSLServer=true
      SSLServerKeyRing=C:\mqipt\samples\ssl\sslSample.pfx
      SSLServerKeyRingPW=C:\mqipt\samples\ssl\sslSample.pwd

   2. Open a command prompt and start MQIPT:

      C:
      cd \mqipt\bin
      mqipt .. -n ipt2

      where .. indicates that the MQIPT configuration file, mqipt.conf, is in the parent directory, and ipt2 is the name to be given to the instance of MQIPT. The following messages indicate that MQIPT has started successfully:

      5724-H72 (C) Copyright IBM Corp. 2000, 2020 All Rights Reserved
      MQCPI001 IBM MQ Internet Pass-Thru V9.2.0.0 starting
      MQCPI004 Reading configuration information from mqipt.conf
      MQCPI152 MQIPT name is ipt2
      MQCPI021 Password checking has been enabled on the command port
      MQCPI011 The path C:\mqipt\logs will be used to store the log files
      MQCPI006 Route 1416 has started and will forward messages to :
      MQCPI034 ....server1.company2.com(1414)
      MQCPI035 ....using MQ protocol
      MQCPI037 ....SSL Server side enabled with properties :
      MQCPI031 ......CipherSuites <null>
      MQCPI032 ......key ring file C:\mqipt\samples\ssl\sslSample.pfx
      MQCPI047 ......CA key ring file <null>
      MQCPI038 ......peer certificate uses UID=*,CN=*,T=*,OU=*,DC=*,O=*,
      	                                           STREET=*,L=*,ST=*,PC=*,C=*,DNQ=*
      MQCPI033 ......client authentication set to false
      MQCPI078 Route 1416 ready for connection requests

3. At a command prompt on the IBM MQ client system, enter the following commands:
   1. Set the MQSERVER environment variable:

      SET MQSERVER=MQIPT.CONN.CHANNEL/tcp/10.9.1.2(1415)

   2. Put a message:

      amqsputc MQIPT.LOCAL.QUEUE MQIPT.QM1
      Hello world

      Press Enter twice after typing the message string.
   3. Get the message:

      amqsgetc MQIPT.LOCAL.QUEUE MQIPT.QM1

      The message, "Hello world" is returned.

Parent topic: Getting started with IBM MQ Internet Pass-Thru