SSL stanza of the client configuration file

Use the SSL stanza to specify information about the use of TLS.

Note: The description of each attribute of this stanza indicates which IBM® MQ clients can read that attribute. For a summary table for all IBM MQ MQI client configuration file stanzas, see Which IBM MQ attributes can be read by each client.

The following attributes can be included in the SSL stanza:

AllowOutboundSNI = YES|NO
If enabled, SNI capable clients will set SNI to the target IBM MQ channel name to the remote system when initiating a TLS connection. If this attribute is set to NO, SNI capable clients will not set the SNI header causing outbound connection requests to receive the remote queue manager's default certificate during the TLS handshake, and so per-channel certificates cannot be used.

This attribute can be read by C and unmanaged .NET clients.

[UNIX, Linux, Windows][V9.1.4 Dec 2019]AllowTLSV13=Y|YES|T|TRUE|N|NO|F|FALSE
Specifies whether a queue manager is able to use the TLS 1.3 CipherSpecs (see Enabling CipherSpecs).

This attribute can be read by C/C++ clients.

This attribute has the following possible values:
  • Y, YES, T, or TRUE: Enables TLS 1.3 which allows the queue manager to use the TLS 1.3 CipherSpecs.
  • N, NO, F, or FALSE: Disables TLS 1.3, which means that the queue manager is unable to use the TLS 1.3 CipherSpecs.
Note: When using the MQI client, the value of AllowTLSV13 is inferred unless it is explicitly specified in the SSL stanza of the mqclient.ini file being used by the application. For more information, see IBM MQ MQI client and TLS 1.3.
CDPCheckExtensions = YES|NO

CDPCheckExtensions specifies whether TLS channels on this queue manager try to check CDP servers that are named in CrlDistributionPoint certificate extensions.

This attribute can be read by C and unmanaged .NET clients.

This attribute has the following possible values:
  • YES: TLS channels try to check CDP servers to determine whether a digital certificate is revoked.
  • NO: TLS channels do not try to check CDP servers. This value is the default.
CertificateLabel = string
The certificate label of the channel definition.

This attribute can be read by C and unmanaged .NET clients.

See Certificate label (CERTLABL) for more information.

CertificateValPolicy = string
Determines the type of certificate validation used.

This attribute can be read by C and unmanaged .NET clients.

This attribute has the following possible values:
ANY
Use any certificate validation policy supported by the underlying secure sockets library. This setting is the default setting.
RFC5280
Use only certificate validation which complies with the RFC 5280 standard.
ClientRevocationChecks = REQUIRED|OPTIONAL|DISABLED
Determines how certificate revocation checking is configured if the client connect call uses a TLS channel. See also OCSPAuthentication.

This attribute can be read by C and unmanaged .NET clients.

This attribute has the following possible values:
REQUIRED (default)
Attempts to load certificate revocation configuration from the CCDT and perform revocation checking as configured. If the CCDT file cannot be opened or it is not possible to validate the certificate (because an OCSP or CRL server is not available, for example) the MQCONN call fails. No revocation checking is performed if the CCDT contains no revocation configuration but this does not cause the channel to fail.

[Windows]On Windows systems, you can also use Active Directory for CRL revocation checking. You cannot use Active Directory for OCSP revocation checking.

OPTIONAL
As for REQUIRED, but if it is not possible to load the certificate revocation configuration, the channel does not fail.
DISABLED
No attempt is made to load certificate revocation configuration from the CCDT and no certificate revocation checking is done.
Note: If you are using MQCONNX rather than MQCONN calls, you might choose to supply authentication information records (MQAIR) via the MQSCO. The default behavior with MQCONNX is therefore not to fail if the CCDT file cannot be opened but to assume that you are supplying an MQAIR (even if you choose not to do so).
EncryptionPolicySuiteB = string
Determines whether a channel uses Suite-B compliant cryptography and what level of strength is to be used.

This attribute can be read by C and unmanaged .NET clients.

This attribute has the following possible values:
NONE
Suite-B compliant cryptography is not used. This setting is the default setting.
128_BIT,192_BIT
Sets the security strength to both 128-bit and 192-bit levels.
128_BIT
Sets the security strength to 128-bit level.
192_BIT
Sets the security strength to 192-bit level.
[UNIX, Linux, Windows][V9.1.4 Dec 2019]MinimumRSAKeySize=int

Specifies the minimum keysize that RSA certificates must have in order to be accepted. Allows any value equal to 0 or above. Defaults to 1 if not specified.

This attribute can be read by C/C++ clients.

OCSPAuthentication = OPTIONAL|REQUIRED|WARN
Defines the behavior of IBM MQ when OCSP is enabled and the OCSP revocation check is unable to determine the certificate revocation status. See also ClientRevocationChecks.

