3.1.4.7.3 LsarSetTrustedDomainInfo (Opnum 40)

  • Article

The LsarSetTrustedDomainInfo method is invoked to set information on a trusted domain object. In some cases, if the trusted domain object does not exist, it will be created.

 NTSTATUS LsarSetTrustedDomainInfo(
   [in] LSAPR_HANDLE PolicyHandle,
   [in] PRPC_SID TrustedDomainSid,
   [in] TRUSTED_INFORMATION_CLASS InformationClass,
   [in, switch_is(InformationClass)] 
     PLSAPR_TRUSTED_DOMAIN_INFO TrustedDomainInformation
 );

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

TrustedDomainSid: A SID of the trusted domain object to be modified.

InformationClass: Identifies the type of information to be set on the trusted domain object.

TrustedDomainInformation: Information to be set on the trusted domain object.

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 or more of the supplied parameters was invalid.

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 method is similar to the LsarSetInformationTrustedDomain method, with some important differences. For one, this method takes a policy object handle instead of a trusted domain object handle. Another important distinction is that for some information classes this method, unlike LsarSetInformationTrustedDomain, will create a trusted domain object if one does not exist already.

This message takes four arguments:

PolicyHandle: An open handle to the policy object. The access rights required to perform the operation depend on the value of the InformationClass parameter. The access bits required for each information class are specified in section 3.1.4.7.14. 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. If the server is a read-only domain controller, it MUST return an error.<97>

TrustedDomainSid: A SID of the trusted domain object to modify. The server MUST verify that the caller has supplied a valid domain SID for this parameter and fail the request with STATUS_INVALID_PARAMETER if the check fails.

InformationClass: A value from the TRUSTED_INFORMATION_CLASS enumeration that specifies which type of information the caller is setting. Not all InformationClass values are valid. The valid InformationClass values for this method are as follows:

  • TrustedDomainNameInformation: The server MUST act as if an LsarCreateTrustedDomain message came in with its TrustedDomainInformation.Name parameter as the name passed in the TrustedDomainInformation parameter, its TrustedDomainInformation.Sid parameter as the SID passed in the TrustedDomainSid parameter, and its DesiredAccess parameter set to zero.

  • TrustedPosixOffsetInformation: The server MUST verify that a trusted domain object with this SID exists in its policy database. If the object does not exist, the call MUST fail with STATUS_NO_SUCH_DOMAIN. Otherwise, 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_POSIX. There is no method-specific portion of this check.

    Then the server MUST act as if an LsarSetInformationTrustedDomain message is being processed.

The server MAY support the following InformationClass values.<98> If the server does not support these values, it MUST return STATUS_INVALID_PARAMETER. If the server supports these values, it MUST perform the corresponding operations:

  • TrustedDomainInformationEx: The server MUST check that a trusted domain object with this SID exists in its policy database. If the object does not exist, the server MUST create a new trusted domain object using the same processing rules as LsarCreateTrustedDomainEx2, and using the following parameters for the LsarCreateTrustedDomainEx2 processing rules:

    • PolicyHandle set to the same PolicyHandle in the original message.

    • TrustedDomainInformation set to the same TrustedDomainInformation in the original message.

    • AuthenticationInformation set to NULL.

    • DesiredAccess set to zero.

    If the object does exist, the server MUST set the trusted domain information using the same processing rules as LsarSetInformationTrustedDomain, and using the following parameters for the LsarSetInformationTrustedDomain processing rules:

    • TrustDomainHandle set to the handle to the trusted domain object.

    • InformationClass set to the same InformationClass in the original message.

    • TrustedDomainInformation set to the same TrustedDomainInformation in the original message.

  • TrustedPasswordInformation: The server MUST verify that a trusted domain object with this SID exists in its policy database. If the object does not exist, the call MUST fail with STATUS_NO_SUCH_DOMAIN. Otherwise, the server MUST open the secret object, as defined in section 3.1.1.4, (or create a secret object, if one does not already exist) with "Name" set to "G$$<Trusted Domain Name>". The server MUST then set "Old Value" of the secret object to the "OldPassword" value in TrustedDomainInformation and set "New Value" of the secret object to the "Password" value in TrustedDomainInformation, similar to the processing when an LsarSetSecret request has been made.

The server MUST return STATUS_INVALID_PARAMETER for all other InformationClass arguments.

TrustedDomainInformation: Contains the data supplied by the caller to be set on the trusted domain object.