<div class="content" name="S_DSGetObjectSecurity" uuid="a7926c44-588a-4347-bed1-6a3ea4dcb281"><p>This method gets security properties for a directory object
specified by a <a href="993fa29f-3deb-494f-b4b4-492ee945735f#gt_c36db657-3138-4d9a-9289-ded5cbb8b40e" data-linktype="relative-path">directory
service</a> pathname.</p><dl>
<dd>
<div><pre> HRESULT S_DSGetObjectSecurity(
   [in] handle_t hBind,
   [in, range(1,58)] unsigned long dwObjectType,
   [in] const wchar_t* pwcsPathName,
   [in] unsigned long SecurityInformation,
   [out, size_is(nLength)] unsigned char* pSecurityDescriptor,
   [in, range(0,524288)] unsigned long nLength,
   [out] unsigned long* lpnLengthNeeded,
   [in] PCONTEXT_HANDLE_SERVER_AUTH_TYPE phServerAuth,
   [out, size_is(*pdwServerSignatureSize)] 
     unsigned char* pbServerSignature,
   [in, out] LPBOUNDED_SIGNATURE_SIZE pdwServerSignatureSize
 );
</pre></div>
</dd></dl><p><b>hBind: </b> MUST specify an <a href="993fa29f-3deb-494f-b4b4-492ee945735f#gt_8a7f6700-8311-45bc-af10-82e10accd331" data-linktype="relative-path">RPC</a> binding handle, as
specified in <a href="../ms-rpce/290c38b1-92fe-4229-91e6-4fc376610c15" data-linktype="relative-path">[MS-RPCE]</a>
section <a href="../ms-rpce/a01f5886-c485-4bcf-bb23-e0d755510ab7" data-linktype="relative-path">2</a>.</p><p><b>dwObjectType: </b> Specifies the type of object for which
security properties are to be retrieved. MUST be set to one of the object types
defined in section <a href="0d63e0e1-8b17-4103-9080-01e6c7c9f61f" data-linktype="relative-path">2.2.8</a>.</p><p><b>pwcsPathName: </b>Pointer to a NULL-terminated 16-bit <a href="993fa29f-3deb-494f-b4b4-492ee945735f#gt_b069acb4-e364-453e-ac83-42d469bb339e" data-linktype="relative-path">Unicode string</a> that MUST
contain the directory service pathname, as specified in section <a href="6e03fb44-a705-4728-acca-7c6d7b8d7396" data-linktype="relative-path">2.2.9</a>, of the object in
the directory service.</p><p><b>SecurityInformation: </b>A bitwise mask of the
information to be returned in the <i>pSecurityDescriptor</i> parameter. The bit
fields are defined by the following table:</p><table><thead>
  <tr>
   <th>
   <p>Value</p>
   </th>
   <th>
   <p>Meaning</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>OWNER_SECURITY_INFORMATION 0x00000001</td>
  <td>OWNER field from the security descriptor.</td>
 </tr><tr>
  <td>GROUP_SECURITY_INFORMATION 0x00000002</td>
  <td>GROUP field from the security descriptor.</td>
 </tr><tr>
  <td>DACL_SECURITY_INFORMATION 0x00000004</td>
  <td>Discretionary ACL field from the security descriptor.</td>
 </tr><tr>
  <td>SACL_SECURITY_INFORMATION 0x00000008</td>
  <td>System ACL field from the security descriptor.</td>
 </tr><tr>
  <td>MQDS_SIGN_PUBLIC_KEY 0x80000000</td>
  <td>Signing public key.</td>
 </tr><tr>
  <td>MQDS_KEYX_PUBLIC_KEY 0x40000000</td>
  <td>Encrypting public key.</td>
 </tr></tbody></table><p>The <i>SecurityInformation</i> parameter MUST specify one
