Configuring AT-TLS on an inbound channel from an IBM MQ for Multiplatforms queue manager using a single, named CipherSpec

How you set up AT-TLS on an inbound channel from an IBM® MQ for Multiplatforms queue manager to an IBM MQ for z/OS® queue manager. In this case, the channel on the z/OS queue manager is a receiver channel which does not have the SSLCIPH attribute set, and the channel on the non-z/OS queue manager is a sender channel with the SSLCIPH attribute set to a single, named CipherSpec.

Diagram showing an existing sender-receiver channel pair using the TLS 1.2 TLS_AES_256_GCM_SHA384 CipherSpec being adjusted so that the receiver channel uses AT-TLS instead of IBM MQ TLS.

In this example an existing sender – receiver channel pair, which uses the TLS 1.2 TLS_RSA_WITH_AES_256_GCM_SHA384 CipherSpec is going to be adjusted so that the receiver channel uses AT-TLS instead of IBM MQ TLS.

Other TLS protocols and CipherSpecs can be used by making minor adjustments to the configuration. Other message channel types, apart from cluster-sender and cluster-receiver channels, could be used with no change to the AT-TLS configuration.

Procedure

Step 1: Stop the channel

Step 2: Create and apply an AT-TLS policy

You need to create the following AT-TLS statements for this scenario:
  1. A TTLSRule statement to match inbound connections to the channel initiator address space from the IP address of the sender channel. Here, further filtering has been included to match a specific channel initiator job name.
    
    TTLSRule                      REMOTE-TO-CSQ1
    {
      LocalAddr                   ALL
      LocalPortRange              1414
      RemoteAddr                  123.456.78.9
      Jobname                     CSQ1CHIN
      Direction                   INBOUND
      TTLSGroupActionRef          CSQ1-GROUP-ACTION 
      TTLSEnvironmentActionRef    CSQ1-INBOUND-ENVIRONMENT-ACTION
    }

    The preceding rule matches against connections coming into the CSQ1CHIN job on local port 1414 from remote IP address 123.456.78.9.

    More advanced filtering options are described at TTLSRule.

  2. A TTLSGroupAction statement enabling the rule. The TTLSRule references the TTLSGroupAction using the TTLSGroupActionRef property.
    
    TTLSGroupAction             CSQ1-GROUP-ACTION
    {
      TTLSEnabled               ON
    }
  3. A TTLSEnvironmentAction statement is associated with the TTLSRule by the TTLSEnvironmentActionRef property. A TTLSEnvironmentAction configures the TLS Environment and specifies which key ring to use.
    
    TTLSEnvironmentAction                 CSQ1-INBOUND-ENVIRONMENT-ACTION
    {
      HandshakeRole                       SERVER
      TTLSKeyringParmsRef                 CSQ1-KEYRING
      TTLSCipherParmsRef                  CSQ1-CIPHERPARM
      TTLSEnvironmentAdvancedParmsRef     CSQ1-ENVIRONMENT-ADVANCED
    }

    AT-TLS provides the capability to provide mutual authentication, which is the equivalent of using the SSLCAUTH channel attribute. This is done by having an TTLSEnvironmentAction statement with a HandshakeRole value of ServerWithClientAuth for the inbound TTLSEnvironmentAction statement.

  4. A TTLSKeyringParms statement is associated with the TTLSEnvironmentAction by the TTLSKeyringParmsRef property and defines the key ring used by AT-TLS.
    The key ring should contain certificates trusted by the remote non-z/OS queue manager. This key ring can be defined in the same way as a key ring used by the channel initiator; see Configuring your z/OS system to use TLS.
    
    TTLSKeyringParms            CSQ1-KEYRING
    {
      Keyring                   MQCHIN/CSQ1RING
    }
  5. A TTLSCipherParms statement associated with the TTLSEnvironmentAction by the TTLSCipherParmsRef property.
    This statement must contain a single cipher suite name which must be the equivalent of the IBM MQ CipherSpec name used on the remote sender channel.
    Note: AT-TLS cipher suite names do not necessarily match IBM MQ CipherSpec names. However, it is possible to find the AT-TLS cipher suite name that matches an IBM MQ CipherSpec name by finding the IBM MQ CipherSpec name from the following table and cross-referencing the four-character code column with the expanded character column from Table 2 in the TTLSCipherParms topic.
    Table 1. Convert from four-character codes to CipherSpec names
    Four-character code Protocol Enabled by default CipherSpec name
    0001 SSL 3.0 No NULL_MD5
    0002 SSL 3.0 No NULL_SHA
    0003 SSL 3.0 No RC4_MD5_EXPORT
    0004 SSL 3.0 No RC4_MD5_US
    0005 SSL 3.0 No RC4_SHA_US
    0006 SSL 3.0 No RC2_MD5_EXPORT
    0008 SSL 3.0 No DES_SHA_EXPORT
    0009 TLS 1.0 Yes TLS_RSA_WITH_DES_CBC_SHA
    000A SSL 3.0 No TRIPLE_DES_SHA_US
    000A TLS 1.0 Yes TLS_RSA_WITH_3DES_EDE_CBC_SHA
    002F TLS 1.0 Yes TLS_RSA_WITH_AES_128_CBC_SHA
    0035 TLS 1.0 Yes TLS_RSA_WITH_AES_256_CBC_SHA
    003B TLS 1.2 Yes TLS_RSA_WITH_NULL_SHA256
    003C TLS 1.2 Yes TLS_RSA_WITH_AES_128_CBC_SHA256
    003D TLS 1.2 Yes TLS_RSA_WITH_AES_256_CBC_SHA256
    C023 TLS 1.2 Yes ECDHE_ECDSA_AES_128_CBC_SHA256
    C024 TLS 1.2 Yes ECDHE_ECDSA_AES_256_CBC_SHA384
    C027 TLS 1.2 Yes ECDHE_RSA_AES_128_CBC_SHA256
    C028 TLS 1.2 Yes ECDHE_RSA_AES_256_CBC_SHA384
    
    TTLSCipherParms             CSQ1-CIPHERPARM
    {
      V3CipherSuites            TLS_RSA_WITH_AES_256_GCM_SHA384
    }
    
  6. A TTLSEnvironmentAdvancedParms statement is associated with the TTLSEnvironmentAction by the TTLSEnvironmentAdvancedParmsRef property.
    This statement can be used to specify which SSL and TLS protocols are enabled. With IBM MQ you should enable only the single protocol that matches the cipher suite name used on the TTLSCipherParms statement.
    TTLSEnvironmentAdvancedParms CSQ1-ENVIRONMENT-ADVANCED
    {
      SSLv3          OFF
      TLSv1          OFF
      TLSv1.1        OFF
      SecondaryMap   OFF
      TLSv1.2        ON
      TLSv1.3        OFF
    }
    
