3.1.4.9 LsarLookupSids3 (Opnum 76)

  • Article

The LsarLookupSids3 method translates a batch of security principal SIDs to their name forms. It also returns the domains that these names are a part of.

 NTSTATUS LsarLookupSids3(
   [in] handle_t RpcHandle,
   [in] PLSAPR_SID_ENUM_BUFFER SidEnumBuffer,
   [out] PLSAPR_REFERENCED_DOMAIN_LIST* ReferencedDomains,
   [in, out] PLSAPR_TRANSLATED_NAMES_EX TranslatedNames,
   [in] LSAP_LOOKUP_LEVEL LookupLevel,
   [in, out] unsigned long* MappedCount,
   [in] unsigned long LookupOptions,
   [in] unsigned long ClientRevision
 );

RpcHandle: An RPC binding handle, as described in [C706]. RPC binding handles are used by RPC internally and are not transmitted over the network.

This handle can be obtained by calling RPC runtime binding routines. For more information, see [MSDN-RPCDB].

SidEnumBuffer: Contains the SIDs to be translated. The SIDs in this structure can be that of users, groups, computers, Windows-defined well-known security principals, or domains.

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.

TranslatedNames: On successful return, contains the corresponding name forms for security principal SIDs in the SidEnumBuffer 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 their name forms. It MUST be ignored on input.

LookupOptions: Flags that control the lookup operation. This parameter is reserved for future use; it MUST be set to 0 and ignored on receipt.

ClientRevision: Version of the client, which implies the client's capabilities. For possible values and their meanings, see section 3.1.4.5.

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).<34>

Otherwise, the RPC server MUST return STATUS_ACCESS_DENIED.

The RPC server MUST check each element in the SidEnumBuffer parameter for validity, as specified in section 2.2.18, and individual elements in this structure MUST be checked for validity, as described for the SID structure in [MS-DTYP] section 2.4.2. If validation fails, the RPC server SHOULD return STATUS_INVALID_PARAMETER.

The TranslatedNames and MappedCount parameters have no effect on message processing in any environment. They MUST be ignored on input.

The RPC server search scope can change depending on the LookupLevel parameter, as specified in section 2.2.16. In the views corresponding to each LookupLevel, SIDs MUST be searched under the Security Principal SID and Security Principal SID History columns.

Output parameters MUST be updated using the following information:

  1. When a SID is found in the database, the ReferencedDomains parameter MUST be searched for an identical entry with the Name field containing the value from the Domain NetBIOS Name column and the Sid field containing 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.

    For the successful search, the corresponding TranslatedNames entry MUST be updated as follows:

    • Use: Security Principal Type column

    •  Name: Security Principal Name column

    •  Flags:

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

      • 0x00000004: If the search is satisfied by matching in Configurable Translation View (section 3.1.1.1.2). 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 SID, but the domain portion of the SID can be matched with a domain SID, the ReferencedDomains parameter MUST be searched for an identical entry with the Name field containing the value from the Domain NetBIOS Name column and the Sid field containing 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.

    The corresponding TranslatedNames entry MUST be updated by using the following view:

    • Use: SidTypeUnknown.

    • Name: Empty unless LookupLevel is LsapLookupWksta, in which case this field must contain a textual representation of the last 32 bits of the corresponding SID in hexadecimal format.

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

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

  3. Otherwise, the corresponding TranslatedNames entry MUST be updated with:

    • Use: SidTypeUnknown.

    • Name: Empty, unless LookupLevel is LsapLookupWksta. In that case, Name MUST contain the textual representation of the corresponding SID, as in step 2.

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

    • DomainIndex: -1.

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

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

  • The IsDomainSidInTrustedForest algorithm defined in [MS-DRSR] section 5.97 returns true.

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

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

If none of the SIDs are translated correctly, the return value MUST be set to STATUS_NONE_MAPPED.

If LookupLevel is LsapLookupWksta, and the return code can be identified as an error value other than STATUS_NONE_MAPPED, ReferencedDomains and the Names fields in the TranslatedNames structure MUST NOT be returned.