Set Policy

The Set Policy (MQCMD_CHANGE_PROT_POLICY) command sets the protection policy.

Important: We must have an Advanced Message Security (AMS) license installed to issue this command. If you attempt to issue the Set Policy command without an AMS license installed, you receive message AMQ7155 - License file not found or not valid.


Syntax diagram

See the syntax diagram in the MQSC SET POLICY on Multiplatforms command for combinations of parameters and values that are allowed.


Required parameters

    PolicyName (MQCFST)
    Specifies the name of the policy. The policy name must match the name of the queue which is to be protected (parameter identifier: MQCA_POLICY_NAME).

    The maximum length of the string is MQ_OBJECT_NAME_LENGTH.


Optional parameters

    SignAlg (MQCFIN)
    Specifies the digital signature algorithm (parameter identifier: MQIA_SIGNATURE_ALGORITHM). The following values are valid:

      MQESE_SIGN_ALG_NONE
      No digital signature algorithm specified. This is the default value.

      MQESE_SIGN_ALG_MD5
      MD5 digital signature algorithm specified.

      MQESE_SIGN_ALG_SHA1
      SHA1 digital signature algorithm specified.

      MQESE_SIGN_ALG_SHA256
      SHA256 digital signature algorithm specified.

      MQESE_SIGN_ALG_SHA384
      SHA384 digital signature algorithm specified.

      MQESE_SIGN_ALG_SHA512
      SHA512 digital signature algorithm specified.

    EncAlg (MQCFIN)
    Specifies the encryption algorithm (parameter identifier: MQIA_ENCRYPTION_ALGORITHM). The following values are valid:

      MQESE_ENC_ALG_NONE
      No encryption algorithm specified. This is the default value.

      MQESE_ENC_ALG_RC2
      RC2 encryption algorithm specified.

      MQESE_ENC_ALG_DES
      DES encryption algorithm specified.

      MQESE_ENC_ALG_3DES
      3DES encryption algorithm specified.

      MQESE_ENC_ALG_AES128
      AES128 encryption algorithm specified.

      MQESE_ENC_ALG_AES256
      AES256 encryption algorithm specified.

    Signer (MQCFST)
    Specifies the distinguished name of an authorized signer. This parameter can be specified multiple times (parameter identifier: MQCA_SIGNER_DN).

    Recipient (MQCFST)
    Specifies the distinguished name of the intended recipient. This parameter can be specified multiple times (parameter identifier: MQCA_RECIPIENT_DN).

    Enforce and Tolerate (MQCFST)
    Indicates whether the security policy should be enforced or whether unprotected messages are tolerated (parameter identifier: MQIA_TOLERATE_UNPROTECTED). The following values are valid:

      MQESE_TOLERATE_NO
      Specifies that all message must be protected when retrieved from the queue. Any unprotected message encountered is moved to the SYSTEM.PROTECTION.ERROR.QUEUE. This is the default value.

      MQESE_TOLERATE_YES
      Specifies that the messages that are not protected when retrieved from the queue can ignore the policy. Toleration is optional and exists to facilitate staged implementation, where:

      • Policies have been applied to queues, but those queues might already contain unprotected messages, or
      • Queues might still receive messages from remote systems that do not yet have the policy set.

    KeyReuse (MQCFIN)
    Specifies the number of times that an encryption key can be re-used, in the range 1-9,999,999, or the special values MQKEY_REUSE_DISABLED or MQKEY_REUSE_UNLIMITED (parameter identifier: MQIA_KEY_REUSE_COUNT). The following values are valid:

      MQKEY_REUSE_DISABLED
      Prevents a symmetric key from being reused. This is the default value.

      MQKEY_REUSE_UNLIMITED
      Allows a symmetric key to be reused any number of times.

    Attention: Key reuse is valid only for CONFIDENTIALITY policies, that is, SignAlg set to MQESE_SIGN_ALG_NONE and EncAlg set to an algorithm value. For all other policy types, we must omit the parameter, or set the Keyreuse value to MQKEY_REUSE_DISABLED.

    Action (MQCFIN)
    Specifies the action for the parameters supplied, as they apply to any existing policy (parameter identifier: MQIACF_ACTION). The following values are valid:

      MQACT_REPLACE
      Has the effect of replacing any existing policy with the parameters supplied. This is the default value.

      MQACT_ADD
      Has the effect that signers and recipients parameters have an additive effect. That is, if a signer or recipient is specified, and does not already exist in a preexisting policy, the signer or recipient value is added to the existing policy definition.

      MQACT_REMOVE
      Has the opposite effect of MQACT_ADD. That is, if any of the signer or recipient values specified exist in a preexisting policy, those values are removed from the policy definition.


Error codes

This command might return the following error codes in the response format header, in addition to the values shown at Error codes applicable to all commands.

    Reason (MQLONG)
    The value can be any of the following values:

      MQRCCF_POLICY_TYPE_ERROR
      Policy type not valid.

Parent topic: Definitions of the Programmable Command Formats