3.1.4.13 S_DSSetObjectSecurity (Opnum 5)
This method sets security properties for a directory object specified by a directory service pathname.
-
HRESULT S_DSSetObjectSecurity( [in] handle_t hBind, [in, range(1,58)] unsigned long dwObjectType, [in] const wchar_t* pwcsPathName, [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 to be set. MUST be one of the object types specified in section 2.2.8.
pwcsPathName: Pointer to a NULL-terminated 16-bit Unicode string that MUST contain the directory service pathname, as specified in section 2.2.9, of the object in the directory service.
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. Information in the pSecurityDescriptor parameter not associated with bits set in this field MUST be ignored.
pSecurityDescriptor: MUST contain a pointer to a security descriptor, as specified in [MS-DTYP] section 2.4.6, or to an MQDS_PublicKey structure.<63> See the pSecurityDescriptor parameter description in section 3.1.4.11. Note that where 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 extension protocol, as specified in [MS-RPCE].
When processing this call, the server MUST:
The server MAY<64> forward the update to another server.
Let dirObject be a directory object and initialized to NULL.
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, pwcsPathName, and NULL 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 and 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<65> do the following:
Generate a Send Change Notification event as specified in [MS-MQCN] section 3.3.4.1 with the following arguments:
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, pwcsPathName, and NULL 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, pwcsPathName, and NULL 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, pwcsPathName, and NULL 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 and SecurityInformation.
If dirObject is not NULL:
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 dirObject.Identifier is different from the LocalQueueManager.Identifier, the server MAY do the following:<66>
Generate a Send Change Notification event as specified in [MS-MQCN] section 3.3.4.1 with the following arguments:
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, pwcsPathName, and NULL 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, pwcsPathName, and NULL 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 and SecurityInformation.
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.
The server MAY<67> contact other servers to propagate the changes.