Opening a Policy Object Handle

Most LSA Policy functions require a handle to the Policy object for the system to query or modify. To obtain a handle to a Policy object, call LsaOpenPolicy and specify the name of the system you want to access and the set of access permissions required.

The access permissions required for your application depend on the actions it performs. For details about the permissions required for each function, see the description of that function in LSA Policy Functions.

If the call to LsaOpenPolicy is successful, it returns a handle to the Policy object for the specified system. Your application then passes this handle in subsequent LSA Policy function calls. When your application no longer needs the handle, it should call LsaClose to free it.

The following example shows how to open a Policy object handle.

#include <windows.h>

#define TARGET_SYSTEM_NAME L"mysystem"

LSA_HANDLE GetPolicyHandle()
{
  LSA_OBJECT_ATTRIBUTES ObjectAttributes;
  WCHAR SystemName[] = TARGET_SYSTEM_NAME;
  USHORT SystemNameLength;
  LSA_UNICODE_STRING lusSystemName;
  NTSTATUS ntsResult;
  LSA_HANDLE lsahPolicyHandle;

  // Object attributes are reserved, so initialize to zeros.
  ZeroMemory(&ObjectAttributes, sizeof(ObjectAttributes));

  //Initialize an LSA_UNICODE_STRING to the server name.
  SystemNameLength = wcslen(SystemName);
  lusSystemName.Buffer = SystemName;
  lusSystemName.Length = SystemNameLength * sizeof(WCHAR);
  lusSystemName.MaximumLength = (SystemNameLength+1) * sizeof(WCHAR);

  // Get a handle to the Policy object.
  ntsResult = LsaOpenPolicy(
        &lusSystemName,    //Name of the target system.
        &ObjectAttributes, //Object attributes.
        POLICY_ALL_ACCESS, //Desired access permissions.
        &lsahPolicyHandle  //Receives the policy handle.
    );

  if (ntsResult != STATUS_SUCCESS)
  {
    // An error occurred. Display it as a win32 error code.
    wprintf(L"OpenPolicy returned %lu\n",
      LsaNtStatusToWinError(ntsResult));
    return NULL;
  } 
  return lsahPolicyHandle;
}

In the preceding example, the application requested POLICY_ALL_ACCESS privileges. For details about which permissions your application should request when calling LsaOpenPolicy, see the descriptions of the functions that your application will pass the Policy object handle to.

To open a handle to the Policy object of a trusted domain, call LsaCreateTrustedDomainEx (to create a new trust relationship with a domain) or call LsaOpenTrustedDomainByName (to access an existing trusted domain). Both of these functions set a pointer to an LSA_HANDLE, which you can then specify in subsequent LSA Policy function calls. As with LsaOpenPolicy, your application should call LsaClose when it no longer needs the handle to the trusted domain's Policy object.