Share via

3.1.4.7.19 LsarSetForestTrustInformation2 (Opnum 133)

  • Article

The LsarSetForestTrustInformation2 method is invoked to establish a trust relationship with another forest by attaching a set of records known as forest trust information to the trusted domain object.<111>

 NTSTATUS LsarSetForestTrustInformation2(
   [in] LSAPR_HANDLE PolicyHandle,
   [in] PLSA_UNICODE_STRING TrustedDomainName,
   [in] LSA_FOREST_TRUST_RECORD_TYPE HighestRecordType,
   [in] PLSA_FOREST_TRUST_INFORMATION2 ForestTrustInfo2,
   [in] unsigned char CheckOnly,
   [out] PLSA_FOREST_TRUST_COLLISION_INFORMATION* CollisionInfo
 );

PolicyHandle: An RPC context handle obtained from either the LsarOpenPolicy (section 3.1.4.4.2) or LsarOpenPolicy2 (section 3.1.4.4.1) method.

TrustedDomainName: The name of the trusted domain object on which to set the forest trust information.

HighestRecordType: The highest ordinal forest trust record type that the caller understands.

ForestTrustInfo2: The forest trust information that the caller is trying to set on the trusted domain object.

CheckOnly: If not 0, the operation is read-only and does not alter the state of the server’s database.

CollisionInfo: Used to return information about collisions between different sets of forest trust information in the server’s database.

Return Values: The following is a summary of the return values that an implementation MUST return, as appropriate, 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.

0xC00000DD

STATUS_INVALID_DOMAIN_STATE

The domain is not the root domain of the forest, or the forest is not at DS_BEHAVIOR_WIN2003 forest functional level.

0xC00000DE

STATUS_INVALID_DOMAIN_ROLE

The server is not the primary domain controller

0xC00000DF

STATUS_NO_SUCH_DOMAIN

The trusted domain object with the name in the TrustedDomainName parameter does not exist.

0xC0000008

STATUS_INVALID_HANDLE

PolicyHandle is not a valid handle.

0xC000000D

STATUS_INVALID_PARAMETER

Some of the parameters supplied were invalid.

Processing instructions:

This message takes six arguments:

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

TrustedDomainName: The name of the trusted domain object on which to set forest trust information.

The server MUST return STATUS_INVALID_DOMAIN_STATE if any of the following conditions are  TRUE.

  • The DnsForestName and DnsDomainName fields in DNS Domain Information (section 3.1.1.1) do not contain the same value.

  • Active Directory is not running on this machine.

The server MUST return STATUS_INVALID_DOMAIN_ROLE if the IsEffectiveRoleOwner function specified in [MS-ADTS] section 3.1.1.5.1.8 returns FALSE with the roleObject parameter set to default NC.

If a trusted domain object named TrustedDomainName does not exist, the server MUST return STATUS_NO_SUCH_DOMAIN.

The server MUST verify that the caller has access to the trusted domain object as specified in section 3.1.4.2.1 with DesiredAccess set to TRUSTED_SET_AUTH. There is no method-specific portion of this check.

The server MUST also make sure that the trust attributes associated with the trusted domain object referenced by the TrustedDomainName parameter has the TRUST_ATTRIBUTE_FOREST_TRANSITIVE set. If the attribute is not present, the server MUST return STATUS_INVALID_PARAMETER.

HighestRecordType: The caller sets this argument to the highest LSA_FOREST_TRUST_RECORD_TYPE enumeration value (section 2.2.7.22) recognized by the caller. If this argument is greater in value than the highest record type recognized by the server, the server MUST return STATUS_INVALID_PARAMETER.

ForestTrustInfo: A collection of forest trust records identifying the topology of the trusted forest. The server MUST verify that the forest trust information supplied by the caller is valid by performing a consistency check, as specified in [MS-ADTS] section 6.1.6. Note that "consistent" does not necessarily mean "collision-free". The method for determining collisions is specified in section 3.1.4.7.16.1.

ForestTrustScannerInfo records must contain DnsName and NetbiosName data but are not otherwise validated. No collision name checking is done on ForestTrustScannerInfo records.

CheckOnly: Perform a read-only probing operation. The results will not be persisted in the Local Security Authority (Domain Policy) database, but the set of collision records returned in CollisionInfo will be accurate as though the information was persisted.

CollisionInfo: A list of collision records. The request is considered successful even if a non-empty set of collisions is returned. The rules for generating collision information are specified in section 3.1.4.7.16.1.

The server MUST store the generated ForestTrustInfo in the Forest Trust Information attribute specified in section 3.1.1.5.