setmqspl (set security policy)

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

Before you begin

  • The queue manager on which you want to operate must be running.
  • You must grant the necessary +connect, +inq and +chg authorities, using the setmqaut command, to connect to the queue manager and create a security policy.

For more information about configuring security see Setting up security.

Syntax

Read syntax diagramSkip visual syntax diagram setmqspl -m QMgrName -pPolicyName Policy definition-remove
Policy definition
Read syntax diagramSkip visual syntax diagram -e NONERC21DES3DESAES128AES256 -rRecipientDN-aAuthorDN2 -s NONEMD5SHA1SHA256SHA384SHA512 -t01 -c1 - 9,999,9990*
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.
Table 1. setmqspl command flags
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 you 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
  • [z/OS]On z/OS® encryption algorithm RC2 is not supported for confidentiality policies.
-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 IBM® MQ 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 you 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

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