3.1.4.15 S_DSQMGetObjectSecurity (Opnum 21)

This method retrieves the security descriptor for a directory object specified by an object identifier.

 HRESULT S_DSQMGetObjectSecurity(
   [in] handle_t hBind,
   [in, range(1,58)] unsigned long dwObjectType,
   [in] const GUID* pGuid,
   [in] unsigned long SecurityInformation,
   [out, size_is(nLength)] unsigned char* pSecurityDescriptor,
   [in, range(0,524288)] unsigned long nLength,
   [out] unsigned long* lpnLengthNeeded,
   [in] unsigned long dwContext,
   [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 the security descriptor is retrieved. 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 to retrieve security information.

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

pSecurityDescriptor: If the SecurityInformation parameter is MQDS_SIGN_PUBLIC_KEY or MQDS_KEYX_PUBLIC_KEY, it SHOULD <73> contain a pointer to a BLOBHEADER 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 that the server MUST set to the length in bytes of the requested security descriptor or Public Key. If the requested security descriptor or Public Key is larger than nLength, the server MUST set this parameter to the size in bytes needed for the requested security descriptor or Public Key, and return MQ_ERROR_SECURITY_DESCRIPTOR_TOO_SMALL (0xC00E0023).

dwContext:  MUST be set by the client to a value that the client can use to correlate callbacks with the initial call to S_DSQMGetObjectSecurityChallengeResponceProc. The server MUST supply this value in the dwContext parameter in the related calls of the S_DSQMGetObjectSecurityChallengeResponceProc (section 3.2.4.2) callback method.

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: MUST point to the signed hash of the security descriptor.

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 0x00000000. If the method fails, the return value is an implementation-specific error code.

MQ_OK (0x00000000)

MQ_ERROR_SECURITY_DESCRIPTOR_TOO_SMALL (0xC00E0023)

MQ_ERROR_USER_BUFFER_TOO_SMALL (0xC00E0028)

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<74> invoke the S_DSQMGetObjectSecurityChallengeResponceProc (section 3.2.4.2) callback method to authenticate the client caller for this procedure.

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

    • Set the pSecurityDescriptor to dirObject.Security.

  • If the dwObjectType parameter is MQDS_MACHINE:

    • If SecurityInformation is MQDS_KEYX_PUBLIC_KEY (0x40000000):

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

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

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

      • Set the pSecurityDescriptor to dirObject.Security.

  • If the dwObjectType parameter is MQDS_SITE:

    • If SecurityInformation is MQDS_SIGN_PUBLIC_KEY (0x80000000):

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

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

      • Set the pSecurityDescriptor to dirObject.Security.

  • If the dwObjectType parameter 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, 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.

    • Set the pSecurityDescriptor to dirObject.Security.

  • If the dwObjectType parameter 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, 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.

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

  • If the dwObjectType parameter is any other value, the server MUST return MQ_ERROR_INVALID_PARAMETER (0xC00E0006).

  • 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 GSS 
           security context and the computed MD5 hash
      
     Set pbServerSignature to the wrapped MD5 hash
      
     Set *pdwServerSignatureSize to the size in bytes 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).