Quick Start Guide for AMS on Windows platforms

Use this guide to quickly configure Advanced Message Security 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

Refer to IBM MQ features for Windows systems for details.

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.

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

1. Create a queue manager

   crtmqm QM_VERIFY_AMS
   

2. Start the queue manager

   strmqm QM_VERIFY_AMS
   

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

1. Create the two users and ensure that HOMEPATH and HOMEDRIVE are set for both these users.
2. 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
   

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

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 the keytool command, which is part of the JRE (see Quick Start Guide for AMS with Java clients for more details). For all other languages, and for Java applications using local bindings, the steps in this guide are correct.

Procedure

1. Use the IBM Key Management GUI ( strmqikm.exe ) to create a new key database for the user alice.

   Type:       CMS
   Filename:   alicekey.kdb
   Location:   C:/Documents and Settings/alice/AMS
   

   Note:
   • It is advisable to use a strong password to secure the database.
   • Make sure that Stash password to a file check box is selected.
2. Change the key database content view to Personal Certificates.
3. Select New Self Signed ; self signed certificates are used in this scenario.
4. Create a certificate identifying the user alice for use in encryption, using these fields:

   Key label: Alice_Cert
   Common Name: alice
   Organisation: IBM
   Country: 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 not to use self-signed certificates but instead rely on certificates signed by a Certificate Authority.
   • The Key label parameter specifies the name for the certificate, which interceptors will look up to receive necessary information.
   • The Common Name and optional parameters specifies the details of the Distinguished Name (DN), which must be unique for each user.
5. 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 hold that information in the 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 should 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 configuration file.
• %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 Use keystores and certificates.
• 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

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

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

3. 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 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 receptive user's certificate from the key database.

What to do next

To verify the policy we 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 we can verify if the application has been properly configured.

Procedure

1. Switch user to run as user alice

   Right-click cmd.exe and select Run as.... When prompted, log in as the user alice.

2. As the user alice put a message using a sample application:

   amqsput TEST.Q QM_VERIFY_AMS
   

3. Type the text of the message, then press Enter.
4. 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.

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

1. Using the runmqsc command against queue manager QM_VERIFY_AMS, create an alias queue.

   DEFINE QALIAS(TEST.ALIAS) TARGET(TEST.Q)
   

2. Grant bob access to browse from the alias queue

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

3. As the user alice, put another message using a sample application just as before:

   amqsput TEST.Q QM_VERIFY_AMS
   

4. As the user bob, browse the message using a sample application via the alias queue this time:

   amqsbcg TEST.ALIAS QM_VERIFY_AMS
   

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