Authenticating a TLS client and server

You can run MQIPT as both a TLS server and client to terminate the incoming TLS session and forward data to the destination by using a separate TLS connection.

Before you begin

Complete the steps that are listed in Getting started with IBM MQ Internet Pass-Thru.
Read the topic SSL/TLS support in MQIPT.

Note: This scenario uses self-signed certificates for convenience. Do not use any self-signed certificates in production environments. Instead, obtain certificates that are signed by a trusted certificate authority (CA).

About this task

The connection is made between an IBM MQ client and a IBM MQ server through a single instance of MQIPT. The connections between the IBM MQ client and MQIPT, and between MQIPT and the IBM MQ server, both use TLS. Therefore, the MQIPT route is both a TLS server and a TLS client.

During the TLS handshake between the client and MQIPT, the client and MQIPT send their certificates to each other to authenticate the connection. When the connection between the client and MQIPT is established, MQIPT establishes a separate TLS connection to the IBM MQ server. MQIPT and the IBM MQ server send their certificates to each other to authenticate the connection.

See text. — Figure 1. SSL/TLS server and client network diagram

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

Procedure

To configure an MQIPT route as both a TLS server and a TLS client, complete the following steps:

On the system where the client runs, complete the following steps to configure the IBM MQ client to use a TLS connection.
1. Create a key repository for the client.
  Enter the following command to create a new key repository named clientkey.kdb in the C:\ProgramData\IBM\MQ directory:
```
runmqakm -keydb -create -db C:\ProgramData\IBM\MQ\clientkey.kdb -pw password -stash
```
  where password is the key repository password.
  For more information, see Setting up a key repository on AIX®, Linux®, and Windows.
2. Create a personal certificate for the client, in the client key repository that you created in step 1.a.
  Enter the following command to create a new self-signed certificate with the label clientcert for the client:
```
runmqakm -cert -create -db C:\ProgramData\IBM\MQ\clientkey.kdb -stashed
         -label clientcert -dn CN=Client
```
  For more information, see Creating a self-signed personal certificate on AIX, Linux, and Windows.
3. Extract the certificate from the client key repository.
  Enter the following command to extract the client certificate:
```
runmqakm -cert -extract -db C:\ProgramData\IBM\MQ\clientkey.kdb -stashed -label clientcert
         -target C:\ProgramData\IBM\MQ\client.crt -format ascii
```
  For more information, see Extracting the public part of a self-signed certificate from a key repository on AIX, Linux, and Windows.
4. Copy the extracted certificate file to the system where MQIPT runs.
On the system where the IBM MQ server runs, complete the following steps to configure the queue manager to use a TLS connection.
1. Create a key repository for the queue manager.
  Enter the following command to create a new key repository named key.kdb for the queue manager.
```
runmqakm -keydb -create -db C:\ProgramData\IBM\MQ\qmgrs\MQIPT!QM1\ssl\key.kdb -pw password -stash
```
  where password is the key repository password.
  Ensure that the mqm user is granted read access to the C:\ProgramData\IBM\MQ\qmgrs\MQIPT!QM1\ssl\key.sth stash file that the command creates to store the encrypted key repository password.
  For more information, see Setting up a key repository on AIX, Linux, and Windows.
2. Create a personal certificate for the queue manager, in the queue manager key repository that you created in step 2.a.
  Enter the following command to create a new self-signed certificate with the label ibmwebspheremqmqipt.qm1 for the queue manager:
```
runmqakm -cert -create -db C:\ProgramData\IBM\MQ\qmgrs\MQIPT!QM1\ssl\key.kdb -stashed
         -label ibmwebspheremqmqipt.qm1 -dn CN=MQIPT.QM1
```
  For more information, see Creating a self-signed personal certificate on AIX, Linux, and Windows.
3. Extract the certificate from the queue manager key repository.
  Enter the following command to extract the queue manager certificate:
```
runmqakm -cert -extract -db C:\ProgramData\IBM\MQ\qmgrs\MQIPT!QM1\ssl\key.kdb -stashed -label ibmwebspheremqmqipt.qm1
         -target C:\ProgramData\IBM\MQ\qmgrs\MQIPT!QM1\ssl\mqipt.qm1.crt -format ascii
```
  For more information, see Extracting the public part of a self-signed certificate from a key repository on AIX, Linux, and Windows.
4. Copy the extracted certificate file to the system where MQIPT runs.
5. Issue the following MQSC command to alter the MQIPT.CONN.CHANNEL server connection channel to use TLS:
```
ALTER CHANNEL(MQIPT.CONN.CHANNEL) CHLTYPE(SVRCONN) TRPTYPE(TCP) SSLCIPH(ANY_TLS12_OR_HIGHER)
```
On the system where MQIPT runs, complete the following steps to configure the MQIPT route to use TLS.
1. Create a personal certificate for MQIPT in a PKCS #12 key repository.
  Enter the following command to create a new self-signed certificate with the label mqiptcert:
```
mqiptKeytool -genkeypair -keystore C:\mqiptHome\ssl\mqipt.p12 -storetype pkcs12 -storepass password
            -alias mqiptcert -dname "CN=MQIPT Test Certificate"
            -keyalg RSA -keysize 2048 -sigalg SHA256WithRSA
```
  where password is the key repository password.
