Encrypting passphrases for MQTT TLS channels

You can encrypt passphrases for MQTT TLS channels with the MQXR service STARTARG option -sf.

About this task

When a channel is created or altered, the passphrase is encrypted using a credentials key file. This key file is specified by using the -sf option in the STARTARG parameter when you define the MQXR service. The encrypted passphrases are stored in the platform-specific properties file, mqxr_win.properties or mqxr_unix.properties.

This task assumes that an MQXR service is defined on your system. You can configure the MXQR service, including the steps to specify a credentials key file, by using the following topics:

Procedure

  1. Ensure that you know the passphrases for each MQTT TLS channel.
  2. Stop the MQXR service SYSTEM.MQXR.SERVICE:
    1. In the Navigator view, click the Services folder.
    2. Right-click SYSTEM.MQXR.SERVICE and then click Stop.
  3. Alter the MQXR service SYSTEM.MQXR.SERVICE to add the STARTARG option -sf and provide the credentials key file to be used for encryption:
    1. Right-click SYSTEM.MQXR.SERVICE and then click Properties.
    2. In the Start args field, edit the text to add the -sf option.
      For example, on Windows, to encrypt passphrases with a user defined key that is stored in c:\keyfile.txt, edit the text to the following text:
      STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+" 
      -sf "c:\keyfile.txt"')
      For example, to encrypt passphrases using the DEFAULT key edit the text to the following text:
      STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+" 
      -sf "[DEFAULT]"')
      Note that the DEFAULT word has to be enclosed with square bracket, that is [DEFAULT].
      CAUTION:
      The default initial key is the same for all IBM MQ installations. To protect passwords securely, supply an initial key that is unique to your installation when you encrypt passwords.
  4. Start the MQXR service SYSTEM.MQXR.SERVICE:
    1. In the Navigator view, click the Services folder.
    2. Right-click SYSTEM.MQXR.SERVICE and then click Start.
  5. Change the TLS channel passphrases

    Do this through IBM MQ Explorer, or by using the MQSC ALTER CHANNEL (MQTT) command.

    Passphrases are encrypted using the credentials key file provided by the -sf option in step 3

  6. 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.