Quick Start Guide for UNIX platforms

Use this guide to quickly configure IBM® Advanced Message Security to provide message security on UNIX 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 components installed on your system:

Runtime
Server
Sample programs
IBM Global Security Kit
MQ Advanced Message Security

Refer to the following topics for the component names on each specific platform:

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 WebSphere MQ infrastructure through the standard WebSphere MQ interface. The basic setup is done in WebSphere MQ and is configured in the following steps.

You can use WebSphere 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 <MQ_INSTALL_PATH>/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 completed successfully, the following 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
```
useradd alice
useradd bob
```

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

User groups are now created and the required authorities granted to them. This way users who are assigned to those groups will also have permission to connect to the queue manager and to put and get from the queue.

What to do next

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

3. Creating key database and certificates

About this task

To encrypt the message, the interceptor requires the private key of the sending user and the public key(s) of the recipient(s). 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 the keytool command, which is part of the JRE (see Quick Start Guide for Java clients for more details). 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
```
mkdir /home/alice/.mqs -p
runmqakm -keydb -create -db /home/alice/.mqs/alicekey.kdb -pw passw0rd -stash
```
Note:
- It is advisable to use a strong password to secure the database.
- The stash parameter stores the password into the key.sth file, which interceptors can use to open the database.
Ensure the key database is readable
```
chmod +r /home/alice/.mqs/alicekey.kdb
```
Create a certificate identifying the user alice for use in encryption
```
runmqakm -cert -create -db /home/alice/.mqs/alicekey.kdb -pw passw0rd
-label Alice_Cert -dn "cn=alice,o=IBM,c=GB" -default_cert yes
```
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 not to use self-signed certificates but instead rely on certificates 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), which must be unique for each user.

Now we have created the key database, we should set the ownership of it, and ensure it is unreadable by all other users.


chown alice /home/alice/.mqs/alicekey.kdb /home/alice/.mqs/alicekey.sth
chmod 600 /home/alice/.mqs/alicekey.kdb /home/alice/.mqs/alicekey.sth

Repeat step 1-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 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 = /home/alice/.mqs/alicekey
cms.certificate = Alice_Cert

Note:

The path to the keystore file must be provided with no file extension.
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).
HOME/.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.

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 /home/alice/.mqs/alicekey.kdb -pw passw0rd -label Alice_Cert -target alice_public.arm

Add the certificate to bob's keystore:

runmqakm -cert -add -db /home/bob/.mqs/bobkey.kdb -pw passw0rd -label Alice_Cert -file alice_public.arm

Repeat the step for bob:

 runmqakm -cert -extract -db /home/bob/.mqs/bobkey.kdb -pw passw0rd -label Bob_Cert -target bob_public.arm

Add the certificate for bob to alice's keystore:

runmqakm -cert -add -db /home/alice/.mqs/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 by running the following commands which print out its details:

runmqakm -cert -details -db /home/bob/.mqs/bobkey.kdb -pw passw0rd -label Alice_Cert
runmqakm -cert -details -db /home/alice/.mqs/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 this example, messages are signed by the user alice using the SHA1 algorithm, and encrypted using the 256-bit AES 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, 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

Change to the directory containing the samples. If MQ is installed in a non-default location, this may be in a different place.
```
cd /opt/mqm/samp/bin
```
Switch user to run as user alice
```
su 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.
Stop running as user alice
```
exit
```
Switch user to run as user bob
```
su 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 will show the encrypted data that is on the queue proving that the message has been encrypted.