Quick Start Guide for AMS on Windows platforms

Use this guide to quickly configure Advanced Message Security (AMS) to provide message security on Windows platforms. By the time you complete it, you will have created a key database to verify user identities, and defined signing/encryption policies for your queue manager.

Before you begin

You should have at least the following features installed on your system:

Server
Development Toolkit (for the Sample programs)
Advanced Message Security (AMS)

Refer to IBM® MQ features for Windows systems for details.

For information about using the setmqenv command to initialize the current environment so that the appropriate IBM MQ commands can be located and executed by the operating system, see setmqenv (set IBM MQ environment).

1. Creating a queue manager and a queue

About this task

All the following examples use a queue named TEST.Q for passing messages between applications. Advanced Message Security uses interceptors to sign and encrypt messages at the point they enter the IBM MQ infrastructure through the standard IBM MQ interface. The basic setup is done in IBM MQ and is configured in the following steps.

You can use IBM MQ Explorer to create the queue manager QM_VERIFY_AMS and its local queue called TEST.Q by using all the default wizard settings, or you can use the commands found in C:\Program Files\IBM\MQ\bin. Remember that you must be a member of the mqm user group to run the following administrative commands.

Procedure

Create a queue manager
```
crtmqm QM_VERIFY_AMS
```
Start the queue manager
```
strmqm QM_VERIFY_AMS
```
Create a queue called TEST.Q by entering the following command into runmqsc for queue manager QM_VERIFY_AMS
```
DEFINE QLOCAL(TEST.Q)
```

Results

If the procedure is completed, command entered into runmqsc will display details about TEST.Q:


DISPLAY Q(TEST.Q)

2. Creating and authorizing users

About this task

There are two users that appear in this example: alice, the sender, and bob, the receiver. To use the application queue, these users need to be granted authority to use it. Also to successfully use the protection policies that we will define these users must be granted access to some system queues. For more information about the setmqaut command refer to setmqaut.

Procedure

Create the two users and ensure that HOMEPATH and HOMEDRIVE are set for both these users.

Authorize the users to connect to the queue manager and to work with the queue


setmqaut -m QM_VERIFY_AMS -t qmgr -p alice -p bob +connect +inq


setmqaut -m QM_VERIFY_AMS -n TEST.Q -t queue -p alice +put


setmqaut -m QM_VERIFY_AMS -n TEST.Q -t queue -p bob +get

You should also allow the two users to browse the system policy queue and put messages on the error queue.
```
setmqaut -m QM_VERIFY_AMS -t queue -n SYSTEM.PROTECTION.POLICY.QUEUE -p alice -p bob +browse
```
```
setmqaut -m QM_VERIFY_AMS -t queue -n SYSTEM.PROTECTION.ERROR.QUEUE -p alice -p bob +put
```
Attention: IBM MQ optimizes performance by caching policies so that you do not have to browse records for policy details on the SYSTEM.PROTECTION.POLICY.QUEUE in all cases.
IBM MQ does not cache all the policies available. If there are high number of policies, IBM MQ caches a limited number of policies. So, if the queue manager has a low number of policies defined, there is no need to provide the browse option to the SYSTEM.PROTECTION.POLICY.QUEUE.

However, you should give browse authority to this queue, in case there is a high number of policies defined, or if you are using old clients. The SYSTEM.PROTECTION.ERROR.QUEUE is used to put error messages generated by the AMS code. The put authority against this queue is checked only when you attempt to put an error message to the queue. Your put authority against the queue is not checked when you attempt to put or get message from an AMS protected queue.

Results

Users are now created and the required authorities granted to them.

What to do next

To verify if the steps were carried out correctly, use the amqsput and amqsget samples as described in section 7. Testing the setup.

3. Creating key database and certificates

About this task

Interceptor requires the public key of the sending users to encrypt the message. Thus, the key database of user identities mapped to public and private keys must be created. In the real system, where users and applications are dispersed over several computers, each user would have its own private keystore. Similarly, in this guide, we create key databases for alice and bob and share the user certificates between them.

Note: In this guide, we use sample applications written in C connecting using local bindings. If you plan to use Java applications using client bindings, you must create a JKS keystore and certificates using either the Java keytool command [MQ 9.4.0 Jun 2024]

or the IBM MQ runmqktool command. For more information, see Quick Start Guide for AMS with Java clients. For all other languages, and for Java applications using local bindings, the steps in this guide are correct.

Procedure

Create a new key database for the user alice.
For example, issue the following command to create the new key database:
```
runmqakm -keydb -create -db "C:\Documents and Settings\alice\AMS\alicekey.kdb" -type cms -pw passw0rd -stash
```
Note:
- Use a strong password to secure the database.
- Include the -stash parameter to stash the encrypted key database password in a file.
Create a new self-signed certificate to identify the user alice for use in encryption.
For example, issue the following command to create a new self-signed certificate:
```
runmqakm -cert -create -db "C:\Documents and Settings\alice\AMS\alicekey.kdb" -stashed -label Alice_Cert -dn "CN=alice, O=IBM, C=GB"
```
Note:
- For the purpose of this guide, we are using self-signed certificate which can be created without using a Certificate Authority. For production systems, it is advisable to use certificates that are signed by a Certificate Authority.
- The -label parameter specifies the name for the certificate, which interceptors will look up to receive necessary information.
- The -dn parameter specifies the details of the Distinguished Name (DN) for the certificate. The Distinguished Name must be unique for each user.
Repeat steps 1 and 2 for the user bob.

Results

The two users alice and bob each now have a self-signed certificate.

4. Creating keystore.conf

About this task

You must point Advanced Message Security interceptors to the directory where the key databases and certificates are located. This is done via the keystore.conf file, which holds that information in plain text form. Each user must have a separate keystore.conf file in the .mqs folder. This step must be done for both alice and bob.