The complete set of statements are as follows and should be applied to the policy agent :

TTLSRule                      REMOTE-TO-CSQ1
{
  LocalAddr                   ALL
  LocalPortRange              1414
  RemoteAddr                  123.456.78.9  
  Jobname                     CSQ1CHIN
  Direction                   INBOUND
  TTLSGroupActionRef          CSQ1-GROUP-ACTION 
  TTLSEnvironmentActionRef    CSQ1-INBOUND-ENVIRONMENT-ACTION
}                                              

TTLSGroupAction             CSQ1-GROUP-ACTION
{
  TTLSEnabled               ON
} 

TTLSEnvironmentAction             CSQ1-INBOUND-ENVIRONMENT-ACTION
{
  HandshakeRole                   CLIENT
  TTLSKeyringParmsRef             CSQ1-KEYRING
  TTLSCipherParmsRef              CSQ1-CIPHERPARM
  TTLSEnvironmentAdvancedParmsRef CSQ1-ENVIRONMENT-ADVANCED
}

TTLSKeyringParms            CSQ1-KEYRING
{
  Keyring                   MQCHIN/CSQ1RING
}

TTLSCipherParms             CSQ1-CIPHERPARM
{
  V3CipherSuites            TLS_RSA_WITH_AES_256_GCM_SHA384
}

TTLSEnvironmentAdvancedParms CSQ1-ENVIRONMENT-ADVANCED
{
  SSLv3          OFF
  TLSv1          OFF
  TLSv1.1        OFF
  SecondaryMap   OFF
  TLSv1.2        OFF
  TLSv1.3        ON
}  

Step 3: Remove SSLCIPH from the z/OS channel

Remove the CipherSpec from the z/OS channel using the following command:
ALTER CHANNEL(channel-name) CHLTYPE(RCVR) SSLCIPH(' ')

Step 4: Start the channel

Once the channel has started it will be using a combination of AT-TLS and IBM MQ TLS.
Attention: The preceding AT-TLS statements are only a minimal configuration. There are other AT-TLS policy statements with AT-TLS which are not documented here, and could be used with IBM MQ depending on need. However, IBM MQ has only been tested with the policies described.