LsaOpenPolicy function (ntsecapi.h)

Article
10/13/2021

The LsaOpenPolicy function opens a handle to the Policy object on a local or remote system.

You must run the process "As Administrator" so that the call doesn't fail with ERROR_ACCESS_DENIED.

Syntax

NTSTATUS LsaOpenPolicy(
  [in]      PLSA_UNICODE_STRING    SystemName,
  [in]      PLSA_OBJECT_ATTRIBUTES ObjectAttributes,
  [in]      ACCESS_MASK            DesiredAccess,
  [in, out] PLSA_HANDLE            PolicyHandle
);

Parameters

[in] SystemName

A pointer to an LSA_UNICODE_STRING structure that contains the name of the target system. The name can have the form "ComputerName" or "\\ComputerName". If this parameter is NULL, the function opens the Policy object on the local system.

[in] ObjectAttributes

A pointer to an LSA_OBJECT_ATTRIBUTES structure that specifies the connection attributes. The structure members are not used; initialize them to NULL or zero.

[in] DesiredAccess

An ACCESS_MASK that specifies the requested access rights. The function fails if the DACL of the target system does not allow the caller the requested access. To determine the access rights that you need, see the documentation for the LSA functions with which you want to use the policy handle.

[in, out] PolicyHandle

A pointer to an LSA_HANDLE variable that receives a handle to the Policy object.

When you no longer need this handle, pass it to the LsaClose function to close it.

Return value

If the function succeeds, the function returns STATUS_SUCCESS.

If the function fails, it returns an NTSTATUS code. For more information, see LSA Policy Function Return Values.

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

Remarks

To administer the local security policy of a local or remote system, you must call the LsaOpenPolicy function to establish a session with that system's LSA subsystem. LsaOpenPolicy connects to the LSA of the target system and returns a handle to the Policy object of that system. You can use this handle in subsequent LSA function calls to administer the local security policy information of the target system.

For an example that demonstrates calling this function see Opening a Policy Object Handle.

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