This attribute can be read by C and unmanaged .NET clients.

This attribute has the following possible values:
OPTIONAL
Any certificate with a revocation status that cannot be determined by OCSP checking is accepted and no warning or error message is generated. The SSL or TLS connection continues as if no revocation check had been made.
REQUIRED
OCSP checking must yield a definitive revocation result for every SSL or TLS certificate which is checked. Any SSL or TLS certificate with a revocation status that cannot be verified is rejected with an error message. If queue manager SSL event messages are enabled, an MQRC_CHANNEL_SSL_ERROR message with a ReasonQualifier of MQRQ_SSL_HANDSHAKE_ERROR is generated. The connection is closed.

This value is the default value.

WARN
A warning is reported in the queue manager error logs if an OCSP revocation check is unable to determine the revocation status of any SSL or TLS certificate. If queue manager SSL event messages are enabled, an MQRC_CHANNEL_SSL_WARNING message with a ReasonQualifier of MQRQ_SSL_UNKNOWN_REVOCATION is generated. The connection is allowed to continue.
OCSPCheckExtensions = YES|NO
Controls whether IBM MQ acts on AuthorityInfoAccess certificate extensions.

This attribute can be read by C and unmanaged .NET clients.

If the value is set to NO, IBM MQ ignores AuthorityInfoAccess certificate extensions and does not attempt an OCSP security check. The default value is YES.

[UNIX, Linux, Windows][V9.1.5 Apr 2020]OCSPTimeout = number
The number of seconds to wait for an OCSP responder when performing a revocation check.

This attribute can be read by C and unmanaged .NET clients.

If no value is set, then the IBM MQ default of 30 seconds is used.

SSLCryptoHardware = string
Sets the parameter string required to configure PKCS #11 cryptographic hardware present on the system.

This attribute can be read by C and unmanaged .NET clients.

Specify a string in the following format: GSK_PKCS11 = driver path and filename;token label;token password;symmetric cipher setting;

For example: GSK_PKCS11=/usr/lib/pkcs11/PKCS11_API.so;tokenlabel;passw0rd;SYMMETRIC_CIPHER_ON

The driver path is an absolute path to the shared library providing support for the PKCS #11 card. The driver file name is the name of the shared library. An example of the value required for the PKCS #11 driver path and file name is /usr/lib/pkcs11/PKCS11_API.so. To access symmetric cipher operations through GSKit, specify the symmetric cipher setting parameter. The value of this parameter is either:
SYMMETRIC_CIPHER_OFF
Do not access symmetric cipher operations. This setting is the default setting.
SYMMETRIC_CIPHER_ON
Access symmetric cipher operations.

The maximum length of the string is 256 characters. The default value is blank. If you specify a string that is not in the correct format, an error is generated.

SSLFipsRequired = YES|NO
Specifies whether only FIPS-certified algorithms are to be used if cryptography is carried out in IBM MQ.

This attribute can be read by C, and unmanaged .NET clients.

If cryptographic hardware is configured, the cryptographic modules used are those modules provided by the hardware product. These might, or might not, be FIPS-certified to a particular level, depending on the hardware product in use.

SSLHTTPProxyName = string
The string is either the host name or network address of the HTTP Proxy server that is to be used by GSKit for OCSP checks. This address can be followed by an optional port number, enclosed in parentheses. If you do not specify the port number, the default HTTP port, 80, is used.

This attribute can be read by C, and unmanaged .NET clients.

[AIX][Solaris]For the Sun Solaris SPARC platform, and for 32-bit clients on AIX®, the network address can be only an IPv4 address.

On other platforms the network address can be an IPv4 or IPv6 address.

This attribute might be necessary if, for example, a firewall prevents access to the URL of the OCSP responder.

[UNIX, Linux, Windows][V9.1.5 Apr 2020]SSLHTTPConnectTimeout = number|0
The number of seconds to wait for a network connection to be successfully established to a HTTP server when performing a revocation check.

This attribute can be read by C and unmanaged .NET clients.

If no value is set, then the IBM MQ default of 0 (off) is used.

SSLKeyRepository = pathname
The location of the key repository that holds the user's digital certificate, in stem format. That is, it includes the full path and the file name without an extension.

This attribute can be read by C, and unmanaged .NET clients.

SSLKeyResetCount = integer|0
The number of unencrypted bytes sent and received on a TLS channel before the secret key is renegotiated.

This attribute can be read by C, and unmanaged .NET clients.

The value must be in the range 0 - 999999999.

The default is 0, which means that secret keys are never renegotiated.

If you specify a value of 1 - 32768, TLS channels use a secret key reset count of 32768 (32Kb). This is to avoid excessive key resets, which would occur for small secret key reset values.