The content of keystore.conf must be of the form:


cms.keystore = dir/keystore_file
cms.certificate = certificate_label

Example

For this scenario, the contents of the keystore.conf will be as follows:


cms.keystore = C:/Documents and Settings/alice/AMS/alicekey
cms.certificate = Alice_Cert

Note:

The path to the keystore file must be provided with no file extension.
The certificate label can include spaces, thus "Alice_Cert" and "Alice_Cert " (with a space on the end) for example, are recognized as labels of two different certificates. However, to avoid confusion, it is better not to use spaces in label's name.
There are the following keystore formats: CMS (Cryptographic Message Syntax), JKS ( Java Keystore) and JCEKS ( Java Cryptographic Extension Keystore). For more information, refer to Structure of the keystore configuration file (keystore.conf) for AMS.
%HOMEDRIVE%\%HOMEPATH%\.mqs\keystore.conf (eg. C:\Documents and Settings\alice\.mqs\keystore.conf) is the default location where Advanced Message Security searches for the keystore.conf file. For information about how to use a non-default location for the keystore.conf, see Using keystores and certificates with AMS.
To create .mqs directory, you must use the command prompt.

5. Sharing Certificates

About this task

Share the certificates between the two key databases so that each user can successfully identify the other. This is done by extracting each user's public certificate to a file, which is then added to the other user's key database.

Note: Take care to use the extract option, and not the export option. Extract gets the user's public key, whereas export gets both the public and private key. Using export by mistake would completely compromise your application, by passing on its private key.

Procedure

Extract the certificate identifying alice to an external file:


runmqakm -cert -extract -db "C:\Documents and Settings\alice\AMS\alicekey.kdb" -pw passw0rd -label Alice_Cert -target alice_public.arm

Add the certificate to bob's keystore:


runmqakm -cert -add -db "C:\Documents and Settings\bob\AMS\bobkey.kdb" -pw passw0rd -label Alice_Cert -file alice_public.arm

Repeat steps for bob:


runmqakm -cert -extract -db "C:\Documents and Settings\bob\AMS\bobkey.kdb" -pw passw0rd -label Bob_Cert -target bob_public.arm


runmqakm -cert -add -db "C:\Documents and Settings\alice\AMS\alicekey.kdb" -pw passw0rd -label Bob_Cert -file bob_public.arm

Results

The two users alice and bob are now able to successfully identify each other having created and shared self-signed certificates.

What to do next

Verify that a certificate is in the keystore either by browsing it using the GUI or running the following commands which print out its details:


runmqakm -cert -details -db "C:\Documents and Settings\bob\AMS\bobkey.kdb" -pw passw0rd -label Alice_Cert


runmqakm -cert -details -db "C:\Documents and Settings\alice\AMS\alicekey.kdb" -pw passw0rd -label Bob_Cert

6. Defining queue policy

About this task

With the queue manager created and interceptors prepared to intercept messages and access encryption keys, we can start defining protection policies on QM_VERIFY_AMS using the setmqspl command. Refer to setmqspl for more information on this command. Each policy name must be the same as the queue name it is to be applied to.

Example

This is an example of a policy defined for the TEST.Q queue. In the example, messages are signed with the [Deprecated]

SHA1 algorithm and encrypted with the AES256 algorithm. alice is the only valid sender and bob is the only receiver of the messages on this queue:


setmqspl -m QM_VERIFY_AMS -p TEST.Q -s SHA1 -a "CN=alice,O=IBM,C=GB" -e AES256 -r "CN=bob,O=IBM,C=GB"

Note: The DNs match exactly those specified in the respective user's certificate from the key database.

What to do next

To verify the policy you have defined, issue the following command:


dspmqspl -m QM_VERIFY_AMS

To print the policy details as a set of setmqspl commands, use the -export flag. This allows storing already defined policies:


dspmqspl -m QM_VERIFY_AMS -export >restore_my_policies.bat

7. Testing the setup

About this task

By running different programs under different users you can verify if the application has been properly configured.

Procedure

Switch user to run as user alice

Right-click cmd.exe and select Run as.... When prompted, log in as the user alice.
As the user alice put a message using a sample application:
```
amqsput TEST.Q QM_VERIFY_AMS
```
Type the text of the message, then press Enter.
Switch user to run as user bob

Open another window by right-clicking cmd.exe and selecting Run as.... When prompted, log in as the user bob.
As the user bob get a message using a sample application:
```
amqsget TEST.Q QM_VERIFY_AMS
```

Results

If the application has been configured properly for both users, the user alice 's message is displayed when bob runs the getting application.

8. Testing encryption

About this task

To verify that the encryption is occurring as expected, create an alias queue which references the original queue TEST.Q. This alias queue will have no security policy and so no user will have the information to decrypt the message and therefore the encrypted data will be shown.

Procedure

Using the runmqsc command against queue manager QM_VERIFY_AMS, create an alias queue.
```
DEFINE QALIAS(TEST.ALIAS) TARGET(TEST.Q)
```

Grant bob access to browse from the alias queue


setmqaut -m QM_VERIFY_AMS -n TEST.ALIAS -t queue -p bob +browse

As the user alice, put another message using a sample application just as before:
```
amqsput TEST.Q QM_VERIFY_AMS
```
As the user bob, browse the message using a sample application via the alias queue this time:
```
amqsbcg TEST.ALIAS QM_VERIFY_AMS
```
As the user bob, get the message using a sample application from the local queue:
```
amqsget TEST.Q QM_VERIFY_AMS
```

Results

The output from the amqsbcg application shows the encrypted data that is on the queue proving that the message has been encrypted.