+

Search Tips | Advanced Search

Migrating from MQIPT Version 2.0 to Version 2.1

We can migrate your MQIPT Version 2.0 installation to Version 2.1.

To perform the migration, complete the following steps:

  1. Make appropriate backups in case you later have to restore any data. See Making backups for details.

  2. Stop MQIPT by running the command: 
    mqiptAdmin -stop
  3. If we have installed MQIPT as a service, you must remove it before uninstalling MQIPT. Note that only the installation of MQIPT that installed the service can be used to remove it. For example, if we have two MQIPT installations, one in C:\MQIPT1 and one in C:\mqipt2, and you run the command C:\MQIPT1\bin\mqiptService -install C:\mqipt1, then only the mqiptService command from the C:\MQIPT1 installation can subsequently be used to remove the service. Attempting to remove the service using a different installation causes error MQCPE083. 
    mqiptService -remove
  4. Run the uninstallation program for MQIPT Version 2.0.
  5. After we have installed MQIPT Version 2.1, copy the saved configuration files back to their original locations.
  6. You are advised to use the IPT Administration Client to manage changes to MQIPT. The configuration file from version 2.0 is compatible with the GUI.

Some implementations require a local MQIPT service under the control of your own organization and a remote MQIPT service which could be under the control of your client organization. In this situation, it is very difficult to migrate both MQIPT services at the same time but this is not a problem for MQIPT. Unless otherwise stated, older versions of MQIPT are compatible with the latest version. This makes the MQIPT migration process much easier.


CipherSuites

The following CipherSuites are no longer supported:

If you include one of these CipherSuites in the SSLClientCipherSuites or SSLServerCipherSuites properties, the route will fail to start with error MQCPE076. No IBM MQ CipherSpecs correspond to these CipherSuites, so this only affects interoperability between a pair of MQIPT instances that use SSL/TLS. The following CipherSuites are not enabled by default in JSSE, whereas they were enabled by default in SSLite. This is because these CipherSuites are no longer considered sufficiently secure and you should avoid using them. This change affects SSLClient routes without the SSLClientCipherSuites property and SSLServer routes without the SSLServerCipherSuites property, as these routes rely on the CipherSuites that are enabled by default. If you require any of these CipherSuites, you must specify the SSLClientCipherSuites or SSLServerCipherSuites route properties and include them in the property value.

Notes:
  1. These CipherSpecs correspond to IBM MQ CipherSpecs as described in SSL/TLS support.
  2. These names are historical; they are no longer FIPS-compliant and you should avoid using them.
If you require the same IBM MQ CipherSpecs enabled in MQIPT 2.1 as the previous MQIPT release, set the following properties in the [global] section of mqipt.conf. Enter each of these parameters on a single line in mqipt.conf, separating each CipherSuite value with a space: 
 
SSLServerCipherSuites=SSL_RSA_WITH_DES_CBC_SHA SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA 
SSL_RSA_FIPS_WITH_DES_CBC_SHA SSL_RSA_WITH_NULL_MD5 SSL_RSA_WITH_NULL_SHA 
SSL_RSA_EXPORT_WITH_RC4_40_MD5 SSL_RSA_WITH_RC4_128_MD5 SSL_RSA_WITH_RC4_128_SHA 
SSL_RSA_WITH_3DES_EDE_CBC_SHA SSL_RSA_WITH_AES_128_CBC_SHA SSL_RSA_WITH_AES_256_CBC_SHA  
SSL_RSA_WITH_DES_CBC_SHA SSL_RSA_WITH_RC4_128_SHA SSL_RSA_WITH_3DES_EDE_CBC_SHA 
SSLClientCipherSuites=SSL_RSA_WITH_DES_CBC_SHA SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA  
SSL_RSA_FIPS_WITH_DES_CBC_SHA SSL_RSA_WITH_NULL_MD5 SSL_RSA_WITH_NULL_SHA  
SSL_RSA_EXPORT_WITH_RC4_40_MD5 SSL_RSA_WITH_RC4_128_MD5 SSL_RSA_WITH_RC4_128_SHA  
SSL_RSA_WITH_3DES_EDE_CBC_SHA SSL_RSA_WITH_AES_128_CBC_SHA SSL_RSA_WITH_AES_256_CBC_SHA  
SSL_RSA_WITH_DES_CBC_SHA SSL_RSA_WITH_RC4_128_SHA SSL_RSA_WITH_3DES_EDE_CBC_SHA
Adding these properties to the [global] section ensures that all SSL/TLS routes that do not explicitly define a list of enabled CipherSuites inherit these settings. The presence of these properties only affects routes with SSLServer or SSLClient set to true; other routes are unaffected.

With this set of CipherSuites, we can use all of the IBM MQ CipherSpecs supported by MQIPT 2.0 after migration to version 2.1.


Changes to organizational unit (OU) matching

The following [route] properties now support the matching of multiple OU values by using commas as separators:

