This method sets security properties for a directory object specified by an object identifier.

 HRESULT S_DSSetObjectSecurityGuid(
   [in] handle_t hBind,
   [in, range(1,58)] unsigned long dwObjectType,
   [in] const GUID* pGuid,
   [in] unsigned long SecurityInformation,
   [in, unique, size_is(nLength)] unsigned char* pSecurityDescriptor,
   [in, range(0,524288)] unsigned long nLength
 );

hBind: MUST specify an RPC binding handle, as specified in [MS-RPCE] section 2.

dwObjectType:  Specifies the type of object for which security properties are set. MUST be set to one of the object types specified in section 2.2.8.

pGuid: MUST be set by the client to a pointer to the GUID of the object for which properties are to be set.

SecurityInformation: MUST be set by the client to a bitwise mask specifying the information to set from the pSecurityDescriptor parameter. See the SecurityInformation parameter description in section 3.1.4.11.

pSecurityDescriptor: MUST contain a pointer to security descriptor, as specified in [MS-DTYP] section 2.4.6, or to an MQDS_PublicKey structure.<68> See the pSecurityDescriptor parameter description in section 3.1.4.11. Note that while section 3.1.4.11 indicates that pSecurityDescriptor contains a BLOBHEADER followed by an RSAPUBKEY (section 2.2.18) structure, this method actually contains an MQDS_PublicKey structure, which is the same structure prefixed by a 4-byte length field.

nLength: MUST be set by the client to the length in bytes of the pSecurityDescriptor buffer.

Return Values: If the method succeeds, the return value is 0x00000000. If the method fails, the return value is an implementation-specific error code.

MQ_OK (0x00000000)

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol extension, as specified in [MS-RPCE].

When processing this call, the server MUST:

• Let dirObject be a directory object and initialized to NULL.

• The server MAY<69> forward the update to another server.

• If the dwObjectType is MQDS_QUEUE:

  • Generate the Get Directory Object for Update (section 3.1.6.14) event with the arguments set to MQDS_QUEUE, NULL and pGuid respectively. If rStatus returned by the event is not MQ_OK, return rStatus and take no further action; otherwise, set dirObject to rObject.

  • Update dirObject.Security with information from pSecurityDescriptor, SecurityInformation.

  • Generate the Commit Directory Object Update (section 3.1.6.15) event with the arguments set to dirObject and "Security" respectively. If rStatus returned by the event is not MQ_OK, return rStatus and take no further action.

  • If the Computer portion of the dirObject.PathName (as described in [MS-MQMQ] section 2.1.1) is different from the LocalQueueManager.ComputerName, the server MAY do the following:<70>

    • Generate a Send Change Notification event as specified in [MS-MQCN] section 3.3.4.1 with the following parameters:

      • iOperation := QueueUpdate

      • iDirectoryObject := dirObject

