setmqspl (set security policy)

Use the setmqspl command to define a new security policy, alter an already existing one, or remove an existing policy.


Syntax

setmqspl -m QMgrName -pPolicyName Policy definition-remove Policy definition -e NONERC21DES3DESAES128AES256 -rRecipientDN-aAuthorDN2 -s NONEMD5SHA1SHA256SHA384SHA512 -t 01 Notes:

  • 1 If an encryption algorithm is selected, a recipient DN must also be provided.
  • 2 If an author DN is provided, a signing algorithm must also be selected.

Command flag Explanation
-m Queue manager name.

This flag is mandatory for all actions on security policies.

-p Policy name.

Set the policy name to the name of the queue we want the policy to apply to.

-e Digital encryption algorithm.

Advanced Message Security supports the following encryption algorithms: RC2, DES, 3DES, AES128, AES256. The default value is NONE.

Important: The name of the encryption algorithm must be provided in uppercase
-r The distinguished name (DN) of the message recipient (if provided, the certificate pertaining to the DN is used to encrypt a given message). Recipients can be specified, only if the encryption algorithm is different from NONE. Multiple recipients can be included for a message. Each DN must be provided with a separate -r flag. Important:

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

For example: 

-r "CN=alice, O=ibm, C=US"
-a Signature DN that is validated during message retrieval. Only messages signed by a user with a provided DN are accepted during the retrieval. Signature DNs can be specified only if the signature algorithm is different from NONE. Multiple authorized signers can be specified, each authorized signer needs to have a separate -a flag. Important: The attribute in the DN name must be in uppercase. Specify CN= rather than cn=.

The attribute values in the DN are case sensitive so, for example, CN=USERID1 is different from CN=userid1.
-s Digital signature algorithm.

Advanced Message Security supports the following values: MD5, SHA1, SHA256, SHA384, and SHA512. All must be in uppercase. The default value is NONE.

Important:

  • For the SHA384 and SHA512 cryptographic hash functions, keys used for signing must be longer than 768 bits.
  • The name of the signature algorithm must be provided in uppercase.
  • From Version 9.0, with the Confidentiality policy, the signature algorithm must be NONE. For more information about the Confidentiality policy, see Qualities of protection available with AMS.

-t The toleration flag indicates whether messages that do not meet the requirements of the policy can still be successfully browsed or retrieved by an application. Toleration may be useful for example when introducing a policy to a queue which already contains unprotected messages. Valid values include:

    • 0 (default)
      Toleration flag off.

    • 1
      Toleration flag on.

Toleration is optional and facilitates staged implementation, where policies were applied to queues but those queues may already contain messages that have no policy, or still receive messages from remote systems that do not have the security policy set.
-c The key reuse count can be provided as an integer from 1 through 9,999,999. Special values are:

    • 0
      Keys are not reused.

    • *
      Allows applications to reuse an encryption key an unlimited number of times.

If we omit the -c parameter when defining a policy, a key reuse count of 0 is assumed for backwards compatibility with previous versions of Advanced Message Security and IBM WebSphere MQ Extended Security Edition.

Note that a non-zero key reuse count is only valid for a confidentiality policy. If you attempt to create or modify an integrity or privacy policy, with a non-zero key reuse count, you receive error message AMQ9091: Key reuse is not valid for policy and the policy operation fails.
-remove Delete policy.

Only the policy name flag, -p is valid for use in combination with this flag.


Examples

The following list shows examples of some valid setmqspl commands on Multiplatforms:
setmqspl -m QMGR -p PROT -s SHA256
setmqspl -m QMGR -p PROT -s SHA256 -a "CN=Alice, O=IBM, C=US"
setmqspl -m QMGR -p PROT -s SHA256 -e AES128 -a "CN=Alice, O=IBM, C=US" -r "CN=Bob, O=IBM, C=GB"
setmqspl -m QMGR -p PROT -e AES128 -r "CN=Bob, O=IBM, C=GB" -c 50
The following list shows examples of setmqspl commands that are not valid:

  • No recipients specified:
    setmqspl -m QMGR -p PROT -e AES128
  • Key reuse not valid for an Integrity policy:
    setmqspl -m QMGR -p PROT -s SHA256 -c 1
  • Key reuse is not valid for a Privacy policy:
    setmqspl -m QMGR -p PROT -s SHA256 -e AES128 -r "CN=Bob, O=IBM, C=GB" -c 1

On z/OS, we can use the setmqspl command with the CSQ0UTIL utility. For more information, see The message security policy utility (CSQ0UTIL).