Export (0) Print
Expand All
Expand Minimize

AuthzAccessCheck function

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


BOOL WINAPI AuthzAccessCheck(
  _In_       DWORD flags,
  _In_       AUTHZ_CLIENT_CONTEXT_HANDLE hAuthzClientContext,
  _In_       PAUTHZ_ACCESS_REQUEST pRequest,
  _In_opt_   AUTHZ_AUDIT_EVENT_HANDLE AuditEvent,
  _In_       PSECURITY_DESCRIPTOR pSecurityDescriptor,
  _In_opt_   PSECURITY_DESCRIPTOR *OptionalSecurityDescriptorArray,
  _In_opt_   DWORD OptionalSecurityDescriptorCount,
  _Inout_    PAUTHZ_ACCESS_REPLY pReply,
  _Out_opt_  PAUTHZ_ACCESS_CHECK_RESULTS_HANDLE phAccessCheckResults
);

Parameters

flags [in]

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.

ValueMeaning
0

If pAuthzHandle is not NULL, a deep copy of the security descriptor is copied to the handle referenced by pAuthzHandle.

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 pAuthzHandle. The AuthzAccessCheck function sets this handle to a security descriptor that must remain valid during subsequent calls to AuthzCachedAccessCheck.

 

hAuthzClientContext [in]

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.

pRequest [in]

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.

AuditEvent [in, optional]

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.

pSecurityDescriptor [in]

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.

OptionalSecurityDescriptorArray [in, optional]

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.

OptionalSecurityDescriptorCount [in, optional]

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

pReply [in, out]

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.

phAccessCheckResults [out, optional]

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

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Redistributable

Windows Server 2003 Administration Tools Pack on Windows XP

Header

Authz.h

Library

Authz.lib

DLL

Authz.dll

See also

Basic Access Control Functions
Centralized Authorization Policy
How AccessCheck Works
Security Descriptor Definition Language for Conditional ACEs
AUTHZ_ACCESS_REPLY
AUTHZ_ACCESS_REQUEST
AuthzCachedAccessCheck
SECURITY_DESCRIPTOR

 

 

Community Additions

ADD
Show:
© 2014 Microsoft