# Migrating Windows Secure Sockets Layer (SSL) connections

This section deals with migrating Windows® Secure Sockets Layer (SSL) connections from WebSphere® MQ Version 5.3 to WebSphere MQ Version 7.0.

## General Introduction

WebSphere MQ Version 7.0 provides the Global Security Toolkit (GSKit) on Windows platforms for improved SSL (Secure Sockets Layer) support for queue manager and WebSphere MQ client channels. Follow the guidance in this section to determine whether WebSphere MQ Version 5.3 queue managers or clients have been set up to use SSL connections, and to ensure these channels continue to work with WebSphere MQ Version 7.0. The migration process causes a copy of the certificates stored in the WebSphere MQ Certificate Stores used by WebSphere MQ Version 5.3, to be migrated to a GSKit Key database.

## Points to consider

- If you are intending to uninstall WebSphere MQ Version 5.3 before installing WebSphere MQ Version 7.0, you must do the following:
  - Before uninstalling WebSphere MQ Version 5.3, check that the certificate chains are complete. If they are not, use the AMQMCERT utility supplied with WebSphere MQ Version 5.3 to complete the chains.
  - After installing WebSphere MQ Version 7.0, run the AMQTCERT command from the command line to migrate your certificate stores.
  If you install WebSphere MQ Version 7.0 after uninstalling WebSphere MQ Version 5.3, the certificate chain checker cannot then check the chains and AMQMCERT is no longer available to repair them. This also means that the processes used in the installation to migrate the stores cannot find them and you must manually check the chains and manually migrate the stores. See the Control commands for details of the AMQMCERT and AMQTCERT commands.
- The Pre-installation Launchpad is run at the beginning of the installation process. From this the Check WebSphere MQ Certificate Store Wizard can be run. This checks that the certificate chains in the certificate stores are complete, that is, that each certificate in the chain is signed by the entity identified by the next certificate in the chain, terminating with a root CA certificate signed by the CA itself. If you elect not to run the Check WebSphere MQ Certificate Store Wizard, the Post-installation Prepare Wizard does not present any migration panels and your certificate stores can not be scheduled for automatic migration.
- The chain checker application used to verify that all the required certificates are there, before migrating certificates from the WebSphere MQ for Windows V5.3 store to the GSKit store, is available in WebSphere MQ V5.3 Fix Pack 10 (CSD10) or later.
- On client installation, the Check WebSphere MQ Certificate Store Wizard is run from the Install panels directly because there is no launchpad on the client installation to run it from.
- The Check WebSphere MQ Certificate Store Wizard and the Post-installation Prepare Wizard for scheduling certificate migration are made available only if you are migrating from a WebSphere MQ Version 5.3 installation directly to a WebSphere MQ Version 7.0 installation. If you uninstall WebSphere MQ Version 5.3 and then install WebSphere MQ Version 7.0, the installation process is not aware that the previous version was WebSphere MQ Version 5.3 and will not present the Check WebSphere MQ Certificate Store Wizard or any of the SSL migration panels to you. In this situation, you might consider running the Pre-installation Launchpad and the Check WebSphere MQ Certificate Store Wizard before uninstalling WebSphere MQ Version 5.3. This confirms the completeness of the certificate chains and allows you to import them using AMQTCERT after installing WebSphere MQ Version 7.0.
- If you are installing WebSphere MQ Version 7.0 silently, there are options which can be passed to the Post-installation Prepare Wizard silently to have it schedule certificate migration for you. If you follow this process, the Check WebSphere MQ Certificate Store Wizard is not run to check the certificate chains. If you are intending to run a silent installation, you should either run the Pre-installation Launchpad and the Check WebSphere MQ Certificate Store Wizard to check the completeness of the certificate chains or check the stores manually using AMQCCERT prior to the installation.

## Certificates that are not migrated

A number of certificates are not migrated during this process. These are:

- Certificates that match GSKit's default supplied set. These are not migrated as GSKit provides its own set which are assumed to be the same or more up to date.
- Orphaned certificates that do not have a full valid Certification Authority certificate chain. A certificate can only be imported into a GSkit key database file if a certificate from its certification authority is already present or if it is a root certificate. Certificates can only be added to the GSkit key database starting with the root Certification Authority certificate, proceeding down the chain of intermediate Certification Authority certificates, if any exist, and ending with the personal certificate issued by the lowest member of the Certification Authority chain, again if any exists.
- Certificates that have expired.

## Types of certificate migration

There are two types of certificate migration.

- Automatic migration. For a queue manager the actual migration occurs when the queue manager is started for the first time. When the migration has completed, it is not attempted again even if the migration process failed. The queue manager attempts to start, irrespective of the success or failure of the migration. For a client, the actual migration occurs when the client first connects to the queue manager using an SSL channel. If the migration completes successfully then it is not attempted again. The starting of the client is dependent on the outcome of the migration; if the migration fails then so does the client. Where a certificate store has been successfully validated in the pre-installation phase, the Post-installation Prepare Wizard uses the automatic migration method for each of the queue managers and client stores specified.
- Manual migration. This occurs at the time the new Transfer Certificates (AMQTCERT) control command is run. Manual migration requires you to use AMQTCERT for each queue manager and client. You must specify the location and name stem of the WebSphere MQ Certificate Store and the GSKit key database to be used.

Automatic migration has the advantage that you do not need to specify the location and names for all the WebSphere MQ Certificates Stores and their corresponding GSKit key databases for all the queue managers and the clients because this is derived from the information gathered during the pre-installation processing.

## Friendly Name attribute

In the WebSphere MQ Certificate Store file there is one certificate assigned to the queue manager or client. During migration, the copy of this certificate is modified before it is imported into the GSKit database. The modification sets the certificate's Friendly Name attribute to the string `ibmwebspheremq` followed in lower case by the queue manager name or the client logon ID. This Friendly Name value becomes the label of the certificate in the GSKit key database. The previous Friendly Name value, if any, is lost.

## Working with migrated certificates

When WebSphere MQ Version 7.0 has been fully installed, and the certificates from the WebSphere MQ Certificate Stores have been migrated to the GSKit database, you can use the IBM® Key Management (iKeyman) utility to view and manage your certificates. Full details of the iKeyman utility can be found in the WebSphere MQ Security book. Alternatively, you can use the command line interfaces iKeycmd and GSKCapiCmd to manage keys and digital certificates. These interfaces are described in Managing keys and certificates .

- Determining whether SSL connections have been set up
  This section deals with determining whether SSL connections have been set up for WebSphere MQ.
- SSL migration steps
  This section deals with steps for migrating Secure Sockets Layer (SSL) connections to work with WebSphere MQ Version 7.0.

Parent topic: Installing WebSphere MQ