[z/OS]

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.

See Configuring AT-TLS on an inbound channel from an IBM MQ for Multiplatforms queue manager using an alias CipherSpec for an example using an alias CipherSpec.

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

Diagram showing an existing sender-receiver channel pair using the TLS1.3 TLS_AES_256_GCM_SHA384 CipherSpec being 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 in the following table and cross-referencing the hexadecimal code column with the expanded character column from Table 2 in the TTLSCipherParms statement topic.
    Table 1. CipherSpecs on z/OS from IBM MQ for z/OS 9.2.0
    CipherSpec Protocol Hexadecimal code Enabled by default
    TLS_CHACHA20_POLY1305_SHA256 TLS 1.3 1303 Yes
    TLS_AES_256_GCM_SHA384 TLS 1.3 1302 Yes
    TLS_AES_128_GCM_SHA256 TLS 1.3 1301 Yes
    TLS_RSA_WITH_AES_256_GCM_SHA384 TLS 1.2 009D Yes
    ECDHE_RSA_AES_256_GCM_SHA384 TLS 1.2 C030 Yes
    TLS_RSA_WITH_AES_256_CBC_SHA256 TLS 1.2 003D Yes
    ECDHE_ECDSA_AES_256_CBC_SHA384 TLS 1.2 C024 Yes
    ECDHE_RSA_AES_256_CBC_SHA384 TLS 1.2 C028 Yes
    TLS_RSA_WITH_AES_128_GCM_SHA256 TLS 1.2 009C Yes
    ECDHE_RSA_AES_128_GCM_SHA256 TLS 1.2 C02F Yes
    TLS_RSA_WITH_AES_128_CBC_SHA256 TLS 1.2 003C Yes
    ECDHE_ECDSA_AES_128_CBC_SHA256 TLS 1.2 C023 Yes
    ECDHE_RSA_AES_128_CBC_SHA256 TLS 1.2 C027 Yes
    TLS_RSA_WITH_NULL_SHA256 TLS 1.2 003B No
    TLS_RSA_WITH_AES_256_CBC_SHA TLS 1.0 0035 No
    TLS_RSA_WITH_AES_128_CBC_SHA TLS 1.0 002F No
    TLS_RSA_WITH_3DES_EDE_CBC_SHA TLS 1.0 000A No
    TLS_RSA_WITH_RC4_128_SHA TLS 1.0 0005 No
    TLS_RSA_WITH_DES_CBC_SHA TLS 1.0 0009 No
    TRIPLE_DES_SHA_US SSL v3 000A No
    RC4_SHA_US SSL v3 0005 No
    RC4_MD5_US SSL v3 0004 No
    DES_SHA_EXPORT SSL v3 0009 N
    RC4_MD5_EXPORT SSL v3 0003 No
    RC2_MD5_EXPORT SSL v3 0006 No
    NULL_SHA SSL v3 0002 No
    NULL_MD5 SSL v3 0001 No 
    
TTLSCipherParms             CSQ1-CIPHERPARM
{
  V3CipherSuites            TLS_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        OFF
  TLSv1.3        ON
}
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                   SERVER
  TTLSKeyringParmsRef             CSQ1-KEYRING
  TTLSCipherParmsRef              CSQ1-CIPHERPARM
  TTLSEnvironmentAdvancedParmsRef CSQ1-ENVIRONMENT-ADVANCED
}

TTLSKeyringParms            CSQ1-KEYRING
{
  Keyring                   MQCHIN/CSQ1RING
}

TTLSCipherParms             CSQ1-CIPHERPARM
{
  V3CipherSuites            TLS_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.