Encryption of passphrases for MQTT TLS channels

IBM® MQ 9.2.4 provides support for encryption of passphrases for MQTT TLS channels. Two additional MQXR service STARTARG options, -sf and -sp have been added.

About this task

The -sf option provides a credentials key file for encryption of MQTT TLS channel passphrases. Note that, for convenience, a default key is provided.

The -sp option specifies the protection mode. The default value is 2 to use the more secure credentials protection method. See Defining the MQXR service manually on Linux or Defining the MQXR service manually on Windows for more information, depending on the operating systems your enterprise uses.

When a channel is created or altered, the passphrases are encrypted using the credentials key file provided for the -sf option. Encrypted passphrases are stored in the platform-specific properties file, mqxr_win.properties or mqxr_unix.properties.

Example of an encrypted passphrase stored in the platform-specific properties file:

com.ibm.mq.MQXR.channel.SSL.PassPhrase=<MQXR>2!kvAzYv/1aCMfSQ5igkFVmQ==
!f4rX5KL7aFKHJl7Ln0X+OQ==

Example to encrypt passphrases using the default key:

STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+" 
-sf "[DEFAULT]"')

where DEFAULT means the default key is used for encryption of passphrases.

Attention: The DEFAULT word has to be enclosed with square bracket, that is [DEFAULT].

Example to encrypt passphrases with a user defined key in keyfile.txt:

STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+" 
-sf "c:\pathOfKeyfile\keyfile.txt"')

Creating the SYSTEM.MQXR.SERVICE on Linux®, and Creating the SYSTEM.MQXR.SERVICE on Windows are updated to specify the default key to use the default key for encrypting MQTT TLS channels.

You can also define the MQXR service manually by performing a list of steps. For more information, see Defining the MQXR service manually on Windows and Defining the MQXR service manually on Linux.

If you want to change the credentials key file used for encrypting the passphrases, carry out the following procedure.

Procedure

Ensure that you know the passphrases for each MQTT TLS channel.
Stop the MQXR service SYSTEM.MQXR.SERVICE.
Alter the MQXR service SYSTEM.MQXR.SERVICE to add the STARTARG option -sf and provide the credentials key file to be used for encryption.
For example, to encrypt passphrases using the DEFAULT key, issue the following command:
```
STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+" 
-sf "[DEFAULT]"')
```
Similarly, to encrypt passphrases with a user defined key in keyfile.txt, issue the following command:
```
STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+" 
-sf "c:\pathToKeyfile\keyfile.txt"')
```
Start the MQXR service SYSTEM.MQXR.SERVICE.
Change the TLS channel passphrases through IBM MQ Explorer, or by using the MQSC ALTER CHANNEL (MQTT) command.
Passphrases will be encrypted using the credentials key file provided by the -sf option in step 3
Start the channels to use the new encrypted passphrase.
Notes:
- In the preceding steps, if you do not alter the channel after restarting the service, a channel with a plain text passphrase fails to start. An error is logged to indicate that the passphrase needs to be updated.
- If you want to turn off encryption, carry out the same procedure, but in step 3 start the MQXR service without specifying the -sf option.
For migration of this process, see Migration of plain text passphrases to encrypted passphrases.
Attention: MQXR still supports plain text passphrase, but you should encrypt all MQTT TLS channel passphrases in your enterprise.