2. Enter the following command to add the client certificate and the queue manager certificate to the MQIPT key repository:
```
mqiptKeytool -importcert -keystore C:\mqiptHome\ssl\mqipt.p12 -storetype pkcs12 -storepass password -file client.crt
mqiptKeytool -importcert -keystore C:\mqiptHome\ssl\mqipt.p12 -storetype pkcs12 -storepass password -file mqipt.qm1.crt
```
  where password is the key repository password, client.crt is the client certificate file that you created in step 1.c, and mqipt.qm1.crt is the queue manager certificate that you created in step 2.c.
3. Extract the MQIPT certificate from the key repository.
  Enter the following command to extract the MQIPT certificate:
```
mqiptKeytool -exportcert -keystore C:\mqiptHome\ssl\mqipt.p12 -storetype pkcs12 -storepass password
            -alias mqiptcert -file C:\mqiptHome\ssl\mqipt.crt -rfc
```
  where password is the key repository password.
4. Copy the extracted certificate file to both the system where the client runs and the system where the IBM MQ server runs.
5. Enter the following command to encrypt the MQIPT key repository password:
```
mqiptPW
```
  When prompted, enter the key repository password that you specified when you created the key repository in step 3.a.
6. Edit the mqipt.conf file and add the following route definition:
```
[route]
ListenerPort=1415
Destination=server1.company2.com
DestinationPort=1414
SSLServer=true
SSLServerKeyRing=C:\\mqiptHome\\ssl\\mqipt.p12
SSLServerKeyRingPW=encrypted_password
SSLClient=true
SSLClientKeyRing=C:\\mqiptHome\\ssl\\mqipt.p12
SSLClientKeyRingPW=encrypted_password
```
  where encrypted_password is the encrypted key repository password created by running the mqiptPW command in step 3.e.
Add the MQIPT certificate to both the client key repository and the queue manager key repository.
1. On the system where the client runs, enter the following command to add the MQIPT certificate to the client key repository:
```
runmqakm -cert -add -db C:\ProgramData\IBM\MQ\clientkey.kdb -stashed
         -label mqiptcert -file mqipt.crt -format ascii
```
  where mqipt.crt is the MQIPT certificate file that you created in step 3.c.
2. On the system where the IBM MQ server runs, enter the following command to add the MQIPT certificate to the queue manager key repository:
```
runmqakm -cert -add -db C:\ProgramData\IBM\MQ\qmgrs\MQIPT!QM1\ssl\key.kdb -stashed
         -label mqiptcert -file mqipt.crt -format ascii
```
  where mqipt.crt is the MQIPT certificate file that you created in step 3.c.
For more information, see Adding a CA certificate (or the public part of a self-signed certificate) into a key repository, on AIX, Linux, and Windows systems.

On the system where MQIPT runs, open a command prompt and enter the following commands to 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, 2026. All Rights Reserved
MQCPI001 IBM MQ Internet Pass-Thru V9.4.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 is starting and will forward messages to :
MQCPI034 ....server1.company2.com(1414)
MQCPI035 ....using MQ protocol
MQCPI036 ....SSL Client side enabled with properties :
MQCPI139 ......secure socket protocols <NULL>
MQCPI031 ......cipher suites <NULL>
MQCPI032 ......key ring file C:\\mqiptHome\\ssl\\mqipt.p12
MQCPI047 ......CA key ring file <NULL>
MQCPI071 ......site certificate uses UID=*,CN=*,T=*,OU=*,DC=*,O=*,STREET=*,L=*,ST=*,PC=*,C=*,DNQ=*
MQCPI038 ......peer certificate uses UID=*,CN=*,T=*,OU=*,DC=*,O=*,STREET=*,L=*,ST=*,PC=*,C=*,DNQ=*
MQCPI037 ....SSL Server side enabled with properties :
MQCPI139 ......secure socket protocols <NULL>
MQCPI031 ......cipher suites <NULL>
MQCPI032 ......key ring file C:\\mqiptHome\\ssl\\mqipt.p12
MQCPI047 ......CA key ring file <NULL>
MQCPI071 ......site certificate uses UID=*,CN=*,T=*,OU=*,DC=*,O=*,STREET=*,L=*,ST=*,PC=*,C=*,DNQ=*
MQCPI038 ......peer certificate uses UID=*,CN=*,T=*,OU=*,DC=*,O=*,STREET=*,L=*,ST=*,PC=*,C=*,DNQ=*
MQCPI033 ......client authentication set to false
MQCPI078 Route 1415 ready for connection requests

At a command prompt on the IBM MQ client system, enter the following command to run the TLS sample program:
```
AMQSSSLC -m MQIPT.QM1 -c MQIPT.CONN.CHANNEL -x 10.9.1.2(1415)
         -k "C:\ProgramData\IBM\MQ\clientkey" -l clientcert -s ANY_TLS12_OR_HIGHER
```
The following message indicates that the application connected successfully to the queue manager:
```
Connection established to queue manager MQIPT.QM1
```