SSL stanza of the client configuration file

The following attributes can be included in the SSL stanza:

AllowOutboundSNI = YES (default) |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, unmanaged .NET, IBM MQ classes for Java, and IBM MQ classes for JMS clients.

Property values are interpreted case-sensitively by the Java/JMS client, so YES/NO values should be set in uppercase.

Attention: From IBM MQ 9.2.1 the AllowOutboundSNI property is deprecated, and is available for backwards-compatibility purposes only.

AllowOutboundSNI set to YES provides the same function as OutboundSNI set to CHANNEL, while AllowOutboundSNI set to NO provides the same function as OutboundSNI set to HOSTNAME.

If both AllowOutboundSNI and OutboundSNI attributes are present in the SSL stanza, the setting of OutboundSNI takes precedence.

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 (default), YES (default), T (default), or TRUE (default): 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 (default)

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 (default) : 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.

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

If you are using either MQSCO or CCDT, then the connection succeeds. If there is no CCDT file and if MQSCO is also not supplied, then the connection fails with a reason code 2059 and the error log reports AMQ9518E: File '/var/mqm/AMQCLCHL.TAB' not found.

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.

EnvironmentScope=PROCESS|CONNECTION

Controls whether IBM MQ uses a single GSKit Environment for the entire process or a GSKit environment per connection.

This attribute can be read by C clients.

This attribute has the following possible values:

PROCESS

A single GSKit environment is used for multiple connections created by the process. Using this setting means that TLS keystore changes will not be available until all active TLS connections within the process have stopped.

This value is the default value.

CONNECTION

A GSKit environment is created for each connection within the same process. Enabling this means TLS keystore changes will be picked up immediately by any new TLS connections started by the process.

Warning: Enabling this mode of operation causes applications to use additional CPU and Memory resources to create each GSKit environment. This resource consumption increases with each additional concurrent TLS connection.

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.

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.

For Long Term Support from IBM MQ 9.2.0 Fix Pack 2 and Continuous Delivery from IBM MQ 9.2.3, if a value of 0 is set, the default timeout of 30 seconds is used.

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

OutboundSNI = CHANNEL | HOSTNAME

If OutboundSNI is set to CHANNEL, SNI capable clients set SNI to the target IBM MQ channel name to the remote system when initiating a TLS connection.

If this attribute is set to HOSTNAME, SNI capable clients set the SNI header to the hostname, causing outbound connection requests to receive the default certificate of the remote queue manager 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.

Property values are interpreted case-sensitively by the Java/JMS client, so YES/NO values should be set in uppercase.

From IBM MQ 9.2.0 Fix Pack 4 for Long Term Support and IBM MQ 9.2.3 for Continuous Delivery, the IBM MQ managed .NET client has been updated to set SERVERNAME to the respective hostname if the OutboundSNI property is set to HOSTNAME. This allows an IBM MQ managed .NET client to connect to a queue manager using Red Hat® OpenShift® routes. Note that, in IBM MQ 9.2.0 Fix Pack 4, the OutboundSNI property is added and supported only from the mqclient.ini file; you cannot set the property from the .NET application.

Note: If an application with an OutboundSNI setting of HOSTNAME connects to a channel with a certificate label configured, the application is rejected with an MQRC_SSL_INITIALIZATION_ERROR, and an AMQ9673 message is printed in the queue manager error logs.

PeerCertChainValidation=string

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.

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.

When supplying the different components of the string, you must escape the semicolon characters using the backslash character, as the semicolon character is treated as a comment. For example: '\;'

You should protect the token password contained in the SSLCryptoHardware attribute string. See IBM MQ clients using cryptographic hardware for more information.

The maximum length of the string is 256 characters.

To handle encrypted passwords, there is now no limit to the length of the string.

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.

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.

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.