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. IBM MQ 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 <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 managerQM_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 IBM MQ 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
- 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 encryptionrunmqakm -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 IBM MQ 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) for AMS.
- HOME/.mqs/keystore.conf is the default location where IBM MQ 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
toalice'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 queuesetmqaut -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