SSL stanza of the qm.ini file
The SSL stanza is used to configure the TLS channels on a queue manager.
Online Certificate Status Protocol (OCSP)
A certificate can contain an AuthorityInfoAccess extension. This extension specifies a server to be contacted through Online Certificate Status Protocol (OCSP). To allow SSL or TLS channels on your queue manager to use AuthorityInfoAccess extensions, ensure that the OCSP server named in them is available, is correctly configured, and is accessible over the network. For more information, see Working with revoked certificates.
A certificate can contain a CrlDistributionPoint extension. This extension contains a URL which identifies both the protocol used to download a certificate revocation list (CRL) and also the server to be contacted.
If you want to allow SSL or TLS channels on your queue manager to use CrlDistributionPoint extensions, ensure that the CDP server named in them is available, correctly configured, and accessible over the network.
The SSL Stanza
Use the SSL stanza in the qm.ini file to configure how TLS channels on your queue manager attempts to use the following facilities, and how they react if problems occur when using them.
In each of the following cases, if the value supplied is not one of the valid values listed, then the default value is taken. No error messages are written mentioning that an invalid value is specified.
- 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. Note: If OutboundSNI=HOSTNAME is used to connect to a remote channel with a certificate label configured, the connection is rejected with an MQRC_SSL_INITIALIZATION_ERROR and an AMQ9673 message is printed in the remote queue manager error logs.
- 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.
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.
- AllowedCipherSpecs=name|name list|ALL
- Specifies a custom list of CipherSpecs that are ordered and enabled for use with IBM MQ channels on Multiplatforms.
Note: You should not select ALL CipherSpecs, as this enables SSL 3.0 and TLS 1.0 protocols and a large number of weak cryptographic algorithms.
- A single CipherSpec name.
- A comma separated list of IBM MQ CipherSpec names to re-enable.
- The special value of ALL, representing all CipherSpecs (not recommended).
- For more information, see Providing a custom list of ordered and enabled CipherSpecs on Multiplatforms.
Specifies whether a queue manager is able to use the TLS 1.3 CipherSpecs.
- 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.
- CDPCheckExtensions=YES|NO (default)
Specifies whether TLS channels on this queue manager try to check CDP servers that are named in CrlDistributionPoint certificate extensions.
- 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.
Specifies the minimum keysize that RSA certificates must have in order to be accepted during a TLS handshake. Allows any value equal to 0 or above. Defaults to 1 if not specified.
- OCSPAuthentication=REQUIRED (default) |WARN|OPTIONAL
Specifies the action to be taken when a revocation status cannot be determined from an OCSP server.
If OCSP checking is enabled, a TLS channel program attempts to contact an OCSP server.
If the channel program is unable to contact any OCSP servers, or if no server can provide the revocation status of the certificate, then the value of the OCSPAuthentication parameter is used.
- REQUIRED (default) : Failure to determine the revocation status causes the connection to be closed with an error. This value is the default.
- WARN: Failure to determine the revocation status causes a warning message to be written in the queue manager error log, but the connection is allowed to proceed.
- OPTIONAL: Failure to determine the revocation status allows the connection to proceed silently. No warnings or errors are given.
- OCSPCheckExtensions= YES (default) |NO
Specifies whether TLS channels on this queue manager try to check OCSP servers that are named in AuthorityInfoAccess certificate extensions.
- YES (default) : TLS channels try to check OCSP servers to determine whether a digital certificate is revoked. This value is the default.
- NO: TLS channels do not try to check OCSP servers.
- OCSPTimeout= number
The number of seconds to wait for an OCSP responder when performing a revocation check.
From IBM MQ 9.3.0, 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.
- 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.
- For 32-bit clients on AIX®, the network address can only be an IPv4 address.
- On other platforms, the network address can be an IPv4 or IPv6
This attribute might be necessary if, for example, a firewall prevents access to the URL of the OCSP responder.
- 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.
- 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.
If no value is set, then the IBM MQ default of 0 (off) is used.
SSL: OutboundSNI=CHANNEL1 AllowedCipherSpecs=TLS13 CipherSpec list2 AllowTLSV13=Y3 CDPCheckExtensions=NO4 MinimumRSAKeySize=1 OCSPAuthentication=REQUIRED OCSPCheckExtensions=YES OCSPTimeout=30 PeerCertChainValidation=Usepeerchain5 SSLHTTPConnectTimeout=0
- The default value for OutboundSNI is Channel
- This is a list of specific CipherSpecs not the alias ciphers. If you require only
TLS1.3 ciphers, you must list them. For example:
- The default value for AllowTLSV13 is Y unless you have enabled weak ciphers, in which case it turns off (unless you explicitly turn it on.)
- The values for CDPCheckExtensions can be only Yes or No.
- The values for PeerCertChainValidation can be only Usepeerchain or Truststoreonly.