Resetting SSL and TLS secret keys

IBM MQ supports the resetting of secret keys on queue managers and clients.

Secret keys are reset when a specified number of encrypted bytes of data have flowed across the channel. If channel heartbeats are enabled, the secret key is reset before data is sent or received following a channel heartbeat.

The key reset value is always set by the initiating side of the IBM MQ channel.

Queue manager

For a queue manager, use the command ALTER QMGR with the parameter SSLRKEYC to set the values used during key renegotiation.

On IBM i, use CHGMQM with the SSLRSTCNT parameter.

MQI client

By default, MQI clients do not renegotiate the secret key. We can make an MQI client renegotiate the key in any of three ways. In the following list, the methods are shown in order of priority. If you specify multiple values, the highest priority value is used.

1. By using the KeyResetCount field in the MQSCO structure on an MQCONNX call
2. By using the environment variable MQSSLRESET
3. By setting the SSLKeyResetCount attribute in the MQI client configuration file

These variables can be set to an integer in the range 0 through 999 999 999, representing the number of unencrypted bytes sent and received within a TLS conversation before the TLS secret key is renegotiated. Specifying a value of 0 indicates that TLS secret keys are never renegotiated. If you specify a TLS secret key reset count in the range 1 byte through 32 KB, TLS channels will use a secret key reset count of 32 KB. This is to avoid excessive key resets which would occur for small TLS secret key reset values.

If a value greater than zero is specified and channel heartbeats are enabled for the channel, the secret key is also renegotiated before message data is sent or received following a channel heartbeat.

The count of bytes until the next secret key renegotiation is reset after each successful renegotiation.

For full details of the MQSCO structure, see KeyResetCount (MQLONG). For full details of MQSSLRESET, see MQSSLRESET. For more information about the use of TLS in the client configuration file, see SSL stanza of the client configuration file.

Java

For IBM MQ classes for Java™, an application can reset the secret key in either of the following ways:

• By setting the sslResetCount field in the MQEnvironment class.
• By setting the environment property MQC.SSL_RESET_COUNT_PROPERTY in a Hashtable object. The application then assigns the hashtable to the properties field in the MQEnvironment class, or passes the hashtable to an MQQueueManager object on its constructor.

If the application uses more than one of these ways, the usual precedence rules apply. See Class com.ibm.mq.MQEnvironment for the precedence rules.

The value of the sslResetCount field or environment property MQC.SSL_RESET_COUNT_PROPERTY represents the total number of bytes sent and received by the IBM MQ classes for Java client code before the secret key is renegotiated. The number of bytes sent is the number before encryption, and the number of bytes received is the number after decryption. The number of bytes also includes control information sent and received by the IBM MQ classes for Java client.

If the reset count is zero, which is the default value, the secret key is never renegotiated. The reset count is ignored if no CipherSuite is specified.

JMS

For IBM MQ classes for JMS, the SSLRESETCOUNT property represents the total number of bytes sent and received by a connection before the secret key that is used for encryption is renegotiated. The number of bytes sent is the number before encryption, and the number of bytes received is the number after decryption. The number of bytes also includes control information sent and received by IBM MQ classes for JMS. For example, to configure a ConnectionFactory object that can be used to create a connection over a TLS enabled MQI channel with a secret key that is renegotiated after 4 MB of data have flowed, issue the following command to JMSAdmin:

ALTER CF(my.cf) SSLRESETCOUNT(4194304)

If the value of SSLRESETCOUNT is zero, which is the default value, the secret key is never renegotiated. The SSLRESETCOUNT property is ignored if SSLCIPHERSUITE is not set.

.NET

For .NET unmanaged clients, the integer property SSLKeyResetCount indicates the number of unencrypted bytes sent and received within a TLS conversation before the secret key is renegotiated.

For information about the use of object properties in IBM MQ classes for .NET, see Get and setting attribute values.

For .NET managed clients, the SSLStream class does not support secret key reset/renegotiation. However, to be consistent with other IBM MQ clients, the IBM MQ managed .NET client allows applications to set SSLKeyResetCount. For more information, see Secret key reset or renegotiation.

XMS .NET

For XMS .NET unmanaged clients, see Secure connections to an IBM MQ queue manager.