3.1.4.5 LsarLookupNames4 (Opnum 77)

  • Article

The LsarLookupNames4 method translates a batch of security principal names to their SID form. It also returns the domains of which these security principals are a part.

 NTSTATUS LsarLookupNames4(
   [in] handle_t RpcHandle,
   [in, range(0,1000)] unsigned long Count,
   [in, size_is(Count)] PRPC_UNICODE_STRING Names,
   [out] PLSAPR_REFERENCED_DOMAIN_LIST* ReferencedDomains,
   [in, out] PLSAPR_TRANSLATED_SIDS_EX2 TranslatedSids,
   [in] LSAP_LOOKUP_LEVEL LookupLevel,
   [in, out] unsigned long* MappedCount,
   [in] unsigned long LookupOptions,
   [in] unsigned long ClientRevision
 );

RpcHandle: This value is used by RPC internally and is not transmitted over the network, as specified in [C706]. This handle can be obtained by calling RPC runtime binding routines. For more information, see [MSDN-RPCDB].

Count: Number of security principal names to look up.<24>

Names: Contains the security principal names to translate. The RPC_UNICODE_STRING structure is defined in [MS-DTYP] section 2.3.10.

The following name forms MUST be supported:

  • User principal names (UPNs), such as user_name@example.example.com.

  • Fully qualified account names based on either DNS or NetBIOS names. For example: example.example.com\user_name or example\user_name, where the generalized form is domain\user account name, and domain is either the fully qualified DNS name or the NetBIOS name of the trusted domain.

  • Unqualified or isolated names, such as user_name.

The comparisons used by the RPC server MUST NOT be case-sensitive, so case for inputs is not important.

ReferencedDomains: On successful return, contains the domain information for the domain to which each security principal belongs. The domain information includes a NetBIOS domain name and a domain SID for each entry in the list.

TranslatedSids: On successful return, contains the corresponding SID form for security principal names in the Names parameter. It MUST be ignored on input.

LookupLevel: Specifies what scopes are to be used during translation, as specified in section 2.2.16.

MappedCount: On successful return, contains the number of names that are translated completely to the SID form. This parameter is left as an input parameter for backward compatibility and has no effect on message processing in any environment. It MUST be ignored on input.

LookupOptions: Flags specified by the caller that control the lookup operation. The value MUST be one of the following.

Value

Meaning

0x00000000

Isolated names are searched for even when they are not on the local computer.

0x80000000

Isolated names (except for user principal names (UPNs)) are searched for only on the local account database. UPNs are not searched for in any of the views.

ClientRevision: Version of the client, which implies the client's capabilities. The value MUST be one of the following.<25>

Value

Meaning

0x00000001

The client does not understand DNS domain names and is not aware that it might be part of a forest.

0x00000002

The client understands DNS domain names and is aware that it might be part of a forest.

Error codes returned can include STATUS_TRUSTED_DOMAIN_FAILURE and STATUS_TRUSTED_RELATIONSHIP_FAILURE, which are not returned for ClientRevision of 0x00000001. For more information on error codes, see [MS-ERREF].

Values smaller than 0x00000002 SHOULD be assumed to be 0x00000001, and other values SHOULD be assumed to be 0x00000002.

Return Values: The following table contains a summary of the return values that an implementation MUST return, as specified by the message processing shown after the table.

Return value/code

Description

0x00000000

STATUS_SUCCESS

The request was successfully completed.

0x00000107

STATUS_SOME_NOT_MAPPED

Some of the information to be translated has not been translated.

0xC00000DC

STATUS_INVALID_SERVER_STATE

The RPC server is not a domain controller.

0xC0000022

STATUS_ACCESS_DENIED

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

0xC000000D

STATUS_INVALID_PARAMETER

One of the supplied parameters was invalid.

0xC0000073

STATUS_NONE_MAPPED

None of the information to be translated has been translated.

This message is valid only if the RPC server is a domain controller. The RPC server MUST return STATUS_INVALID_SERVER_STATE in the return value if it is not a domain controller.

The RPC server MUST ensure that one of the following conditions is true:

  1. The RPC_C_AUTHN_NETLOGON security provider (as specified in [MS-RPCE] section 2.2.1.1.7) and at least RPC_C_AUTHN_LEVEL_PKT_INTEGRITY authentication level (as specified in [MS-RPCE] section 2.2.1.1.8) are used in this RPC message.

  2. The RPC client token contains one of the following well-known SID types - DOMAIN_GROUP_RID_COMPUTERS, DOMAIN_GROUP_RID_CONTROLLERS, DOMAIN_GROUP_RID_READONLY_CONTROLLERS (as specified in [MS-SAMR] section 2.2.1.14).<26>

Otherwise, the RPC server MUST return STATUS_ACCESS_DENIED.

