amqtcert (transfer certificates)

Purpose

The amqtcert command applies to WebSphere MQ for Windows only.

The amqtcert command is used to migrate SSL Certificates from WebSphere MQ for Windows Version 5.3, or Version 5.3.1. SSL Certificate Migration instructions are detailed in the WebSphere MQ Migration Information. SSL Certificate Migration occurs after migrating WebSphere MQ for Windows Version 5.3, or Version 5.3.1.

In this section when referring to a WebSphere MQ Certificate Store file, we are specifically referring to a WebSphere MQ for Windows Version 5.3, or Version 5.3.1, Certificate Store file.

To use this command, you must be either an administrator or a member of the mqm group.

The amqtcert command is used to migrate certificates from a client's or queue manager's WebSphere MQ Certificate Store file to a GSKit key database file. The filename of the WebSphere MQ Certificate Store file is of the form xxx.sto, where xxx is your chosen name. The filename of the GSKit key database file is of the form yyy.kdb, where yyy is your chosen name.

The amqtcert command is used to perform the following types of migration:

Automatic migration
The migration is deferred.

The time at which the migration occurs depends on whether it is being done for a queue manager or a WebSphere MQ client. On a queue manager the migration occurs when the queue manager starts. On a WebSphere MQ client the migration occurs when the first SSL channel starts.

Manual migration
The migration occurs immediately.

The command is also used to set the state information relating to automatic migration, held in the Windows(R) registry, for each queue manager or client.

Syntax

Read syntax diagramSkip visual syntax diagram>>-amqtcert----------------------------------------------------->

>--+- -a -- -p --Password--+---------------+--+- -c --FileName-+--+-><
   |                       '- -e --ExpTime-'  +- -m --QMgrName-+  |
   |                                          '- -m *----------'  |
   +- -g --FileName-- -w --FileName--| Manual migration options |-+
   +- -l --+- -a -----------+-------------------------------------+
   |       +- -c --FileName-+                                     |
   |       '- -m --QMgrName-'                                     |
   '- -r --+- -c *----------+-------------------------------------'
           +- -c --FileName-+
           +- -m --QMgrName-+
           '- -m *----------'

Manual migration options:

|-- -p --Password--+---------------+---------------------------->
                   '- -e --ExpTime-'

>--+-------------------------------------+----------------------|
   +- -u --ClntLogonID-- -i --ListNumber-+
   '- -m --QMgrName----------------------'

Keywords and parameters

-a
Specifies automatic migration.

When used in conjunction with the -m or -c parameters, it prepares the specified queue manager or client to automatically migrate the WebSphere MQ Certificate Store.

When used in conjunction with the -l parameter, it lists the contents of the registry entries for automatic migration.

-c FileName|*
FileName specifies the absolute (rather than relative) directory path name and filename (excluding the .sto suffix) of the client's WebSphere MQ Certificate Store. In manual migration, the -c parameter is not required.

FileName is used to identify a specific client WebSphere MQ Certificate Store. For automatic migration, the filename is stored in the registry and flagged as requiring automatic migration.

When the client connects to the queue manager, the key repository value (either MQSSLKEYR or the KeyRepository field of the MQSCO) being used by the client is compared against the list of stored filenames flagged as requiring automatic migration; if the values match then migration takes place. The filename is cleared from the registry list once successful migration has taken place.

-c * is used only in combination with the -r flag and specifies all client entries in the registry.

-e ExpTime
The expiration time (in days) of the GSKit key database password. The default is 60 days.
-g Filename
Use manual migration. The absolute (rather than relative) directory path name and filename (excluding the .kdb suffix) of a GSKit key database. The -w parameter must also be specified.
-l
In combination with the -c FileName or -m QMgrName parameters, it lists the certificates in a WebSphere MQ Certificate Store.

In combination with the -a parameter, it lists the contents of the registry entries for automatic migration.

-m QMgrName|*
QMgrName specifies the name of an individual queue manager. * represents all queue managers.

When specifying manual migration of a queue manager certificate store, the -m QMgrName parameter is mandatory. This allows the correct label to be given to the assigned personal certificate when it is written to the GSkit key database file (see the description of the -u parameter for more details). The * value is not valid for manual migration.

When specifying automatic migration, the names of the source certificate store and the target key database file are derived from the queue manager's SSLKeyRepository attribute.

-p Password
The password for the GSKit key database. This must be specified for automatic or manual migration. The maximum password length is 255 bytes.
-r
Remove the registry state information relating to automatic migration.
-u ClntLogonID
This parameter is only applicable when the command is used for manual migration of clients. The -i ListNumber parameter must also be specified.

In the WebSphere MQ Certificate Store there is usually one certificate assigned to the client. During migration, the copy of this certificate is modified before it is stored in the GSKit database.

The modification sets the certificate's Friendly Name attribute to the string ibmwebspheremq, followed in lower case by the client logon ID. The previous Friendly Name value, if any, is lost. This Friendly Name value becomes the label in the GSKit key database.

If neither -u nor -m are specified on manual migration, it is assumed to be a client migration. The ClntLogonId used is the userid used by the current amqtcert user to logon.

-i ListNumber

This parameter is only applicable when the command is used for manual migration of clients. The -u ClntLogonID parameter must also be specified.

This parameter is used to identify a specific personal certificate which is to have its GSKit label set to the value specified by the -u ClntLogonID parameter.

Prior to using amqtcert with -i ListNumber specified, you must execute amqtcert with -l specified to list the certificates in a WebSphere MQ Certificate Store. You must identify the required personal certificate from the list, then execute amqtcert again, specifying -i ListNumber with the required certificate number.

For example, after executing amqtcert -l -c C:\SSL\Client\key you might identify the following personal certificate from the list displayed as the required certificate:

Certificate 14
Certificate Type:  Personal
Subject:           personalcert@ibm.com, personalcert@ibm.com
Issuer:            BE, GlobalSign nv-sa, PersonalSign Class 1 CA, GlobalSign 
                                                         PersonalSign Class 1 CA
Valid From:        14/10/2004 to 14/11/2004
Certificate Usage: <All>

You will then execute amqtcert and specify -i ListNumber as -i 14.

ListNumber must be a number greater than 0.

If ListNumber references a valid personal certificate, which is not the currently assigned certificate, then:

  • The assigned certificate is not modified.
  • The assigned certificate is not given a label of the form ibmwebspheremq<xxxxx> in the GSkit key database file, and ceases to be assigned.
  • The certificate referenced by ListNumber becomes the assigned certificate in the GSKit key database.

If ListNumber does not reference a valid personal certificate, then the command fails and no migration occurs for any certificates (personal or otherwise).

-w FileName
Use manual migration. FileName is the absolute (rather than relative) directory path name and filename (excluding the .sto suffix) of a WebSphere MQ Certificate Store. The -g parameter must also be specified.

Examples