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 V5.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 V5.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 V5.3.1, Certificate Store file.
To use this command, 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 registry, for each queue manager or client.
Syntax
>>-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. If there are any spaces in FileName then it must be enclosed in quotes. 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. If there are any spaces in FileName then it must be enclosed in quotes. 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, 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. If there are any spaces in FileName then it must be enclosed in quotes. The -g parameter must also be specified.
Examples
Return codes
1 Error accessing certificate store 2 Auto migration failed 3 Invalid argument combination 4 Certificate expired 5 Certificate import failed 6 Certificate is an orphan 7 Create file failed 8 Duplicate registry entry 9 WebSphere MQ Certificate Store file is empty 16 WebSphere MQ Certificate Store file found 17 WebSphere MQ Certificate Store file not found 18 GSKit add certificate failed 19 GSKit error 20 GSKit initialization error 21 GSkit add CA certificate error 22 Load library failed 23 No memory to allocate tables for migrating root/intermediate certificates 24 No memory 25 WebSphere MQ Certificate Store file cannot be opened 32 User not authorized to run amqtcert command 33 Windows operation failed 34 Windows export of personal certificate failed 35 GSKit create new key database error 36 Windows registry error 37 amqtcert command usage error 38 Queue manager name error 39 Unexpected system return code 40 Local mqm group not found 41 Invalid arguments 48 Bad argument 49 Invalid -i ListNumber parameter
Related commands
amqccert Check certificate chains
- Listing the contents of certificate stores
- Manually migrating certificate stores
- Automatically migrating certificate stores
- Listing the contents of registry entries
- Removing state information
Parent topic:
The control commands
fa15580_
Home