3.1.4.11 S_DSGetObjectSecurity (Opnum 4)

  • Article

This method gets security properties for a directory object specified by a directory service pathname.

 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
 );

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 retrieved. MUST be set to one of the object types defined 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: A bitwise mask of the information to be returned in the pSecurityDescriptor parameter. The bit fields are defined by the following table:

Value

Meaning

OWNER_SECURITY_INFORMATION

0x00000001

OWNER field from the security descriptor.

GROUP_SECURITY_INFORMATION

0x00000002

GROUP field from the security descriptor.

DACL_SECURITY_INFORMATION

0x00000004

Discretionary ACL field from the security descriptor.

SACL_SECURITY_INFORMATION

0x00000008

System ACL field from the security descriptor.

MQDS_SIGN_PUBLIC_KEY

0x80000000

Signing public key.

MQDS_KEYX_PUBLIC_KEY

0x40000000

Encrypting public key.

The SecurityInformation parameter MUST specify one of:

  • MQDS_SIGN_PUBLIC_KEY, or

  • MQDS_KEYX_PUBLIC_KEY, or

  • A bitwise OR of any combination of:

    • OWNER_SECURITY_INFORMATION

    • GROUP_SECURITY_INFORMATION

    • DACL_SECURITY_INFORMATION

    • SACL_SECURITY_INFORMATION

If the SecurityInformation parameter includes an invalid combination, the server MUST NOT complete the call, and MUST return an error.

pSecurityDescriptor: If the SecurityInformation parameter is MQDS_SIGN_PUBLIC_KEY or MQDS_KEYX_PUBLIC_KEY, it SHOULD<55> contain a pointer to a BLOBHEADER (section 2.2.19) structure followed by an RSAPUBKEY (section 2.2.18) structure. Otherwise, this parameter contains a security descriptor, as specified in [MS-DTYP] section 2.4.6.

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

lpnLengthNeeded:  A DWORD representing the length in bytes of the requested security descriptor or public key.

phServerAuth:  A PCONTEXT_HANDLE_SERVER_AUTH_TYPE RPC context handle acquired from the pphServerAuth parameter in a previous call to S_DSValidateServer. The server MUST use this parameter as a key to locate the GSS security context used to compute the signature returned in pbServerSignature. See section 3.1.4.2.

pbServerSignature: Contains a signed hash over the returned property values.

pdwServerSignatureSize: A DWORD that contains the maximum length in bytes of the server signature to return.

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

MQ_OK (0x00000000)

MQ_ERROR_USER_BUFFER_TOO_SMALL (0xC00E0028)

MQ_ERROR_SECURITY_DESCRIPTOR_TOO_SMALL (0xC00E0023)

MQDS_WRONG_OBJ_TYPE (0xC00E0506)

MQ_ERROR_INVALID_PARAMETER (0xC00E0006)

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

 When processing this call, the server MUST:

  • Include the information specified by the SecurityInformation parameter in the returned security descriptor.

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

  • If the dwObjectType is MQDS_QUEUE, and 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 (section 3.1.6.12) 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.

    • Set the pSecurityDescriptor to dirObject.Security.

  • If the dwObjectType is MQDS_MACHINE:

    • If SecurityInformation is MQDS_KEYX_PUBLIC_KEY (0x40000000):

      • Generate the Get Directory Object (section 3.1.6.12) 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.

      • Construct a buffer that consists of a BLOBHEADER structure followed by an RSAPUBKEY structure. The BLOBHEADER MUST be initialized as specified in section 2.2.18, and the aiKeyAlg field set to CALG_RSA_KEYX. The RSAPUBKEY structure is obtained from the dirObject.PublicEncryptionKeyList attribute by extracting the aBuf field of the first MQDSPUBLICKEY structure ([MS-MQMQ] section 2.2.1) in the aPublicKeys field of the MQDSPUBLICKEYS structure ([MS-MQMQ] section 2.2.2).

      • Set the pSecurityDescriptor to point to the buffer constructed in the preceding step.

    • If SecurityInformation is MQDS_SIGN_PUBLIC_KEY (0x80000000):

      • Generate the Get Directory Object 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.

      • Construct a buffer that consists of a BLOBHEADER structure followed by an RSAPUBKEY structure. The BLOBHEADER MUST be initialized as specified in section 2.2.18, and the aiKeyAlg field set to CALG_RSA_SIGN. The RSAPUBKEY structure is obtained from the dirObject.PublicSigningKeyList attribute by extracting the aBuf field of the first MQDSPUBLICKEY structure in the aPublicKeys field of the MQDSPUBLICKEYS structure.

      • Set the pSecurityDescriptor to point to the buffer constructed in the preceding step.

    • 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 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.

      • Set the pSecurityDescriptor to dirObject.Security.

  • If the dwObjectType is MQDS_SITE:

    • If SecurityInformation is MQDS_SIGN_PUBLIC_KEY (0x80000000):

      • Generate the Get Directory Object 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.

      • Construct a buffer that consists of a BLOBHEADER structure followed by an RSAPUBKEY structure. The BLOBHEADER MUST be initialized as specified in section 2.2.18, and the aiKeyAlg field set to CALG_RSA_SIGN. The RSAPUBKEY structure is obtained from the dirObject.PublicSigningKeyList attribute by extracting the aBuf field of the first MQDSPUBLICKEY structure in the aPublicKeys field of the MQDSPUBLICKEYS structure.

      • Set the pSecurityDescriptor to point to the buffer constructed in the preceding step.

    • 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 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.

      • Set the pSecurityDescriptor to dirObject.Security.

  • If the dwObjectType is MQDS_CN and 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 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.

    • Set the pSecurityDescriptor to dirObject.Security.

  • If the dwObjectType is MQDS_ENTERPRISE and 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 event with the arguments set to MQDS_ENTERPRISE, 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.

    • Set the pSecurityDescriptor to dirObject.Security.

  • If the SecurityInformation parameter is equal to MQDS_SIGN_PUBLIC_KEY (0x80000000), the only allowed values for the dwObjectType parameter are MQDS_MACHINE and MQDS_SITE. If the dwObjectType parameter is any other value, the server SHOULD throw an RPC exception with MQ_ERROR_INVALID_PARAMETER (0xC00E0006) as the exception code.<56>

  • If the SecurityInformation parameter is equal to MQDS_KEYX_PUBLIC_KEY (0x40000000), the only allowed value for the dwObjectType parameter is MQDS_MACHINE.

  • If the dwObjectType parameter is equal to MQDS_USER or MQDS_ROUTINGLINK, the server SHOULD return MQDS_WRONG_OBJ_TYPE (0xC00E0506).<57>

  • If the dwObjectType parameter is any other value, the server SHOULD throw an RPC exception with MQ_ERROR_INVALID_PARAMETER (0xC00E0006) as the exception code.<58>

  • If the requested security descriptor or public key is larger than nLength, the server MUST set the lpnLengthNeeded parameter to the size needed for the requested security descriptor or public key, and return MQ_ERROR_SECURITY_DESCRIPTOR_TOO_SMALL (0xC00E0023).

  • Construct the pbServerSignature by creating a hash by using the MD5 algorithm, as specified in [RFC1321], and sealing it, as defined by the following pseudocode: 

     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

  • Set pdwServerSignatureSize 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).