The RPC server MUST check each element in the Names parameter for validity, as described for the RPC_UNICODE_STRING structure in [MS-DTYP] section 2.3.10. If validation fails, the RPC server MUST return STATUS_INVALID_PARAMETER.

The TranslatedSids and MappedCount parameters are left as input parameters for backward compatibility and have no effect on message processing in any environment. They MUST be ignored on input.

LookupOptions MUST NOT contain 0x80000000 unless LookupLevel is LsapLookupWksta. If this fails, the RPC server MUST return STATUS_INVALID_PARAMETER.

A name is interchangeably called a "qualified" or "composite" name if the name has a backslash ('\') character in it. The string before the backslash is assumed to be the domain name, and the string after the backslash is the name to be resolved within that domain. If the name does not contain a backslash character, it is called an "isolated" name. An isolated name can be in single-label form, as in "John", or can be in user-principal-name form, as in "John@example.com".

The RPC server MUST match a name with a row in the view by using the following rules:

  • If the name is a qualified name, the domain name MUST match the Domain NetBIOS Name column or Domain DNS Name column, and the name MUST match the Security Principal Name column. Note that there cannot be multiple matches in this case (see section 3.1.1.1). A domain name match against the Domain DNS Name column MUST NOT be performed if ClientRevision is 0x00000001 and the machine is joined to a mixed mode domain, as specified in [MS-ADTS] section 6.1.4.1.

  • If the name is an isolated name:

    • If in single-label form, the name MUST match the Security Principal Name column or the Additional Security Principal Name column.

      • If there are multiple matches due to a search in multiple domains, which can happen in Forest Views, any one of the matches MAY be used to satisfy the request, as long as a consistent search order is followed.

    • If in user principal name form, the name SHOULD<27> match the User Principal Name column or the Default User Principal Names column.

      • If there are multiple matches on the User Principal Name attribute, the match MUST fail.

      • If there is one match with User Principal Name and one match with Default User Principal Names, the match with the User Principal Name attribute MUST take precedence.

      • There cannot be multiple Default User Principal Names matches; see section 3.1.1.1.

The search scope is defined by the LookupLevel parameter. The RPC server MUST search only the scopes that are defined by the LookupLevel parameter and MUST NOT return matches defined outside that scope. The scopes to search when processing this message are specified in section 2.2.16.

When a name is matched in the database, or when the domain name of a composite name is matched in the database, the ReferencedDomains parameter MUST be searched for an entry that is identical to the following: The Name field contains the value from the Domain NetBIOS Name column, and the Sid field contains the value from the Domain SID column. If there is no such entry, a new entry with the Name field containing the value of the Domain NetBIOS Name and the Sid field containing the value of the Domain SID MUST be created and added to the ReferencedDomains list.

Output parameters MUST be updated using the following information:

  1. For a successful search, the corresponding TranslatedSids entry MUST be updated as follows:

    • Use: Security Principal Type column

    • Sid: Security Principal SID column

    • Flags:

      • 0x00000001: If the search is not satisfied by matching against the Security Principal Name column. Also see the paragraph after step 3.

      • 0x00000004: If the search is satisfied by a comparison that uses the view specified in section 3.1.1.1.2, Configurable Translation Database and Corresponding View. Also see the paragraph after step 3.

    • DomainIndex: Index of the domain in the ReferencedDomains parameter.

  2. If a match cannot be found for a name, the corresponding TranslatedSids entry MUST be updated with:

    • Use: SidTypeUnknown

    • Sid: NULL

    • Flags: 0x00000000 (also see the paragraph after step 3)

    • DomainIndex: -1

  3. If a match cannot be found for a composite name, but the domain name within the composite name is found, the corresponding TranslatedSids entry MUST be updated with:

    • Use: SidTypeUnknown

    • Sid: NULL

    • Flags: 0x00000000 (also see the following paragraph)

    • DomainIndex: Index of the domain in the ReferencedDomains parameter.

In all preceding cases, the Flags field MUST contain 0x00000002 when:

  • LookupLevel is LsapLookupWksta, LsapLookupPDC, LsapLookupGC, LsapLookupXForestReferral, or LsapLookupXForestResolve, and

  • The IsDomainNameInTrustedForest algorithm defined in [MS-DRSR] section 5.64.2 (Determining If a Name Is in a Trusted Forest), given the domain name, returns true, or the IsUPNInTrustedForest algorithm defined in [MS-DRSR] section 5.109, given the full name to be translated, returns true.

The return value MUST be set to STATUS_SUCCESS if all names are translated correctly.

If some names are translated correctly but some are not, the return value MUST be set to STATUS_SOME_NOT_MAPPED.

If none of the names are translated correctly, the return value SHOULD<28> be set to STATUS_NONE_MAPPED.

If LookupLevel is LsapLookupWksta, and the return code can be identified as an error value (that is, less than 0) other than STATUS_NONE_MAPPED, ReferencedDomains and the Sids field in the TranslatedSids structure MUST NOT be returned.