• If the dwObjectType is MQDS_MACHINE:

  • If SecurityInformation is MQDS_KEYX_PUBLIC_KEY (0x40000000):

    • Generate the Get Directory Object for Update event with the arguments set to MQDS_MACHINE, NULL and pGuid respectively. If rStatus returned by the event is not MQ_OK, return rStatus and take no further action; otherwise, set dirObject to rObject.

    • Extract the RSAPUBKEY structure from the abPublicKeyBlob field of the MQDS_PublicKey structure to which pSecurityDescriptor points. Construct an MQDSPUBLICKEY structure, initialized as specified in [MS-MQMQ] section 2.2.1, with the sProviderName field set to "Microsoft Base Cryptographic Provider v1.0" and the aBuf field set to the RSAPUBKEY structure that was extracted in the previous step. Then construct an MQDSPUBLICKEYS structure, initialized as specified in [MS-MQMQ] section 2.2.2, with the just-constructed MQDSPUBLICKEY structure as the only element of aPublicKeys.

    • Set dirObject.PublicEncryptionKeyList to the MQDSPUBLICKEYS structure.

  • If SecurityInformation is MQDS_SIGN_PUBLIC_KEY (0x80000000):

    • Generate the Get Directory Object for Update event with the arguments set to MQDS_MACHINE, NULL and pGuid respectively. If rStatus returned by the event is not MQ_OK, return rStatus and take no further action; otherwise, set dirObject to rObject.

    • Extract the RSAPUBKEY structure from the abPublicKeyBlob field of the MQDS_PublicKey structure to which pSecurityDescriptor points. Construct an MQDSPUBLICKEY structure, initialized as specified in [MS-MQMQ] section 2.2.1, with the sProviderName field set to "Microsoft Base Cryptographic Provider v1.0" and the aBuf field set to the RSAPUBKEY structure that was extracted in the previous step. Then construct an MQDSPUBLICKEYS structure, initialized as specified in [MS-MQMQ] section 2.2.2, with the just-constructed MQDSPUBLICKEY structure as the only element of aPublicKeys.

    • Set dirObject.PublicSigningKeyList to the MQDSPUBLICKEYS structure.

  • If SecurityInformation is a bitwise OR of any combination of OWNER_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION, and DACL_SECURITY_INFORMATION:

    • Generate the Get Directory Object for Update event with the arguments set to MQDS_MACHINE, NULL and pGuid respectively. If rStatus returned by the event is not MQ_OK, return rStatus and take no further action; otherwise, set dirObject to rObject.

    • Update dirObject.Security with information from pSecurityDescriptor, SecurityInformation.

  • If dirObject is not NULL:

    • Generate the Commit Directory Object Update (section 3.1.6.15) event with the arguments set to dirObject and "Security" respectively. If rStatus returned by the event is not MQ_OK, return rStatus and take no further action.

  • If the dirObject.Identifier is different from the LocalQueueManager.Identifier, the server MAY do the following:<71>

    • Generate a Send Change Notification event as specified in [MS-MQCN] section 3.3.4.1 with the following parameters:

      • iOperation := QueueManagerUpdate

      • iDirectoryObject := dirObject

• If the dwObjectType is MQDS_SITE:

  • If SecurityInformation is MQDS_SIGN_PUBLIC_KEY (0x80000000):

    • Generate the Get Directory Object for Update event with the arguments set to MQDS_SITE, NULL and pGuid respectively. If rStatus returned by the event is not MQ_OK, return rStatus and take no further action; otherwise, set dirObject to rObject.

    • Extract the RSAPUBKEY structure from the abPublicKeyBlob field of the MQDS_PublicKey structure to which pSecurityDescriptor points. Construct an MQDSPUBLICKEY structure, initialized as specified in [MS-MQMQ] section 2.2.1, with the sProviderName field set to "Microsoft Base Cryptographic Provider v1.0" and the aBuf field set to the RSAPUBKEY structure that was extracted in the previous step. Then construct an MQDSPUBLICKEYS structure, initialized as specified in [MS-MQMQ] section 2.2.2, with the just-constructed MQDSPUBLICKEY structure as the only element of aPublicKeys.

    • Set dirObject.PublicSigningKeyList to the MQDSPUBLICKEYS structure.

    • Generate the Commit Directory Object Update event with the arguments set to dirObject and "Security" respectively. If rStatus returned by the event is not MQ_OK, return rStatus and take no further action.

• If the dwObjectType is MQDS_CN:

  • Generate the Get Directory Object for Update event with the arguments set to MQDS_CN, NULL and pGuid respectively. If rStatus returned by the event is not MQ_OK, return rStatus and take no further action; otherwise, set dirObject to rObject.

  • Update dirObject.Security with information from pSecurityDescriptor, SecurityInformation.

  • Generate the Commit Directory Object Update event (section 3.1.6.15) with the arguments set to dirObject and "Security" respectively. If rStatus returned by the event is not MQ_OK, return rStatus and take no further action.

• The server MAY<72> contact other servers to propagate the changes.