+

Search Tips | Advanced Search

Administer MQIPT using the TLS command port

From Version 9.2.0, MQIPT can be configured to use a TLS command port to listen for administrative commands issued by the mqiptAdmin command. Using the TLS command port protects sensitive data such as the MQIPT access password on the network between mqiptAdmin and MQIPT. Use this procedure to configure the TLS command port and administer MQIPT using the TLS command port.


About this task

The TLS command port must be configured with a server certificate stored either in a PKCS #12 key ring, or in cryptographic hardware that supports the PKCS #11 Cryptographic Token Interface. The command port server certificate is sent to the mqiptAdmin command during the TLS handshake. This task assumes that you request a new server certificate from a trusted Certificate Authority (CA), and that the certificate is returned to you in a file. The mqiptAdmin command validates the command port certificate using the CA certificate of the CA that signed the server certificate. The CA certificate must be stored in a PKCS #12 key ring that can be accessed by the mqiptAdmin command.

Client certificate authentication is not supported by the TLS command port. To enable authentication for administrative commands issued to a command port, see Command port authentication.

This procedure describes how to manage the key rings and digital certificates that are required to use the TLS command port by using the mqiptKeycmd (iKeyman) command-line interface (CLI). We can use the CLI by using the mqiptKeycmd command. For more information about other commands which can be used to manage key rings and digital certificates, see mqiptKeyman and mqiptKeycmd.


Procedure

  1. Follow these steps to configure the TLS command port for the instance of MQIPT.
    1. Create a PKCS #12 key ring file to be used by the TLS command port. The key ring is used to store the TLS command port server certificate. To create a key ring file using the CLI, enter the following command:
      mqiptKeycmd -keydb -create -db filename -pw password -type pkcs12
      where filename is the name of the key ring file to create, and password is the key ring password.
    2. Create a certificate request for the CA signed TLS command port server certificate. To create a certificate request using the iKeyman CLI, enter the following command:
      mqiptKeycmd -certreq -create -db filename -pw password
            -label label -size key_size -sig_alg algorithm
            -dn distinguished_name -file certreq_filename -type pkcs12
      where:

        -db filename
        Specifies the key ring file name.

        -pw password
        Specifies the key ring password.

        -label label
        Specifies the certificate label.

        -size key_size
        Specifies the key size.

        -sig_alg algorithm
        Specifies the asymmetric signature algorithm used for the creation of the entry's key pair.

        -dn distinguished_name
        Specifies the X.500 distinguished name enclosed in double quotation marks.

        -file certreq_filename
        Specifies the file name for the certificate request.

    3. Send the certificate request file created in step 1.b to your CA to be signed.
    4. After the CA sends you the signed certificate, receive the signed certificate into the key ring file. To receive the signed certificate into the key ring using the CLI, enter the following command:
      mqiptKeycmd -cert -receive -file cert_filename -db filename
            -pw password -type pkcs12
      where cert_filename is the name of the file containing the certificate, filename is the name of the key ring file, and password is the key ring password.
    5. Encrypt the key ring password using the mqiptPW command. Enter the following command:
      mqiptPW -sf encryption_key_file
      where encryption_key_file is the name of a file that contains the password encryption key for the MQIPT installation. You do not need to specify the -sf parameter if your MQIPT installation is using the default password encryption key. Type in the key ring password to encrypt when prompted.For more information about the mqiptPW command, see Encrypting a key ring password.
    6. Edit the mqipt.conf configuration file and specify the following properties to configure the TLS command port:
      1. Set the value of the SSLCommandPort property to the TLS command port number.
      2. Set the value of the SSLCommandPortKeyRing property to the file name of the key ring created in step 1.a.
      3. Set the value of the SSLCommandPortKeyRingPW to the string output by the mqiptPW command in step 1.e.
      4. Set the value of the SSLCommandPortSiteLabel property to the label name of the TLS command port certificate, specified when creating the certificate request in step 1.b.
      5. To restrict inbound connections to the TLS command port to those from a particular network interface, set the value of the SSLCommandPortListenerAddress property to a network address belonging to one of the network interfaces on the system where MQIPT is running. For example, to restrict inbound connections to the TLS command port to those only from the local machine, set the value of the SSLCommandPortListenerAddress property to localhost.

    7. Start or refresh MQIPT to enable the TLS command port. MQIPT issues console messages such as the following to display the TLS command port configuration that is in effect:
      MQCPI155 Listening for control commands on port 1882 on local address * using TLS
MQCPI139 ......secure socket protocols <NULL>
MQCPI031 ......cipher suites <NULL>
MQCPI032 ......key ring file c:\\iptHome\\ssl\\commandport.p12
MQCPI072 ......and certificate label mqiptadmin

  2. On the system where the mqiptAdmin command is used to administer MQIPT, follow these steps to enable mqiptAdmin to connect to the TLS command port.
    1. Create a PKCS #12 key ring to be used as a trust store by the mqiptAdmin command. To create a key ring file using the CLI, enter the following command:
      mqiptKeycmd -keydb -create -db filename -pw password -type pkcs12
      where filename is the name of the key ring file to create, and password is the key ring password.
    2. Import the CA certificate of the CA that signed the TLS command port certificate into the key ring that was created in step 2.a. To import the CA certificate using the iKeyman CLI, enter the following command:
      mqiptKeycmd -cert -add -db filename -pw password -type pkcs12
            -label certlabel -file cert_filename
      where:

        filename
        Specifies the key ring file name

        password
        Specifies the key ring password

        certlabel
        Specifies the label to be given to the CA certificate

        cert_filename
        Specifies the name of the file containing the CA certificate

    3. Encrypt the key ring password using the mqiptPW command. Enter the following command:
      mqiptPW -sf encryption_key_file
      where encryption_key_file is the name of the file that contains the password encryption key. The password encryption key file can be different to the one used to encrypt passwords in the MQIPT configuration. The default password encryption key is used if we do not specify an encryption key file with the -sf parameter. Type in the key ring password to encrypt when prompted.For more information about the mqiptPW command, see Encrypting a key ring password.
    4. Create a properties file to be used by the mqiptAdmin command and specify the following properties: 
      SSLClientCAKeyRing=key_ring_file_name
SSLClientCAKeyRingPW=key_ring_password
PasswordProtectionKeyFile=encryption_key_file
      where:

        key_ring_file_name
        is the name of the key ring file created in step 2.a.

        key_ring_password
        is the encrypted password output by the mqiptPW command in step 2.c.

        encryption_key_file
        is the name of the file that contains the password encryption key. We need to specify the PasswordProtectionKeyFile property only if an encryption key file was used to encrypt the key ring password in step 2.c.

    5. Issue the mqiptAdmin command to administer MQIPT, specifying the -s parameter to indicate that a TLS connection is required, and the -p parameter to specify the name of the properties file that was created in step 2.d. For example, enter the following command to refresh an instance of MQIPT by sending a refresh command to the TLS command port:
      mqiptAdmin -refresh -r hostname:port -s -p properties_file
      The mqiptAdmin command issues a message such as the following to confirm that the connection to MQIPT is protected with TLS:
      MQCAI109 The connection to MQIPT is secured with TLSv1.2.


What to do next

To enable authentication for commands received by the TLS command port, follow the steps in Command port authentication. Parent topic: Administer MQIPT by using the command line

Last updated: 2020-10-04