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 will have its own
certificate store. If you want to change the location of a certificate
store, refer to the information on working with your key repository in WebSphere MQ Security.
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.
| Note: | 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 or modify a client or system store.
|
Syntax
Required 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. CA certificates that
do not have associated private keys cannot be assigned to a WebSphere MQ queue
manager or WebSphere MQ client.
- -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.
- -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.
- 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 QM1
- Lists the contents of the queue manager store for queue manager
QM1.
- 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.
- amqmcert -m QM2 -a 102
- Copies the certificate with handle 102 into the queue manager
store for QM2.
- 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 QM1
- Copies the certificate with handle 4 from the current
user's MY system store to the queue manager store for
QM1. If the certificate has private key data, that data will
be copied to the local machine's private key repository.
- amqmcert -m QM2 -d 122
- Assigns the certificate with handle 122 to be used for
authenticating QM2. 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.
Note that this function is available only on Windows 2000 or later
versions. Personal certificate files are usually provided in files with
extensions .p12 or .pfx
- amqmcert -a -p mqper.pfx -z password
- Imports the certificate(s) 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.