of:</p><ul><li><p><span><span> 
</span></span>MQDS_SIGN_PUBLIC_KEY, or</p>
</li><li><p><span><span> 
</span></span>MQDS_KEYX_PUBLIC_KEY, or</p>
</li><li><p><span><span> 
</span></span>A bitwise OR of any combination of: </p>
<ul><li><p><span><span>  </span></span>OWNER_SECURITY_INFORMATION</p>
</li><li><p><span><span>  </span></span>GROUP_SECURITY_INFORMATION</p>
</li><li><p><span><span>  </span></span>DACL_SECURITY_INFORMATION</p>
</li><li><p><span><span>  </span></span>SACL_SECURITY_INFORMATION</p>
</li></ul></li></ul><p>If the <i>SecurityInformation</i> parameter includes an
invalid combination, the server MUST NOT complete the call, and MUST return an
error.</p><p><b>pSecurityDescriptor: </b>If the <i>SecurityInformation</i>
parameter is MQDS_SIGN_PUBLIC_KEY or MQDS_KEYX_PUBLIC_KEY, it SHOULD<a id="Appendix_A_Target_55"></a><a aria-label="Product behavior note 55" href="9c868bc8-426a-4e5f-8b45-cee7d49c3d10#Appendix_A_55" data-linktype="relative-path">&lt;55&gt;</a> contain a pointer to a <a href="588d8ab6-a559-4698-af82-8f4d489cfc0e" data-linktype="relative-path">BLOBHEADER (section 2.2.19)</a>
structure followed by an <a href="7567bcfb-7972-4bb9-abcf-c19b2eedf57f" data-linktype="relative-path">RSAPUBKEY (section 2.2.18)</a>
structure. Otherwise, this parameter contains a security descriptor, as
specified in <a href="../ms-dtyp/cca27429-5689-4a16-b2b4-9325d93e4ba2" data-linktype="relative-path">[MS-DTYP]</a>
section <a href="../ms-dtyp/7d4dac05-9cef-4563-a058-f108abecce1d" data-linktype="relative-path">2.4.6</a>.</p><p><b>nLength: </b> MUST be set by the client to the length in
bytes of the <i>pSecurityDescriptor</i> buffer.</p><p><b>lpnLengthNeeded: </b> A <a href="../ms-dtyp/262627d8-3418-4627-9218-4ffe110850b2" data-linktype="relative-path">DWORD</a>
representing the length in bytes of the requested security descriptor or public
key. </p><p><b>phServerAuth: </b> A <a href="c28a1e6b-4092-4443-b69f-5814d5c4f9e4" data-linktype="relative-path">PCONTEXT_HANDLE_SERVER_AUTH_TYPE</a>
RPC context handle acquired from the <i>pphServerAuth</i> parameter in a
previous call to <a href="0e3ad7d0-6a64-480a-9f13-e94dd608d79d" data-linktype="relative-path">S_DSValidateServer</a>.
The server MUST use this parameter as a key to locate the GSS security context
used to compute the signature returned in <i>pbServerSignature</i>. See section
3.1.4.2. </p><p><b>pbServerSignature: </b>Contains a signed hash over the
returned property values. </p><p><b>pdwServerSignatureSize: </b>A DWORD that contains the
maximum length in bytes of the server signature to return.</p><p><b>Return Values: </b> If the method succeeds, the return
value is 0. If the method fails, the return value is an implementation-specific
error code.</p><p><b>MQ_OK</b> (0x00000000)</p><p><b>MQ_ERROR_USER_BUFFER_TOO_SMALL</b> (0xC00E0028)</p><p><b>MQ_ERROR_SECURITY_DESCRIPTOR_TOO_SMALL</b> (0xC00E0023)</p><p><b>MQDS_WRONG_OBJ_TYPE</b> (0xC00E0506)</p><p><b>MQ_ERROR_INVALID_PARAMETER</b> (0xC00E0006)</p><p><b>Exceptions Thrown:</b> No exceptions are thrown beyond
those thrown by the underlying RPC protocol, as specified in [MS-RPCE].</p><p> When processing this call, the server MUST:</p><ul><li><p><span><span> 
</span></span>Include the information specified by the <i>SecurityInformation</i>
parameter in the returned security descriptor.</p>
</li><li><p><span><span> 
</span></span>Let <i>dirObject</i> be a directory object and initialized to
NULL.</p>
</li><li><p><span><span> 
</span></span>If the <i>dwObjectType</i> is MQDS_QUEUE, and <i>SecurityInformation</i>
is a bitwise OR of any combination of OWNER_SECURITY_INFORMATION,
GROUP_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION, and
DACL_SECURITY_INFORMATION:</p>
<ul><li><p><span><span>  </span></span>Generate
the <a href="5c5b8c07-fef2-4e03-ba2d-7e6fc6527d6e" data-linktype="relative-path">Get Directory
Object (section 3.1.6.12)</a> event with the arguments set to
MQDS_QUEUE, <i>pwcsPathName</i>, and NULL respectively. If <i>rStatus</i>
returned by the event is not MQ_OK, return <i>rStatus</i> and take no further
action; otherwise, set <i>dirObject</i> to <i>rObject</i>.</p>
</li><li><p><span><span>  </span></span>Set
the <i>pSecurityDescriptor</i> to <i>dirObject</i>.<b>Security</b>.</p>
</li></ul></li><li><p><span><span> 
</span></span>If the <i>dwObjectType</i> is MQDS_MACHINE: </p>
<ul><li><p><span><span>  </span></span>If <i>SecurityInformation</i>
is MQDS_KEYX_PUBLIC_KEY (0x40000000):</p>
<ul><li><p><span><span> 
</span></span>Generate the Get Directory Object (section 3.1.6.12)
event with the arguments set to MQDS_MACHINE, <i>pwcsPathName</i>, and NULL
respectively. If <i>rStatus</i> returned by the event is not MQ_OK, return <i>rStatus</i>
and take no further action; otherwise, set <i>dirObject</i> to <i>rObject</i>.</p>
</li><li><p><span><span> 
</span></span>Construct a buffer that consists of a BLOBHEADER structure
followed by an <b>RSAPUBKEY</b> structure. The BLOBHEADER MUST be initialized
as specified in section 2.2.18, and the <b>aiKeyAlg</b> field set to
CALG_RSA_KEYX. The <b>RSAPUBKEY</b> structure is obtained from the <i>dirObject</i>.<b>PublicEncryptionKeyList</b>
attribute by extracting the <b>aBuf</b> field of the first <a href="../ms-mqmq/686a51fe-40cf-49d6-b4b0-576b1a5e59c2" data-linktype="relative-path">MQDSPUBLICKEY</a>
structure (<a href="../ms-mqmq/b7cc2590-a617-45df-b6a3-1f31102b36fb" data-linktype="relative-path">[MS-MQMQ]</a>
section 2.2.1) in the <b>aPublicKeys</b> field of the <a href="../ms-mqmq/efa3e184-525e-47da-bf7f-4479444f33df" data-linktype="relative-path">MQDSPUBLICKEYS</a>
structure ([MS-MQMQ] section 2.2.2).</p>
</li><li><p><span><span> 
</span></span>Set the <i>pSecurityDescriptor</i> to point to the buffer
constructed in the preceding step.</p>
</li></ul></li><li><p><span><span>  </span></span>If <i>SecurityInformation</i>
is MQDS_SIGN_PUBLIC_KEY (0x80000000):</p>
<ul><li><p><span><span> 
</span></span>Generate the Get Directory Object event with the arguments set to
MQDS_MACHINE, <i>pwcsPathName</i>, and NULL respectively. If <i>rStatus</i>
returned by the event is not MQ_OK, return <i>rStatus</i> and take no further
action; otherwise, set <i>dirObject</i> to <i>rObject</i>.</p>
</li><li><p><span><span> 
</span></span>Construct a buffer that consists of a BLOBHEADER structure
followed by an <b>RSAPUBKEY</b> structure. The BLOBHEADER MUST be initialized
as specified in section 2.2.18, and the <b>aiKeyAlg</b> field set to
CALG_RSA_SIGN. The <b>RSAPUBKEY</b> structure is obtained from the <i>dirObject</i>.<b>PublicSigningKeyList</b>
attribute by extracting the <b>aBuf</b> field of the first MQDSPUBLICKEY
structure in the <b>aPublicKeys</b> field of the MQDSPUBLICKEYS structure.</p>
</li><li><p><span><span> 
</span></span>Set the <i>pSecurityDescriptor</i> to point to the buffer
constructed in the preceding step.</p>
</li></ul></li><li><p><span><span>  </span></span>If <i>SecurityInformation</i>
is a bitwise OR of any combination of OWNER_SECURITY_INFORMATION,
GROUP_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION, and
DACL_SECURITY_INFORMATION:</p>
<ul><li><p><span><span> 
</span></span>Generate the Get Directory Object event with the arguments set to
MQDS_MACHINE, <i>pwcsPathName</i>, and NULL respectively. If <i>rStatus</i>
returned by the event is not MQ_OK, return <i>rStatus</i> and take no further
action; otherwise, set <i>dirObject</i> to <i>rObject</i>.</p>
</li><li><p><span><span> 
</span></span>Set the <i>pSecurityDescriptor</i> to <i>dirObject</i>.<b>Security</b>.</p>
</li></ul></li></ul></li><li><p><span><span> 
</span></span>If the <i>dwObjectType</i> is MQDS_SITE:</p>
<ul><li><p><span><span>  </span></span>If <i>SecurityInformation</i>
is MQDS_SIGN_PUBLIC_KEY (0x80000000):</p>
<ul><li><p><span><span> 
</span></span>Generate the Get Directory Object event with the arguments set to
MQDS_SITE, <i>pwcsPathName</i>, and NULL respectively. If <i>rStatus</i>
returned by the event is not MQ_OK, return <i>rStatus</i> and take no further
action; otherwise, set <i>dirObject</i> to <i>rObject</i>.</p>
</li><li><p><span><span> 
</span></span>Construct a buffer that consists of a BLOBHEADER structure
followed by an <b>RSAPUBKEY</b> structure. The BLOBHEADER MUST be initialized
as specified in section 2.2.18, and the <b>aiKeyAlg</b> field set to
CALG_RSA_SIGN. The <b>RSAPUBKEY</b> structure is obtained from the <i>dirObject</i>.<b>PublicSigningKeyList</b>
attribute by extracting the <b>aBuf</b> field of the first MQDSPUBLICKEY
structure in the <b>aPublicKeys</b> field of the MQDSPUBLICKEYS structure.</p>
</li><li><p><span><span> 
</span></span>Set the <i>pSecurityDescriptor</i> to point to the buffer
constructed in the preceding step.</p>
</li></ul></li><li><p><span><span>  </span></span>If <i>SecurityInformation</i>
is a bitwise OR of any combination of OWNER_SECURITY_INFORMATION,
GROUP_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION, and
DACL_SECURITY_INFORMATION:</p>
<ul><li><p><span><span> 
</span></span>Generate the Get Directory Object event with the arguments set to
MQDS_SITE, <i>pwcsPathName</i>, and NULL respectively. If <i>rStatus</i>
returned by the event is not MQ_OK, return <i>rStatus</i> and take no further
action; otherwise, set <i>dirObject</i> to <i>rObject</i>.</p>
</li><li><p><span><span> 
</span></span>Set the <i>pSecurityDescriptor</i> to <i>dirObject</i>.<b>Security</b>.</p>
</li></ul></li></ul></li><li><p><span><span> 
</span></span>If the <i>dwObjectType</i> is MQDS_CN and <i>SecurityInformation</i>
is a bitwise OR of any combination of OWNER_SECURITY_INFORMATION,
GROUP_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION, and
DACL_SECURITY_INFORMATION:</p>
<ul><li><p><span><span>  </span></span>Generate
the Get Directory Object event with the arguments set to MQDS_CN, <i>pwcsPathName</i>,
and NULL respectively. If <i>rStatus</i> returned by the event is not MQ_OK,
return <i>rStatus</i> and take no further action; otherwise, set <i>dirObject</i>
to <i>rObject</i>.</p>
</li><li><p><span><span>  </span></span>Set
the <i>pSecurityDescriptor</i> to <i>dirObject</i>.<b>Security</b>.</p>
</li></ul></li><li><p><span><span> 
</span></span>If the <i>dwObjectType</i> is MQDS_ENTERPRISE and <i>SecurityInformation</i>
is a bitwise OR of any combination of OWNER_SECURITY_INFORMATION,
GROUP_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION, and
DACL_SECURITY_INFORMATION:</p>
<ul><li><p><span><span>  </span></span>Generate
the Get Directory Object event with the arguments set to MQDS_ENTERPRISE, <i>pwcsPathName</i>,
and NULL respectively. If <i>rStatus</i> returned by the event is not MQ_OK,
return <i>rStatus</i> and take no further action; otherwise, set <i>dirObject</i>
to <i>rObject</i>.</p>
</li><li><p><span><span>  </span></span>Set
the <i>pSecurityDescriptor</i> to <i>dirObject</i>.<b>Security</b>.</p>
</li></ul></li><li><p><span><span> 
</span></span>If the <i>SecurityInformation</i> parameter is equal to
MQDS_SIGN_PUBLIC_KEY (0x80000000), the only allowed values for the <i>dwObjectType</i>
parameter are MQDS_MACHINE and MQDS_SITE. If the <i>dwObjectType</i> parameter
is any other value, the server SHOULD throw an RPC exception with
MQ_ERROR_INVALID_PARAMETER (0xC00E0006) as the exception code.<a id="Appendix_A_Target_56"></a><a aria-label="Product behavior note 56" href="9c868bc8-426a-4e5f-8b45-cee7d49c3d10#Appendix_A_56" data-linktype="relative-path">&lt;56&gt;</a></p>
</li><li><p><span><span> 
</span></span>If the <i>SecurityInformation</i> parameter is equal to
MQDS_KEYX_PUBLIC_KEY (0x40000000), the only allowed value for the <i>dwObjectType</i>
parameter is MQDS_MACHINE.</p>
</li><li><p><span><span> 
</span></span>If the <i>dwObjectType</i> parameter is equal to MQDS_USER or
MQDS_ROUTINGLINK, the server SHOULD return MQDS_WRONG_OBJ_TYPE (0xC00E0506).<a id="Appendix_A_Target_57"></a><a aria-label="Product behavior note 57" href="9c868bc8-426a-4e5f-8b45-cee7d49c3d10#Appendix_A_57" data-linktype="relative-path">&lt;57&gt;</a></p>
</li><li><p><span><span> 
</span></span>If the <i>dwObjectType</i> parameter is any other value, the
server SHOULD throw an RPC exception with MQ_ERROR_INVALID_PARAMETER
(0xC00E0006) as the exception code.<a id="Appendix_A_Target_58"></a><a aria-label="Product behavior note 58" href="9c868bc8-426a-4e5f-8b45-cee7d49c3d10#Appendix_A_58" data-linktype="relative-path">&lt;58&gt;</a></p>
</li><li><p><span><span> 
</span></span>If the requested security descriptor or public key is larger than
<i>nLength</i>, the server MUST set the <i>lpnLengthNeeded</i> parameter to the
size needed for the requested security descriptor or public key, and return
MQ_ERROR_SECURITY_DESCRIPTOR_TOO_SMALL (0xC00E0023).</p>
</li><li><p><span><span> 
</span></span>Construct the <i>pbServerSignature</i> by creating a hash by
using the <a href="993fa29f-3deb-494f-b4b4-492ee945735f#gt_1535fdac-8d46-4605-96af-252907c4a593" data-linktype="relative-path">MD5</a> algorithm,
as specified in <a href="https://go.microsoft.com/fwlink/?LinkId=90275" data-linktype="external">[RFC1321]</a>,
and sealing it, as defined by the following pseudocode: </p>
<div><pre> Initialize an MD5 hash context
  
 Add to the hash context the DWORD data value 0x00000001.
  
 Add to the hash context the byte array pSecurityDescriptor. The data
        length is defined by nLength.
  
 Call GSS_Wrap using the output context handle from the GSS
                     security context and the computed MD5 hash
  
 Set pbServerSignature to the wrapped MD5 hash
 Set *pdwServerSignatureSize to the size of the wrapped MD5 hash
</pre></div>
</li><li><p><span><span> 
</span></span>Set <i>pdwServerSignatureSize</i> to the actual length in bytes
of the server signature on output. If the server signature is larger than the
supplied buffer, the server MUST return MQ_ERROR_USER_BUFFER_TOO_SMALL
(0xC00E0028).</p>
</li></ul></div>