Edit

Share via

AuthzAccessCheck function (authz.h)

  • Article

The AuthzAccessCheck function determines which access bits can be granted to a client for a given set of security descriptors. The AUTHZ_ACCESS_REPLY structure returns an array of granted access masks and error status. Optionally, access masks that will always be granted can be cached, and a handle to cached values is returned.

Syntax

AUTHZAPI BOOL AuthzAccessCheck(
  [in]            DWORD                              Flags,
  [in]            AUTHZ_CLIENT_CONTEXT_HANDLE        hAuthzClientContext,
  [in]            PAUTHZ_ACCESS_REQUEST              pRequest,
  [in, optional]  AUTHZ_AUDIT_EVENT_HANDLE           hAuditEvent,
  [in]            PSECURITY_DESCRIPTOR               pSecurityDescriptor,
  [in, optional]  PSECURITY_DESCRIPTOR               *OptionalSecurityDescriptorArray,
  [in, optional]  DWORD                              OptionalSecurityDescriptorCount,
  [in, out]       PAUTHZ_ACCESS_REPLY                pReply,
  [out, optional] PAUTHZ_ACCESS_CHECK_RESULTS_HANDLE phAccessCheckResults
);

Parameters

[in] Flags

A DWORD value that specifies how the security descriptor is copied. This parameter can be one of the following values.

Starting with Windows 8 and Windows Server 2012, when you call this function on a remote context handle, the upper 16 bits must be zero.

Value Meaning
0
 If phAccessCheckResults is not NULL, a deep copy of the security descriptor is copied to the handle referenced by phAccessCheckResults.
AUTHZ_ACCESS_CHECK_NO_DEEP_COPY_SD
1
 A deep copy of the security descriptor is not performed. The calling application must pass the address of an AUTHZ_ACCESS_CHECK_RESULTS_HANDLE handle in phAccessCheckResults. The AuthzAccessCheck function sets this handle to a security descriptor that must remain valid during subsequent calls to AuthzCachedAccessCheck.

[in] hAuthzClientContext

A handle to a structure that represents the client.

Starting with Windows 8 and Windows Server 2012, the client context can be local or remote.

[in] pRequest

A pointer to an AUTHZ_ACCESS_REQUEST structure that specifies the desired access mask, principal self security identifier (SID), and the object type list structure, if it exists.

[in, optional] 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.

Starting with Windows 8 and Windows Server 2012, when you use this function with a remote context handle, the value of the parameter must be NULL.

[in] pSecurityDescriptor

A pointer to a SECURITY_DESCRIPTOR structure to be used for access checks. The owner SID for the object is picked from this security descriptor. A NULL discretionary access control list (DACL) in this security descriptor represents a NULL DACL for the entire object. Make sure the security descriptor contains OWNER and DACL information, or an error code 87 or "invalid parameter" message will be generated.

Important  NULL DACLs permit all types of access to all users; therefore, do not use NULL DACLs. For information about creating a DACL, see Creating a DACL.
 
A NULL system access control list (SACL) in this security descriptor is treated the same way as an empty SACL.

[in, optional] OptionalSecurityDescriptorArray

An array of SECURITY_DESCRIPTOR structures. NULL access control lists (ACLs) in these security descriptors are treated as empty ACLs. The ACL for the entire object is the logical concatenation of all of the ACLs.

[in, optional] OptionalSecurityDescriptorCount

The number of security descriptors not including the primary security descriptor.

[in, out] pReply

A pointer to an AUTHZ_ACCESS_REPLY structure that contains the results of the access check. Before calling the AuthzAccessCheck function, an application must allocate memory for the GrantedAccessMask and SaclEvaluationResults members of the AUTHZ_ACCESS_REPLY structure referenced by pReply.

[out, optional] phAccessCheckResults

A pointer to return a handle to the cached results of the access check. When this parameter value is not null, the results of this access check call will be cached. This results in a MAXIMUM_ALLOWED check.

Starting with Windows 8 and Windows Server 2012, when you use this function with a remote context handle, the value of the parameter must be NULL.

Return value

If the function succeeds, the function returns TRUE.

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

Remarks

The AuthzAccessCheckCallback callback function will be called if the DACL of the SECURITY_DESCRIPTOR structure pointed to by the pSecurityDescriptor parameter contains a callback access control entry (ACE).

Security attribute variables must be present in the client context if referred to in a conditional expression, otherwise the conditional expression term referencing them will evaluate to unknown. For more information, see the Security Descriptor Definition Language for Conditional ACEs topic.

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

AUTHZ_ACCESS_REQUEST

AuthzCachedAccessCheck

Basic Access Control Functions

Centralized Authorization Policy

How AccessCheck Works

SECURITY_DESCRIPTOR

Security Descriptor Definition Language for Conditional ACEs