3.1.4.7.10 LsarCreateTrustedDomainEx2 (Opnum 59)

  • Article

The LsarCreateTrustedDomainEx2 method is invoked to create a new trusted domain object (TDO).<100>

 NTSTATUS LsarCreateTrustedDomainEx2(
   [in] LSAPR_HANDLE PolicyHandle,
   [in] PLSAPR_TRUSTED_DOMAIN_INFORMATION_EX TrustedDomainInformation,
   [in] PLSAPR_TRUSTED_DOMAIN_AUTH_INFORMATION_INTERNAL AuthenticationInformation,
   [in] ACCESS_MASK DesiredAccess,
   [out] LSAPR_HANDLE* TrustedDomainHandle
 );

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

TrustedDomainInformation: Information about the new TDO to be created.

AuthenticationInformation: Encrypted authentication information for the new TDO.

DesiredAccess: An access mask specifying desired access to the TDO handle.

TrustedDomainHandle: Used to return the handle for the newly created TDO.

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 arguments is invalid.

0xC0000300

STATUS_NOT_SUPPORTED_ON_SBS

The operation is not supported on a particular product.<101>

0xC00000DD

STATUS_INVALID_DOMAIN_STATE

The operation cannot complete in the current state of the domain.

0xC00002B1

STATUS_DIRECTORY_SERVICE_REQUIRED

The Active Directory service was not available on the server.

0xC0000078

STATUS_INVALID_SID

The security identifier of the trusted domain is not valid.

0xC00002E9

STATUS_CURRENT_DOMAIN_NOT_ALLOWED

Trust cannot be established with the current domain.

0xC0000035

STATUS_OBJECT_NAME_COLLISION

Another TDO already exists that matches some of the identifying information of the supplied information.

0xC0000008

STATUS_INVALID_HANDLE

PolicyHandle is not a valid handle.

0xC0000401

STATUS_PER_USER_TRUST_QUOTA_EXCEEDED

The caller's quota for maximum number of TDOs that can be created by control access right Create-Inbound-Trust is exceeded.

0xC0000402

STATUS_ALL_USER_TRUST_QUOTA_EXCEEDED

The combined users' quota for maximum number of TDOs that can be created by control access right Create-Inbound-Trust is exceeded.

Processing:

If Active Directory is not running on this machine, the server MUST return STATUS_DIRECTORY_SERVICE_REQUIRED.<102> If the server is a read-only domain controller, it MUST return an error.<103>

If the caller is not a member of the Domain Admins group, the server MUST return STATUS_ACCESS_DENIED for policy handle access checking.

If the TDO creation failed due to the caller not having standard access rights to create the TDO, then the server MUST check the caller's control access right (defined in [MS-ADTS] section 5.1.3.2.1). The TDO creation by control access right is allowed if:

  • The trust is an inbound-only forest trust. The server MUST return STATUS_ACCESS_DENIED if the trust to be created is not an inbound-only forest trust.

  • The caller has the control access right to create an inbound trust on the domain object.

  • The caller's quota for trust object creations has not been exceeded. If the number of TDOs that have been created by the caller through control access right Create-Inbound-Trust exceeds the value in the msDS-PerUserTrustQuota attribute of the domain NC root object, then the server MUST return STATUS_PER_USER_TRUST_QUOTA_EXCEEDED. For the syntax of the msDS-PerUserTrustQuota attribute, refer to [MS-ADA2] section 2.423.

  • The combined users' quota for trust object creations has not been exceeded. If the number of TDOs that have been created through control access right Create-Inbound-Trust exceeds the value in the msDS-AllUsersTrustQuota attribute of the domain NC root object (defined in [MS-ADTS] section 6.1.1.1.4), then the server MUST return STATUS_ALL_USER_TRUST_QUOTA_EXCEEDED. For the syntax of the msDS-AllUsersTrustQuota attribute, refer to [MS-ADA2] section 2.220.

This message takes five 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 TDO.

TrustedDomainInformation: A structure containing most components of a TDO makeup. The data provided in this parameter MUST be checked for validity in accordance with rules for TDO consistency specified in "Trust Objects" in [MS-ADTS] section 6.1.6. The server MUST reject invalid input with STATUS_INVALID_PARAMETER. The server MUST return STATUS_INVALID_DOMAIN_STATE in the following cases:

  • The TrustAttributes TRUST_ATTRIBUTE_FOREST_TRANSITIVE flag is set and the forestFunctionality specified in [MS-ADTS] section 3.1.1.3.2.27 is DS_BEHAVIOR_WIN2003 or higher.

  • The TrustAttributes TRUST_ATTRIBUTE_FOREST_TRANSITIVE flag is set and the DnsForestName and DnsDomainName fields in DNS Domain Information (see section 3.1.1.1) do not contain the same value.

  • The TrustAttributes TRUST_ATTRIBUTE_CROSS_ORGANIZATION flag is set and the forestFunctionality specified in [MS-ADTS] section 3.1.1.3.2.27 is DS_BEHAVIOR_WIN2003 or higher.

If one or more properties in TrustedDomainInformation points to the current domain (such as the domain that the server is a part of), the server MUST return STATUS_CURRENT_DOMAIN_NOT_ALLOWED. If there is another domain that claims the same properties, the server MUST return STATUS_OBJECT_NAME_COLLISION. Each field in this structure maps to a field in the TDO model, as specified in section 3.1.1.5. If the operation succeeds, the server MUST update its database with a new TDO field populated from this input parameter.

AuthenticationInformation: A structure containing an encrypted LSAPR_TRUSTED_DOMAIN_AUTH_BLOB (section 2.2.7.16) which specifies the authentication information for the trusted domain. The server first MUST decrypt this data structure using an algorithm (as specified in section 5.1.1) with the key being the session key negotiated by the transport. The server then MUST unmarshal the data inside this structure and then store it into a structure whose format is specified in section 2.2.7.11. This structure MUST then be stored on Trust Incoming and Outgoing Password properties.

DesiredAccess: A bitmask containing a set of access rights that the caller attempts to obtain from the TDO, which is access-checked as specified in section 3.1.4.2.1. Whatever the set of access rights requested by the caller, the server MUST also set the TRUSTED_SET_AUTH bit inside DesiredAccess before performing the security descriptor check. 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 newly created TDO with its fields initialized as follows:

  • LsaContextHandle.HandleType = "Trusted Domain"

  • LsaContextHandle.Object = the TDO

  • LsaContextHandle.GrantedAccess = as specified in section 3.1.4.2.1

New TDOs are always created without forest trust information. The ForestTrustInfo and ForestTrustLength fields of the TDO are thus set to NULL and 0, respectively.

If the trust being created is inbound or bidirectional as defined in the TrustDirection field of the TrustedDomainInformation parameter, then the server MUST also update its database with a new interdomain trust account populated as specified in [MS-ADTS] section 6.1.6.8.