3.1.4.12 S_DSGetObjectSecurityGuid (Opnum 13)

  • Article

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

 HRESULT S_DSGetObjectSecurityGuid(
   [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] 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 specified in section 2.2.8.

pGuid:  MUST be set by the client to a pointer to the GUID of the object for which 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<59> contain a pointer to a BLOBHEADER structure followed by an RSAPUBKEY (section 2.2.18) structure. Otherwise, this parameter contains a pointer to 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).

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 0. 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:

  • 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, 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 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.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, 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.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, 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 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.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, 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 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 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 dwObjectType parameter is any other value, the server SHOULD throw an RPC exception with MQ_ERROR_INVALID_PARAMETER (0xC00E0006) as the exception code.<60>

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

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

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