SecLookupAccountName function

SecLookupAccountName accepts an account as input and retrieves a security identifier (SID) for the account and the name of the domain on which the account was found.

Syntax


NTSTATUS SecLookupAccountName(
  _In_    PUNICODE_STRING Name,
  _Inout_ PULONG          SidSize,
  _Out_   PSID            Sid,
  _Out_   PSID_NAME_USE   NameUse,
  _Out_   PULONG          DomainSize,
  _Inout_ PUNICODE_STRING ReferencedDomain
);

Parameters

Name [in]

A pointer to a Unicode string that specifies the account name. Use a fully qualified string in the domain_name\user_name format to ensure that SecLookupAccountName finds the account in the desired domain.

SidSize [in, out]

A pointer to a variable that specifies the size of the Sid buffer. On input, this value specifies the size in bytes of the input Sid buffer. If the function fails because the buffer is too small or if SidSize is zero, this variable receives the required buffer size. On success, this variable contains the size of the returned Sid.

Sid [out]

A pointer to a buffer that receives the SID structure that corresponds to the account name pointed to by the Name parameter. If this parameter is NULL, SidSize must be zero.

NameUse [out]

A pointer to a SID_NAME_USE enumerated type that indicates the type of the account when the function returns.

DomainSize [out]

A pointer to an optional variable that specifies the size of the ReferencedDomain parameter. On input, this value specifies the size of the ReferencedDomain buffer. If the function fails because the buffer is too small, this variable receives the required buffer size. If the ReferencedDomain parameter is NULL, this parameter must be zero.

ReferencedDomain [in, out]

A pointer to a buffer that receives the name of the domain as a Unicode string where the account name is found. For computers that are not joined to a domain, this buffer receives the computer name. If this parameter is NULL, the function returns the required buffer size in the DomainSize variable.

Return value

SecLookupAccountName returns STATUS_SUCCESS on success or one of the following error codes on failure:

Return codeDescription
SEC_E_INTERNAL_ERROR

An internal error occurred while trying to connect to the Local System Authority (LSA) or the local procedure call (LPC) to the security provider failed.

STATUS_ACCESS_DENIED

The process ID associated with the currently executing thread does not match the current process ID.

STATUS_BUFFER_TOO_SMALL

The buffer size for the Sid or the ReferencedDomain parameter was too small.

STATUS_INVALID_PARAMETER

The length of the Name parameter exceeded the length allowed in a message to the Local System Authority.

STATUS_NONE_MAPPED

The Name parameter could not be found.

STATUS_PROCESS_IS_TERMINATING

This process has terminated so it is not possible to establish the local procedure call (LPC) connection.

 

Remarks

SecLookupAccountName attempts to find a SID for the specified name. The function checks built-in and administratively defined local accounts. Next, the function checks the primary domain. If the name is not found there, trusted domains are checked.

Use fully qualified account names (for example, domain_name\user_name) instead of isolated names (for example, user_name). Fully qualified names are unambiguous and provide better performance when the lookup is performed. This function also supports fully qualified DNS names (for example, example.example.com\user_name) and user principal names (UPN) (for example, someone@example.com).

In addition to looking up local accounts, local domain accounts, and explicitly trusted domain accounts, SecLookupAccountName can look up the name for any account in any domain in the forest.

SecLookupAccountName is equivalent to the Win32 LookupAccountName function.

SecLookupAccountName is exported by the ksecdd driver, which implements this function by using user-mode helper services. Accordingly, the use of this function within file systems must obey the usual rules for communication with user-mode services. SecLookupAccountName cannot be used during paging file I/O.

Requirements

Target platform

Universal

Version

The SecLookupAccountName function is only available on Windows XP and later.

Header

Ntifs.h (include Ntifs.h)

Library

Ksecdd.lib

IRQL

<= APC_LEVEL

See also

SecLookupAccountSid
SecLookupWellKnownSid
SID
SID_NAME_USE

 

 

Send comments about this topic to Microsoft

Show: