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:
- 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, unmanaged .NET, IBM MQ classes for Java, and IBM MQ classes for JMS clients.
Note: Property values are interpreted case-sensitively by the Java/JMS client, so YES/NO values should be set in uppercase.- Specifies whether a queue manager is able to use the TLS 1.3 CipherSpecs (see Enable 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.
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.
- 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.
- 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.
- 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.
On Windows systems, we can also use Active Directory for CRL revocation checking. We 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 we 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 we are supplying an MQAIR (even if you choose not to do so).
- 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.
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.
- 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.
- 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.
- 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.
- This attribute can be read by C, and unmanaged .NET clients.The string can be one of two values:
- Usepeerchain [Default]: The certificate chain provided by the peer can be used to bridge any trust chain gaps while validating certificates. With the exception of the root certificate.
- Truststoreonly [Not recommended]: Only certificates in the trust store will be used for validating the peer's certificate.
- 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.
- 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.
- 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 we do not specify the port number, the default HTTP port, 80, is used.
This attribute can be read by C, and unmanaged .NET clients.
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.
- 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.
- 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.
- 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.
Parent topic: Configure a client using a configuration file