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.
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
- 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.
- A TTLSGroupAction statement enabling the rule. The
TTLSRule references the TTLSGroupAction using the
TTLSGroupActionRef property.
TTLSGroupAction CSQ1-GROUP-ACTION { TTLSEnabled ON }
- 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.
- 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 }
- 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 }
- 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 }
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
}
ALTER CHANNEL(channel-name) CHLTYPE(RCVR) SSLCIPH(' ')