If you previously used any of these OU [route] properties and included commas, you must insert backslash (\) escape characters before any commas to preserve the previous behavior and avoid them being interpretted as separators. See Multi-valued certificate Distinguished Name OU properties for more information.


Changes to SecurityManager security policy

MQIPT Version 2.1 includes additional problem diagnosis information in its trace and FFST records. If we use a Java SecurityManager security policy, you must always include the following properties in the policy: 
 
permission java.util.PropertyPermission "java.home", "read"; 
permission java.util.PropertyPermission "java.version", "read"; 
permission java.util.PropertyPermission "java.runtime.version", "read"; 
permission java.util.PropertyPermission "java.vm.info", "read"; 
permission java.util.PropertyPermission "java.vm.vendor", "read"; 
permission java.util.PropertyPermission "os.arch", "read"; 
permission java.util.PropertyPermission "os.name", "read"; 
permission java.util.PropertyPermission "os.version", "read"; 
permission java.lang.RuntimePermission "getenv.MQIPT_PATH"; 
permission java.lang.RuntimePermission "getStackTrace";
permission java.security.SecurityPermission "getPolicy";
If we do not include all of these properties, MQIPT will not operate correctly, and problem diagnosis will be impaired.

When you migrate from a previous version, ensure that all of these properties are included in any security policy file identified by the SecurityManagerPolicy property in the [global] section of the mqipt.conf file. If do you not have a SecurityManagerPolicy property, it is not necessary to create one.


IBM MQ AMQ9616 or AMQ9631 errors with SSL/TLS routes

MQIPT Version 2.1 supports more TLS secure socket protocol versions than the previous releases. As a result, it is possible that existing IBM MQ channels might fail to connect through MQIPT after MQIPT has been upgraded to version 2.1.

This issue is most likely to affect SSLClient routes, because the listener on the destination queue manager has all protocol versions enabled so that it can perform handshakes for multiple channels with different CipherSpecs. The MQIPT Version 2.1 default is also to enable all protocol versions for security reasons. The secure sockets protocols are designed to negotiate the highest enabled protocol version supported by both sides. If you are using older SSL 3.0 and TLS 1.0 CipherSpecs with IBM MQ Version 7.1 or later, this might result in TLS 1.2 being used instead of the expected protocol. This protocol version mismatch causes the channel to report an error.

If IBM MQ channels that worked with the previous MQIPT release fail to start and produce AMQ9616 or AMQ9631 errors after migration, set the protocol versions that are to be used: set the SSLClientProtocols route property to restrict the protocol versions for an SSLClient route and the SSLServerProtocols route property to restrict the protocol versions for an SSLServer route. In most cases, setting SSLClientProtocols=SSLv3 will resolve the problem. If we have MQIPT V2.0 and an interim fix for APAR IV25345 installed, you might need to add TLSv1 to the SSLClientProtocols list.

To assist with migration, add the following settings to the [global] section of mqipt.conf so that they are inherited by all SSL/TLS routes: 
 
SSLClientProtocols=SSLv3,TLSv1 
SSLServerProtocols=SSLv3,TLSv1
These settings only affect routes with SSLServer or SSLClient set to true; other routes are unaffected.

Refer to the table of CipherSpecs and CipherSuites in SSL/TLS support for more information about the protocol versions used by IBM MQ CipherSpecs and how best to configure the protocol versions.


Connection errors when using 512-bit RSA keys after migration

If we have a digital certificate with a 512-bit RSA public key, you might see one of the following connection errors in the MQIPT connection log, after you migrate to version 2.1:

The failure arises because MQIPT V2.1 supports TLS 1.2 CipherSuites, which are enabled by default unless we have specifically set the SSLClientCipherSuites or SSLServerCipherSuites route properties. The IBM JSSE implementation of the TLS 1.2 CipherSuites does not support 512-bit RSA keys because 512 bits is an insecure key size; it provides only a weak strength of encryption and should be avoided.

Larger RSA key sizes such as 768 bits and 1024 bits are not affected and are supported, although for security reasons, it is preferable to use a minimum RSA key size of 2048 bits.

To check the key size for your existing certificates, we can use the supplied mqiptKeycmd tool:
  1. Run the certificate list command to obtain a list of the certificate labels in the key-ring file. For example: 
    mqiptKeycmd -cert -list -db key.p12 -pw password
  2. For each certificate label (for example, mqipt), display the certificate details: 
    mqiptKeycmd -cert -details -db key.p12 -pw password -label mqipt
    The Key Size field displays the certificate public key size. If the size shown is 512 then this issue is likely to occur.
The preferred solution is to replace the old RSA digital certificate with a new certificate using an RSA key size of at least 2048 bits. This offers a much better strength of encryption and also ensures compatibility with the TLS 1.2 protocol. However, if necessary, we can work around the error by configuring the set of enabled protocol versions to exclude TLS 1.2, for example: 
SSLClientProtocols=SSLv3,TLSv1,TLSv1.1 
SSLServerProtocols=SSLv3,TLSv1,TLSv1.1