Export (0) Print
Expand All
Expand Minimize

AccessCheckByType function

The AccessCheckByType function determines whether a security descriptor grants a specified set of access rights to the client identified by an access token. The function can check the client's access to a hierarchy of objects, such as an object, its property sets, and properties. The function grants or denies access to the hierarchy as a whole. Typically, server applications use this function to check access to a private object.

Syntax


BOOL WINAPI AccessCheckByType(
  _In_         PSECURITY_DESCRIPTOR pSecurityDescriptor,
  _In_opt_     PSID PrincipalSelfSid,
  _In_         HANDLE ClientToken,
  _In_         DWORD DesiredAccess,
  _Inout_opt_  POBJECT_TYPE_LIST ObjectTypeList,
  _In_         DWORD ObjectTypeListLength,
  _In_         PGENERIC_MAPPING GenericMapping,
  _Out_opt_    PPRIVILEGE_SET PrivilegeSet,
  _Inout_      LPDWORD PrivilegeSetLength,
  _Out_        LPDWORD GrantedAccess,
  _Out_        LPBOOL AccessStatus
);

Parameters

pSecurityDescriptor [in]

A pointer to a SECURITY_DESCRIPTOR structure against which access is checked.

PrincipalSelfSid [in, optional]

A pointer to a security identifier (SID). If the security descriptor is associated with an object that represents a principal (for example, a user object), the PrincipalSelfSid parameter should be the SID of the object. When evaluating access, this SID logically replaces the SID in any access control entry containing the well-known PRINCIPAL_SELF SID (S-1-5-10). For information about well-known SIDs, see Well-known SIDs.

Set this parameter to NULL if the protected object does not represent a principal.

ClientToken [in]

A handle to an impersonation token that represents the client attempting to gain access. The handle must have TOKEN_QUERY access to the token; otherwise, the function fails with ERROR_ACCESS_DENIED.

DesiredAccess [in]

Access mask that specifies the access rights to check. This mask must have been mapped by the MapGenericMask function to contain no generic access rights.

If this parameter is MAXIMUM_ALLOWED, the function sets the GrantedAccess access mask to indicate the maximum access rights the security descriptor allows the client.

ObjectTypeList [in, out, optional]

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, AccessCheckByType fails and GetLastError returns ERROR_INVALID_PARAMETER.

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

ObjectTypeListLength [in]

Specifies the number of elements in the ObjectTypeList array.

GenericMapping [in]

A pointer to the GENERIC_MAPPING structure associated with the object for which access is being checked. The GenericAll member of the GENERIC_MAPPING structure should contain all the access rights that can be granted by the resource manager, including STANDARD_RIGHTS_ALL and all of the rights that are set in the GenericRead, GenericWrite, and GenericExecute members.

PrivilegeSet [out, optional]

A pointer to a PRIVILEGE_SET structure that receives the privileges used to perform the access validation. If no privileges were used, the function sets the PrivilegeCount member to zero.

PrivilegeSetLength [in, out]

Specifies the size, in bytes, of the buffer pointed to by the PrivilegeSet parameter.

GrantedAccess [out]

A pointer to an access mask that receives the granted access rights. If AccessStatus is set to FALSE, the function sets the access mask to zero. If the function fails, it does not set the access mask.

AccessStatus [out]

A pointer to a variable that receives the results of the access check. If the security descriptor allows the requested access rights to the client identified by the access token, AccessStatus is set to TRUE. Otherwise, AccessStatus is set to FALSE, and you can call GetLastError to get extended error information.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

For more information, see the How AccessCheck Works overview.

The AccessCheckByType function compares the specified security descriptor with the specified access token and indicates, in the AccessStatus parameter, whether access is granted or denied.

The ObjectTypeList array does not necessarily represent the entire defined object. Rather, it represents that subset of the object for which to check access. For instance, to check access to two properties in a property set, specify an object type list with four elements: the object itself at level zero, the property set at level 1, and the two properties at level 2.

The AccessCheckByType function evaluates ACEs that apply to the object itself and object-specific ACEs for the object types listed in the ObjectTypeList array. The function ignores object-specific ACEs for object types not listed in the ObjectTypeList array. Thus, the results returned in the AccessStatus parameter indicate the access allowed to the subset of the object defined by the ObjectTypeList parameter, not to the entire object.

For more information about how a hierarchy of ACEs controls access to an object and its subobjects, see ACEs to Control Access to an Object's Properties.

If the security descriptor's DACL is NULL, the AccessStatus parameter returns TRUE, indicating that the client has the requested access.

If the security descriptor does not contain owner and group SIDs, AccessCheckByType fails with ERROR_INVALID_SECURITY_DESCR.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Winbase.h (include Windows.h)

Library

Advapi32.lib

DLL

Advapi32.dll

See also

Client/Server Access Control
Client/Server Access Control Functions
How AccessCheck Works
AccessCheck
AccessCheckAndAuditAlarm
AccessCheckByTypeAndAuditAlarm
AccessCheckByTypeResultList
AccessCheckByTypeResultListAndAuditAlarm
GENERIC_MAPPING
MakeAbsoluteSD
MapGenericMask
OBJECT_TYPE_LIST
PRIVILEGE_SET
SECURITY_DESCRIPTOR

 

 

Community Additions

ADD
Show:
© 2014 Microsoft