Edit

Share via

LsaLookupSids function (ntsecapi.h)

  • Article

[LsaLookupSids is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions. Instead, use LsaLookupSids2.]

The LsaLookupSids function looks up the names that correspond to an array of security identifiers (SIDs). If LsaLookupSids cannot find a name that corresponds to a SID, the function returns the SID in character form.

Syntax

NTSTATUS LsaLookupSids(
  [in]  LSA_HANDLE                  PolicyHandle,
  [in]  ULONG                       Count,
  [in]  PSID                        *Sids,
  [out] PLSA_REFERENCED_DOMAIN_LIST *ReferencedDomains,
  [out] PLSA_TRANSLATED_NAME        *Names
);

Parameters

[in] PolicyHandle

A handle to a Policy object. This handle must have the POLICY_LOOKUP_NAMES access right. For more information, see Opening a Policy Object Handle.

[in] Count

Specifies the number of SIDs in the Sids array. This is also the number of entries returned in the Names array. This value must be less than or equal to 20480.

[in] Sids

Pointer to an array of SID pointers to look up. The SIDs can be well-known SIDs, user, group, or local group account SIDs, or domain SIDs.

[out] ReferencedDomains

Receives a pointer to a pointer to a LSA_REFERENCED_DOMAIN_LIST structure. The Domains member of this structure is an array that contains an entry for each domain in which a SID was found. The entry for each domain contains the SID and flat name of the domain. For Windows domains, the flat name is the NetBIOS name. For links with non–Windows domains, the flat name is the identifying name of that domain, or it is NULL.

When you no longer need the information, pass the returned pointer to LsaFreeMemory. This memory must be freed even when the function fails with the either of the error codes STATUS_NONE_MAPPED or STATUS_SOME_NOT_MAPPED

[out] Names

Receives a pointer to an array of LSA_TRANSLATED_NAME structures. Each entry in the Names array contains the name information for the corresponding entry in the Sids array. For account SIDs, the Name member of each structure contains the isolated name of the account. For domain SIDs, the Name member is not valid.

The DomainIndex member of each entry in the Names array is the index of an entry in the Domains array returned in the ReferencedDomains parameter. The index identifies the Domains array for the domain in which the SID was found.

When you no longer need the information, pass the returned pointer to LsaFreeMemory. This memory must be freed even when the function fails with the either of the error codes STATUS_NONE_MAPPED or STATUS_SOME_NOT_MAPPED

Return value

If the function succeeds, the return value is one of the following NTSTATUS values.

Return code Description
STATUS_SOME_NOT_MAPPED
 Some of the SIDs could not be translated. This is an informational-level return value.
STATUS_SUCCESS
 All of the SIDs were found and successfully translated.
 

If the function fails, the return value is an NTSTATUS code, which can be one of the following values or one of the LSA Policy Function Return Values.

Return code Description
STATUS_NONE_MAPPED
 None of the SIDs were translated. This is an error-level return value.
STATUS_TOO_MANY_SIDS
 The Sids array parameter was too large.
 

You can use the LsaNtStatusToWinError function to convert the NTSTATUS code to a Windows error code.

Remarks

For account SIDs, the string returned in the Name member is the isolated name of the account (for example, user_name). If you need the composite name of the account (for example, Acctg\user_name), get the domain name from the ReferencedDomains buffer and append a backslash and the isolated name.

If the LsaLookupSids function cannot translate a SID, the function uses the following algorithm:

  1. If the SID's domain is known, the ReferencedDomains buffer contains an entry for the domain, and the string returned in the Names parameter is a Unicode representation of the account's relative identifier (RID) from the SID.
  2. If the SID's domain is not known, the string returned in the Names parameter is a Unicode representation of the entire SID, and there is no domain record for this SID in the ReferencedDomains buffer.
In addition to looking up SIDs for local accounts, local domain accounts, and explicitly trusted domain accounts, LsaLookupSids can look up SIDs for any account in any domain in the Windows forest, including SIDs that appear only in the SIDhistory field of an account in the forest. The SIDhistory field stores the former SIDs of an account that has been moved from another domain. To perform these searches, the function queries the global catalog of the forest.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header ntsecapi.h
Library Advapi32.lib
DLL Advapi32.dll

See also

LSA_REFERENCED_DOMAIN_LIST

LSA_TRANSLATED_NAME

LsaOpenPolicy