Configuring AT-TLS on an outbound channel to an IBM MQ for Multiplatforms queue manager using alias CipherSpecs

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

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

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

Other TLS protocols and CiperSpecs 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:

A TTLSRule statement to match outbound connections from the channel initiator address space to the IP address and port number of the target receiver channel. These values should match the information used in the CONNAME of the sender channel. Here, further filtering has been included to match a specific channel initiator job name.
```
TTLSRule                      CSQ1-TO-REMOTE
{
  LocalAddr                   ALL
  RemoteAddr                  123.456.78.9
  RemotePortRange             1414
  Jobname                     CSQ1CHIN
  Direction                   OUTBOUND
  TTLSGroupActionRef          CSQ1-GROUP-ACTION 
  TTLSEnvironmentActionRef    CSQ1-OUTBOUND-ENVIRONMENT-ACTION
}  
```
The preceding rule matches against connections going to IP address 123.456.78.9 on port 1414 from the CSQ1CHIN job.

More advanced filtering options are described at TTLSRule.
A TTLSGroupAction statement enabling the rule. The TTLSRule references the TTLSGroupAction using the TTLSGroupActionRef property.
```
TTLSGroupAction             CSQ1-GROUP-ACTION
{
  TTLSEnabled               ON
} 
```

A TTLSEnvironmentAction statement associated with the TTLSRule by the TTLSEnvironmentActionRef property. A TTLSEnvironmentAction configures the TLS Environment and specifies which key ring to use.


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

A TTLSKeyringParms statement 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
}
```

A TTLSCipherParms statement associated with the TTLSEnvironmentAction by the TTLSCipherParmsRef property.

This statement must contain one or more cipher suite names, at least one of which should be compatible with the set of CipherSpecs implied by the alias CipherSpec used on the target receiver 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 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_CHACHA20_POLY1305_SHA256
  V3CipherSuites            TLS_AES_256_GCM_SHA384
  V3CipherSuites            TLS_AES_128_GCM_SHA256 
}

Attention: If both the queue manager and AT-TLS policy support TLS 1.3, only alias CipherSpecs that contain at least one TLS 1.3 CipherSpec allow the channel to start. For example, using ANY_TLS12 results in the channel failing to start, even if TTLSCipherParms contains TLS 1.2 CipherSpecs, but using ANY_TLS12_OR_HIGHER or ANY_TLS13 allows the channel to start. See Relationship between alias CipherSpec settings for an explanation.

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, and should be consistent with the cipher suites in 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                      CSQ1-TO-REMOTE
{
  LocalAddr                   ALL
  RemoteAddr                  123.456.78.9
  RemotePortRange             1414
  Jobname                     CSQ1CHIN
  Direction                   OUTBOUND
  TTLSGroupActionRef          CSQ1-GROUP-ACTION 
  TTLSEnvironmentActionRef    CSQ1-OUTBOUND-ENVIRONMENT-ACTION
}                                              

TTLSGroupAction             CSQ1-GROUP-ACTION
{
  TTLSEnabled               ON
} 

TTLSEnvironmentAction             CSQ1-OUTBOUND-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_CHACHA20_POLY1305_SHA256
  V3CipherSuites            TLS_AES_256_GCM_SHA384
  V3CipherSuites            TLS_AES_128_GCM_SHA256 

}

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(SDR) 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.