Share via

3.1.4.4.1 LsarOpenPolicy2 (Opnum 44)

  • Article

The LsarOpenPolicy2 method opens a context handle to the RPC server. This is the first function that MUST be called to contact the Local Security Authority (Domain Policy) Remote Protocol database.

 NTSTATUS LsarOpenPolicy2(
   [in, unique, string] wchar_t* SystemName,
   [in] PLSAPR_OBJECT_ATTRIBUTES ObjectAttributes,
   [in] ACCESS_MASK DesiredAccess,
   [out] LSAPR_HANDLE* PolicyHandle
 );

SystemName: This parameter does not have any effect on message processing in any environment. It MUST be ignored on receipt.

ObjectAttributes: This parameter does not have any effect on message processing in any environment. All fields MUST<61> be ignored except RootDirectory which MUST be NULL.

DesiredAccess: An ACCESS_MASK value that specifies the requested access rights that MUST be granted on the returned PolicyHandle if the request is successful.

PolicyHandle: An RPC context handle (as specified in section 2.2.2.1) that represents a reference to the abstract data model of a policy object, as specified in section 3.1.1.1.

Return Values: The following is a summary of the return values that an implementation MUST return, as specified by the message processing below.

Return value/code

Description

0x00000000

STATUS_SUCCESS

The request was successfully completed.

0xC0000022

STATUS_ACCESS_DENIED

The caller does not have the permissions to perform this operation.

0xC000000D

STATUS_INVALID_PARAMETER

One of the supplied parameters is incorrect. For example, this can happen when ObjectAttributes is NULL or DesiredAccess is zero.

Processing:

DesiredAccess: A bitmask specifying the access that the caller attempts to obtain on the policy object, which is access-checked according to section 3.1.4.2.1. The method-specific portion of the check is the following:

 LET serverInfo be a SERVER_INFO_101 structure
 CALL ServerGetInfo(101, &serverInfo)
 LET isDomainController be a boolean initialized to FALSE
 IF (serverInfo.sv101_version_type & (SV_TYPE_DOMAIN_CTRL | SV_TYPE_DOMAIN_BAKCTRL)) THEN
     Set isDomainController equal to TRUE
 END IF
            
 IF ((isDomainController equals FALSE) and (IsRequestorAnonymous() and LsaRestrictAnonymous is set to TRUE)) THEN
     Return STATUS_ACCESS_DENIED
 END IF

SERVER_INFO_101, SV_TYPE_DOMAIN_CTRL, and SV_TYPE_DOMAIN_BACKCTRL are specified in [MS-DTYP] section 2.3.12. The ServerGetInfo procedure is specified in [MS-DTYP] section 2.6. The valid account-rights bits are specified in section 2.2.1.1.2, and the security descriptor is specified in section 3.1.1.1.  The IsRequestorAnonymous procedure is specified in section 3.1.4.2.3.

PolicyHandle: If the request is successful, the server MUST create and return a context handle (section 3.1.1.7) via PolicyHandle, with its fields initialized as follows:

  • LsaContextHandle.HandleType = "Policy"

  • LsaContextHandle.Object = the policy object

  • LsaContextHandle.GrantedAccess = as specified in section 3.1.4.2.1

The return value MUST be set to STATUS_SUCCESS in this case.

The LsarOpenPolicy3 method supersedes this message and MUST be used whenever possible.