3.1.4.7.1 LsarOpenTrustedDomain (Opnum 25)

The LsarOpenTrustedDomain method is invoked to obtain a handle to a trusted domain object.

 NTSTATUS LsarOpenTrustedDomain(
   [in] LSAPR_HANDLE PolicyHandle,
   [in] PRPC_SID TrustedDomainSid,
   [in] ACCESS_MASK DesiredAccess,
   [out] LSAPR_HANDLE* TrustedDomainHandle
 );

PolicyHandle: An RPC context handle obtained from either LsarOpenPolicy or LsarOpenPolicy2.

TrustedDomainSid: A security identifier of the trusted domain that is being opened.

DesiredAccess: A bitmask of access rights to open the object with.

TrustedDomainHandle: Used to return the trusted domain object handle.

Return Values: The following is a summary of the return values that an implementation MUST return, as specified by the message processing that follows.

Return value/code

Description

0x00000000

STATUS_SUCCESS

The request was successfully completed.

0xC0000022

STATUS_ACCESS_DENIED

The caller does not have the permissions to perform this operation.

0xC000000D

STATUS_INVALID_PARAMETER

One of the supplied parameters is invalid. For instance, this can happen if the security identifier TrustedDomainSid is not a valid domain security identifier. Section 3.1.4.10 specifies data validation rules, including what constitutes a valid domain security identifier.

0xC0000008

STATUS_INVALID_HANDLE

PolicyHandle is not a valid handle.

0xC00000DF

STATUS_NO_SUCH_DOMAIN

The specified trusted domain object does not exist.

0xC00002B1

STATUS_DIRECTORY_SERVICE_REQUIRED

The Active Directory service was not available on the server.

Processing:

If Active Directory is not running on this machine, the server MUST return STATUS_DIRECTORY_SERVICE_REQUIRED.

This message takes four arguments:

PolicyHandle: An open handle to the policy object. If the handle is not a valid context handle to the policy object or PolicyHandle.HandleType does not equal "Policy", the server MUST return STATUS_INVALID_HANDLE. PolicyHandle.GrantedAccess MUST NOT be considered for this call because the access check MUST happen on the trusted domain object.

TrustedDomainSid: A SID of the trusted domain object. The server MUST verify that the SID is a valid domain SID and reject the request with STATUS_INVALID_PARAMETER otherwise. If the trusted domain object with this SID does not exist, the server MUST fail the request with STATUS_NO_SUCH_DOMAIN error code.

DesiredAccess: A bitmask specifying the type of access the caller attempts to obtain from the trusted domain object, which is access-checked according to section 3.1.4.2.1. There is no method-specific portion of the check. The valid trusted-domain-rights bits are specified in section 2.2.1.1.5, and the security descriptor is specified in section 3.1.1.5.

TrustedDomainHandle: If the request is successful, this parameter is used to return a handle (section 3.1.1.7) to the opened trusted domain object with its fields initialized as follows:<95><96>

  • LsaContextHandle.HandleType = "Trusted Domain"

  • LsaContextHandle.Object = the trusted domain object

  • LsaContextHandle.GrantedAccess = as specified in section 3.1.4.2.1