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, we will have created a keystore to verify user identities, and defined signing/encryption policies for the queue manager.

Before starting

Ensure you have the appropriate components installed as described in the Quick Start Guide (Windows or UNIX). Parent topic: User scenarios

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 UNIX ) for the 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

We must 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

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 we plan to use Java applications using local bindings or C applications, create a CMS keystore and certificates using the runmqakm command. This is shown in the Quick Start Guide ( Windows or UNIX ).

Procedure

Create a directory in which to create your keystore, for example /home/alice/.mqs. We might wish to create it in the same directory as used by the Quick Start Guide ( Windows or UNIX ) for the platform. 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, we must put quotes round the full name of our 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 UNIX, 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

We 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 UNIX ), we can edit the existing file to add these lines.

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. Note: The terms extract and export are used differently by different certificate tools. For example the IBM GSKit Keyman (ikeyman) tool makes a distinction that you extract certificates (public keys) and you export private keys. This distinction is extremely important for tools that offer both options, since using export by mistake would completely compromise the application by passing on its private key. Because the distinction is so important, the IBM MQ documentation strives to use these terms consistently. However, the Java keytool provides a command line option called exportcert that extracts only the public key. For these reasons, the following procedure refers to extracting certificates by using the exportcert option.

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 we 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 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 receptive 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 starting

Ensure the version of Java we 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 we can verify if the application has been properly configured. Refer to the Quick Start Guide ( Windows or UNIX ) for the platform, for details about running programs under different users.

Procedure

To run these JMS sample applications, use the CLASSPATH setting for the 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.