Click to Rate and Give Feedback
MSDN
MSDN Library
Windows Development
Authorization
 AuthzAccessCheck function
AuthzAccessCheck function

Applies to: desktop apps only

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 8 Beta, 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 8 Beta, 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 8 Beta, 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 NULLdiscretionary 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 NULLsystem 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. NULLaccess 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 8 Beta, 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).

Attribute variables must be in the form of an expression when used with logical operators; otherwise, they are evaluated as unknown.

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

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
AUTHZ_ACCESS_REPLY
AUTHZ_ACCESS_REQUEST
AuthzCachedAccessCheck
SECURITY_DESCRIPTOR

 

 

Send comments about this topic to Microsoft

Build date: 3/7/2012

Tags What's this?: Add a tag
Community Content   What is Community Content?
Add new content RSS  Annotations
EXAMPLE CODE      apoorv020   |   Edit   |   Show History
 See http://msdn.microsoft.com/en-us/library/aa446637%28VS.85%29.aspx#examples for sample MSDN code for this function.
Tags What's this?: Add a tag
Flag as ContentBug
ERROR_INVALID_PARAMETER      ChristianWimmer   |   Edit   |   Show History
The member "ObjectTypeList" of paramater pRequest must comply to some rules. They are originally defined in doc of AccessCheckByType
(http://msdn2.microsoft.com/en-us/library/aa374826(VS.85).aspx).

Modified quote:

ObjectTypeList

A pointer to an array of OBJECT_TYPE_LIST structures that identify the hierarchy of object types for which to check access. Each element in the array specifies a GUID that identifies the object type and a value indicating the level of the object type in the hierarchy of object types. The array should not have two elements with the same GUID.

The array must have at least one element. The first element in the array must be at level zero and identify the object itself. The array can have only one level zero element. The second element is a subobject, such as a property set, at level 1. Following each level 1 entry are subordinate entries for the level 2 through 4 subobjects. Thus, the levels for the elements in the array might be {0, 1, 2, 2, 1, 2, 3}. If the object type list is out of order, AuthzAccessCheck fails and GetLastError returns ERROR_INVALID_PARAMETER.

If ObjectTypeList is NULL, AuthzAccessCheck is the same as the AccessCheck function.

In other words (as sequence):

Array[i].Level = a_i    
{ a_i +1 | a_i - a_(i-1) = 1 AND a_i < 4
a_i+1 = { a_i - t | a_i - t AND t >= 0
{ ERROR_INVALID_PARAMETER | else
sequence start: a_0 = 0 


Tags What's this?: Add a tag
Flag as ContentBug
Processing
© 2012 Microsoft. All rights reserved. Terms of Use | Trademarks | Privacy Statement
Page view tracker