Edit

Share via

AuthzCachedAccessCheck function (authz.h)

  • Article

The AuthzCachedAccessCheck function performs a fast access check based on a cached handle containing the static granted bits from a previous AuthzAccessCheck call.

Syntax

AUTHZAPI BOOL AuthzCachedAccessCheck(
  [in]  DWORD                             Flags,
  [in]  AUTHZ_ACCESS_CHECK_RESULTS_HANDLE hAccessCheckResults,
  [in]  PAUTHZ_ACCESS_REQUEST             pRequest,
  [in]  AUTHZ_AUDIT_EVENT_HANDLE          hAuditEvent,
  [out] PAUTHZ_ACCESS_REPLY               pReply
);

Parameters

[in] Flags

Reserved for future use.

[in] hAccessCheckResults

A handle to the cached access check results.

[in] pRequest

Access request handle specifying the desired access mask, principal self SID, and the object type list structure (if any).

[in] hAuditEvent

A structure that contains object-specific audit information. When the value of this parameter is not null, an audit is automatically requested. Static audit information is read from the resource manager structure.

[out] pReply

A pointer to an AUTHZ_ACCESS_REPLY handle that returns the results of access check as an array of GrantedAccessMask/ErrorValue pairs. The number of pairs returned is supplied by the caller in the ResultListLength member of the AUTHZ_ACCESS_REPLY structure.

Return value

If the function succeeds, it returns TRUE.

If the function fails, it returns FALSE. To get extended error information, call GetLastError.

Expected values of the Error members of array elements returned are shown in the following table.

Return code Description
ERROR_SUCCESS
 All the access bits, not including MAXIMUM_ALLOWED, are granted and the GrantedAccessMask member of the pReply parameter is not zero.
ERROR_PRIVILEGE_NOT_HELD
 The DesiredAccess member of the pRequest parameter includes ACCESS_SYSTEM_SECURITY, and the client does not have the SeSecurityPrivilege privilege.
ERROR_ACCESS_DENIED
 One or more of the following is true:
  • The requested bits are not granted.
  • The MaximumAllowed bit is on, and the granted access is zero.
  • The DesiredAccess member of the pRequest parameter is zero.

Remarks

The client context pointer is stored in the AuthzHandle parameter. The structure of the client context must be exactly the same as it was at the time AuthzHandle was created. This restriction is for the following fields:

  • SIDs
  • RestrictedSids
  • Privileges
Pointers to the primary security descriptor and the optional security descriptor array are stored in AuthzHandle at the time of handle creation. These pointers must still be valid.

The AuthzCachedAccessCheck function maintains a cache as a result of evaluating Central Access Policies (CAP) on objects unless CAPs are ignored, for example when the AUTHZ_RM_FLAG_NO_CENTRAL_ACCESS_POLICIES flag is used. The client may call the AuthzFreeCentralAccessPolicyCache function to free up this cache. Note that this requires a subsequent call to AuthzCachedAccessCheck to rebuild the cache if necessary.

For more information, see the How AccessCheck Works and Centralized Authorization Policy overviews.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header authz.h
Library Authz.lib
DLL Authz.dll
Redistributable Windows Server 2003 Administration Tools Pack on Windows XP

See also

AUTHZ_ACCESS_REPLY

AuthzAccessCheck

AuthzFreeCentralAccessPolicyCache

AuthzInitializeResourceManager

Basic Access Control Functions

Centralized Authorization Policy

How AccessCheck Works