amqmcert (manage certificates)

amqmcert (manage certificates)

Purpose

Use the amqmcert command to manage certificates with WebSphere MQ for Windows. You can use this command to configure a WebSphere MQ client certificate store for SSL, or a WebSphere MQ queue manager certificate store. You can assign only personal certificates, which have associated private keys, to a queue manager or WebSphere MQ client. The local store must also contain CA certificates from the Certification Authorities that issue the certificates you expect to receive. CA certificates, also known as signer certificates, enable you to validate incoming certificates.
Usually, each queue manager and WebSphere MQ client has its own certificate store.
The amqmcert command enables you to copy certificates between certificate stores on a computer, or to import certificates from a file. You can copy and install private key data if you require.
Notes:

Only administrators or members of the mqm group can use amqmcert to list or modify WebSphere MQ queue manager stores. General users can use it to list a client or system store or modify a client store.
To manage certificates on UNIX systems, you use IKEYCMD from the command line, or the iKeyman GUI. Chapter 18, Using the IKEYCMD interface to manage keys and certificates on UNIX systemsdescribes the command line interface.

Syntax
>>-amqmcert--+--------+--+-----------------+--+----------+------>
             '-server-'  '--k--+-sslkeyr-+-'  '--m--qmgr-'
                               +-CA------+
                               +-ROOT----+
                               '-MY------'
 
>--+----+--+------------------------------------------------+--->
   '--h-'  '--a--+--------+--+----------------------------+-'
                 '-handle-'  '--p--filename---z--password-'
 
>--+--------------+--+------------+--+------------+------------->
   '--s--filename-'  '--x--handle-'  '--d--handle-'
 
>--+------------+--+----+--+----+------------------------------><
   '--r--handle-'  '--u-'  '--l-'
 
 
Optional parameters

server
The name of the machine at which the command is targeted. For example, you can use the amqmcert command to copy certificates from the interactive user's personal certificate store to a queue manager store on a remote computer on the network. If you include this parameter, it must precede all other options. If you omit it, the command is executed on the local machine.

-k sslkeyr|CA|ROOT|MY
Either:

An alternative MQSSLKEYR value for the current operation when you are manipulating WebSphere MQ client stores, or
The source system certificate store for a copy or enumerate operation. CA, ROOT, and MY are names given to system certificate stores provided by Microsoft Internet Explorer or Windows 2000.

-m qmgr
The target queue manager. Operations look up the queue manager's SSLKEYR value to locate the certificate store and use that as the target.

-h
Specifies that the command refers to the local machine's certificate stores. Windows systems allow two sets of certificate stores, which reside in the registry. One is based on the currently logged in user (HKEY_CURRENT_USER), and the other is for all users of the local machine (HKEY_LOCAL_MACHINE). By default, when using the -k parameter, the command refers to the current user's certificate stores.

-a handle
Adds a certificate to a store. When you specify a handle, the command copies the certificate identified by handle to the store. If the certificate being copied has associated private key data, that data is also copied to the local machine's private key store, if that data does not already exist.

-p filename
The filename for a source personal certificate. These files usually (but not always) contain private key data, and require a password (provided by the -z option) to enable decryption and import. Personal certificates can be assigned to a WebSphere MQ queue manager or WebSphere MQ client. Personal certificate files are usually provided in files with extensions .p12 or .pfx.
Note that this function is available only on Windows 2000 or later versions.

-z password
The password required to decrypt and import a personal certificate.

-s filename
The filename for a CA certificate, used when verifying a subject certificate. CA certificates are not usually encrypted, and typically are provided in files with extensions .DER, .pb7, or .CER.

-x handle
Exports the certificate identified by handle to a file, specified with the -s option. The file is exported in a proprietary format, and can only be used by this command to import to another WebSphere MQ store. Private key data is also exported if a password has been supplied and the private key data exists.

-d handle
Assigns the certificate identified by handle to the target queue manager or client. When you use the -m option to specify a queue manager, the certificate must exist in that queue manager's store, and is assigned as the certificate to use to identify that queue manager to remote parties (WebSphere MQ clients). Without the -m option, the certificate is assigned to the current WebSphere MQ client, that is, the logged- in user.

-rhandle
Removes the certificate identified by handle from the store.

-u
Unassigns a certificate from a queue manager, when the -m option is specified, or from the current WebSphere MQ client, that is, the logged-in user.

-l
Lists certificates. Use this option to enumerate the available certificates. The context of the enumeration can be specified using the -m or -k options, to specify either a queue manager store, a system store, or a specific client store. If neither -m nor -k are specified, the command lists the client store targeted by the environment variable MQSSLKEYR. Certificates are listed with unique identifiers (handles), which can then be used on subsequent commands to identify source or target certificates.

Examples

For a WebSphere MQ client, ensure that the MQSSLKEYR environment variable is set to the root filename of the client certificate store. For example, when you set MQSSLKEYR=D:\mqm\key the amqmcert command uses or creates a store named D:\mqm\key.sto.

Enumerating certificate stores

amqmcert -l

Lists the contents of the store referred to by MQSSLKEYR, that is, the current user's WebSphere MQ client store.

amqmcert -l -k d:\mqm\key

Lists the contents of the store d:\mqm\key.sto.

amqmcert -l -m VANCOUVER

Lists the contents of the queue manager store for queue manager VANCOUVER.

amqmcert -l -k ROOT -h

Lists all certificates in the local machine ROOT store that are available to the local machine.

amqmcert -l -k CA -h

Lists all certificates in the local machine CA store that are available to the local machine.

amqmcert -l -k MY

Lists all certificates in the current user's MY system store.

Copying a certificate from one store to another

amqmcert -m LONDON -a 102

Copies the certificate with handle 102 into the queue manager store for LONDON.

amqmcert -a 102

Copies the certificate whose handle is 102 to the WebSphere MQ store for the current user.

amqmcert -a 4 -k MY -m VANCOUVER

Copies the certificate with handle 4 from the current user's MY system store to the queue manager store for VANCOUVER. If the certificate has private key data, that data will be copied to the local machine's private key repository.

Assigning a certificate for use by WebSphere MQ

amqmcert -m LONDON -d 122

Assigns the certificate with handle 122 to be used for authenticating LONDON. Note that the certificate must be in the queue manager store.

amqmcert -d 123

Assigns the certificate with handle 123 to be used to authenticate this WebSphere MQ client, that is, the interactive user.

Importing a certificate from a file

Note that this function is available only on Windows 2000 and Windows XP.
Importing personal certificates

Personal certificates are usually provided in files with extensions .p12 or .pfx:

amqmcert -a -p mqper.pfx -z password

Imports the certificates in mqper.pfx to the current user's WebSphere MQ client store using the specified password to decrypt the private key, which is then stored in the local machine's key repository.

Importing CA certificates

CA certificates are usually provided in files with the extension .cer:

amqmcert -a -s mqcacert.cer

Imports the certificates in mqcacert.cer to the current user's WebSphere MQ client store.

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.