Understanding setmqspl to set up AMS definitions.

At first glance, how difficult can it be to understand a command with only five operands? As I do not usually write about easy topics, you may be able to guess that there is some subtlety to it.

Background to AMS protection

There are three protection models in AMS. See the IBM Knowledge centre.

1. Integrity.
2. Encryption.
3. Privacy = Encryption and Integrity.

Integrity

A checksum is made of the message contents, and the check sum is encrypted with the senders private key. The sender’s public key, the encrypted checksum, and the original payload are put into a message and put to a queue. This can be sent to a remote queue manager, or remain on the local queue manager. The recipient, performs the same checksum calculation on the original payload, decrypts the embedded checksum value (using information from the public certificate). If the checksums match – the messages is unchanged we have integrity

With Integrity, the getting queue manager knows the DN of the userid doing the signing.

With integrity, you need to specify which checksum technique to use, and at the getting end, you can optionally specify a list of authorised senders, and AMS will check the DN of the sender is in the list.

Confidentiality

The message contents are encrypted with a symmetric key. The key is then encrypted for the list of recipients, using the each recipient’s public key. A package of [(recipient, encrypted key) (recipient, encrypted key).. encrypted message] is put to a queue. When the message is got, the getter locates the (recipient, encrypted key) for it, uses its private certificate to decrypt the key to the data, and uses this to decrypt the message content.

With encryption you need to specify which encryption technique to use, and the list of recipients. For each recipient, AMS goes to the key store at the putting end to get the public certificate.

Privacy

A combination of Integrity and Confidentiality. The data is encrypted, and signed. The getting queue manager knows the DN of the sender.

setmqspl syntax

The syntax is

• setmqspl
• -m name queue manager name
• -policy name the queue name – known as the policy name
• -e value which cipher spec to use – or none
• -r DN a list of 1 or more recipient’s DN
• -s value the signing algorithm to use or none
• -a DN a list of 0 or more acceptable signers DN values (the putter’s DN).

I’ll focus on the -e, -r, -s and -a values.

Looking at a distributed MQ environment, should make it clearer

We have a putter queue manager. Messages go to another queue manager (or stay on the same queue manager) where the messages are got.

Integrity

At the putting queue manager you need

• setmqspl -m qmname -policy queuename -s algorithm
• Pick an algorithm from MD5, SHA1, SHA256, SHA384, SHA512, where the SHAnnn are more secure (it is all relative) but MD5 may be faster. The algorithm you pick will be used.
• -r and -a values are ignored from an integrity and signing perspective

At the getting end you need

• setmqspl -m qmname -policy queuename -s algorithm <-a DN… >
• You can specify any algorithm, (as long as the value is not NONE). This says expect a signed payload. The value is not used.
• The -a DN1 -a DN2… the optional list of values are the authorised DNs from the certificate of the userid that put (and signed) the message. If none are specified, then no checking is done. If there is at least one specified, then the signer’s DN is checked. If it is in the list, the message is returned to the application, if it is not in the list, the message get is rolled back, or put on the SYSTEM.PROTECTION.ERROR.QUEUE queue.

Confidentiality

At the putting end you need

• setmqspl -m qmname -policy queuename -e algorithm -r DN… .
• Pick a digital encryption algorithm from RC2,DES,3DES,AES128,AES256 , where the AESnnn are better than the others. The algorithm you pick will be used.
• The -r value is the DN of a potential recipient. The payload key is encrypted for each DN in the list.

At the getting end you need

• setmqspl -m qmname -policy queuename -e algorithm .
• You can specify any algorithm (as long as the value is not NONE), then this says expect an encrypted message. The value is not used.
• Any -r DN values will be ignored, as they are not relevant. The recipients are identified by the presence of the encrypted key in the payload.

Privacy

See above under Integrity and Confidentially

Specifying a DN

The documentation says

• DN attribute names must be in uppercase.
• Commas must be used as a name separators.
• To avoid command interpreter errors, place quotation marks around the DNs.
• The attribute values in the DN are case sensitive so, for example, CN=USERID1 is different from CN=userid1.

There is a convention (not a standard as such) that there is a hierarchy in the terms, for example starting with CN= on the left, and C= on the right. Some key stores, such as RACF will arrange the parts of the DN into this order.

AMS allows blanks between parts, for example “CN=COLIN , O=SSS”. These padding blanks are not present in certificates, but significant blanks such as within “CN=COLIN PAICE” are kept.

When trying to resolve AMS “missing certificates” problems, I found it easier when I had the parts of the DN in the right order, and did not have extra blanks between terms. It means I could just cut and paste the DN when searching in the key store.

Other AMS blog posts

• Overview and challenges of using end to end message encryption (AMS).
• Certificate and keyring management for AMS.
• Installing AMS on z/OS.
• What certificates do I need for AMS with a client going to z/OS?
• checkAMS: program to check your AMS defintions are consistent with z/OS keyring
• Adding more users to AMS.
• Installing AMS on midrange for end to end message protection
• Understanding setmqspl to set up AMS definitions.
• How to administer AMS policies, and use the set policy command.
• Brain check and reset, needed for AMS keystores on midrange.
• Using runamscred to encrypt the passwords in the keystore.conf file.
• How do I find the recipients and signer of an AMS message?
• I have a message on the AMS DLQ – what can I do about it? and How do I process messages on the dead letter queue (DLQ)?