Quick Start Guide for AMS with Java clients

Use this guide to quickly configure Advanced Message Security to provide message security for Java applications connecting using client bindings. By the time you complete it, you will have created a keystore to verify user identities, and defined signing/encryption policies for your queue manager.

Before you begin

Ensure you have the appropriate components installed as described in Quick Start Guide for AMS on Windows platforms or Quick Start Guide for AMS on AIX and Linux.

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.

Procedure

Create a queue manager
```
crtmqm QM_VERIFY_AMS
```
Start the queue manager
```
strmqm QM_VERIFY_AMS
```
Create and start a listener by entering the following commands into runmqsc for queue manager QM_VERIFY_AMS
```
DEFINE LISTENER(AMS.LSTR) TRPTYPE(TCP) PORT(1414) CONTROL(QMGR)
```
```
START LISTENER(AMS.LSTR)
```
Create a channel for our applications to connect in through by entering the following command into runmqsc for queue manager QM_VERIFY_AMS
```
DEFINE CHANNEL(AMS.SVRCONN) CHLTYPE(SVRCONN)
```
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 completed successfully, the following command entered into runmqsc displays details about TEST.Q:


DISPLAY Q(TEST.Q)

2. Creating and authorizing users

About this task

There are two users that appear in this scenario: 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 defined in this scenario, 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 as described in the Quick Start Guide (Windows or AIX and Linux) for your platform.

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 +inq +browse

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 JmsProducer and JmsConsumer samples as described in section 7. Testing the setup.

3. Creating key database and certificates

About this task

To encrypt the message to interceptor requires the public key of the sending users. 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 computer, 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 Java connecting using client bindings. If you plan to use Java applications using local bindings or C applications, you must create a CMS keystore and certificates using the runmqakm command. For more information, see Quick Start Guide for AMS on Windows platforms and Quick Start Guide for AMS on AIX and Linux.

Procedure

Create a directory in which to create your keystore, for example /home/alice/.mqs. You might wish to create it in the same directory as used by the Quick Start Guide for your platform. For more information, see Quick Start Guide for AMS on Windows platforms and Quick Start Guide for AMS on AIX and Linux.

Note: This directory is referred to as keystore-dir in the following steps
Create a new keystore and certificate identifying the user alice for use in encryption

Note: The keytool command is part of the JRE.
```
keytool -genkey -alias Alice_Java_Cert -keyalg RSA -keystore keystore-dir/keystore.jks -storepass passw0rd
-dname "CN=alice, O=IBM, C=GB" -keypass passw0rd
```
Note:
- If your keystore-dir contains spaces, you must put quotes round the full name of your keystore
- It is advisable to use a strong password to secure the keystore.
- 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 not to use self-signed certificates but instead rely on certificates signed by a Certificate Authority.
- The alias parameter specifies the name for the certificate, which interceptors will look up to receive necessary information.
- The dname parameter specifies the details of the Distinguished Name (DN), which must be unique for each user.
On AIX and Linux, ensure the keystore is readable
```
chmod +r keystore-dir/keystore.jks
```
Repeat step1-4 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 hold that information in the plain text form. Each user must have a separate keystore.conf file. This step should be done for both alice and bob.

Example

For this scenario, the contents of the keystore.conf for alice are as follows:


JKS.keystore = keystore-dir/keystore
JKS.certificate = Alice_Java_Cert
JKS.encrypted = no
JKS.keystore_pass = passw0rd
JKS.key_pass = passw0rd
JKS.provider = IBMJCE

For this scenario, the contents of the keystore.conf for bob are as follows:


JKS.keystore = keystore-dir/keystore
JKS.certificate = Bob_Java_Cert
JKS.encrypted = no
JKS.keystore_pass = passw0rd
JKS.key_pass = passw0rd
JKS.provider = IBMJCE

Note:

The path to the keystore file must be provided with no file extension.
If you already have a keystore.conf file because you have followed the instructions in the Quick Start Guide (Windows or AIX and Linux), you can edit the existing file to add these lines.
For more information, see Structure of the keystore configuration file (keystore.conf) for AMS.

5. Sharing certificates

About this task

Share the certificates between the two keystores so that each user can successfully identify the other. This is done by extracting each user's certificate and importing it into the other user's keystore.

Important: The terms extract and export are used differently by different certificate management commands.

The IBM Global Security Kit (GSKit) runmqakm command uses the term extract to refer to the process of copying only the public part of a certificate from a keystore, and the term export to refer to the process of copying certificates and their associated public and private keys from one keystore to another.
The Java keytool command, and the IBM MQ runmqktool command, use the term export to refer to the process of copying only the public part of a certificate from a keystore.

This distinction is important since using export incorrectly can compromise your application by exposing its private key. Because the distinction is so important, the IBM MQ documentation uses these terms consistently. For these reasons, the following procedure refers to extracting certificates by using the exportcert option in the keytool command.

Procedure

Extract the certificate identifying alice.


keytool -exportcert -keystore alice-keystore-dir/keystore.jks -storepass passw0rd
-alias Alice_Java_Cert -file alice-keystore-dir/Alice_Java_Cert.cer

Import the certificate identifying alice into the keystore that bob will use. When prompted indicate that you will trust this certificate.


keytool -importcert -file alice-keystore-dir/Alice_Java_Cert.cer -alias Alice_Java_Cert
-keystore bob-keystore-dir/keystore.jks -storepass passw0rd

Repeat the steps for bob

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 by running the following commands which print out its details:


keytool -list -keystore bob-keystore-dir/keystore.jks -storepass passw0rd -alias Alice_Java_Cert


keytool -list -keystore alice-keystore-dir/keystore.jks -storepass passw0rd -alias Bob_Java_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 on the TEST.Q queue, signed by the user alice using the [Deprecated]

SHA1 algorithm, and encrypted using the 256-bit AES algorithm for the user bob:


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, the -export flag. This allows storing already defined policies:


dspmqspl -m QM_VERIFY_AMS -export >restore_my_policies.bat

7. Testing the setup

Before you begin

Ensure the version of Java you are using has the unrestricted JCE policy files installed.

Note: The version of Java supplied in the IBM MQ installation already has these policy files. It can be found in MQ_INSTALLATION_PATH/java/bin.

About this task

By running different programs under different users you can verify if the application has been properly configured. For more information about running programs under different users, see Quick Start Guide for AMS on Windows platforms and Quick Start Guide for AMS on AIX and Linux.

Procedure

To run these JMS sample applications, use the CLASSPATH setting for your platform as shown in Environment variables used by IBM MQ classes for JMS to ensure the samples directory is included.

As the user alice, put a message using a sample application, connecting as a client:


java JmsProducer -m QM_VERIFY_AMS -d TEST.Q -h localhost -p 1414 -l AMS.SVRCONN

As the user bob, get a message using a sample application, connecting as a client:


java JmsConsumer -m QM_VERIFY_AMS -d TEST.Q -h localhost -p 1414 -l AMS.SVRCONN

Results

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