AccessCheck

The AccessCheck function determines whether a security descriptor grants a specified set of access rights to the client identified by an access token. Typically, server applications use this function to check access to a private object.

BOOL AccessCheck(
  PSECURITY_DESCRIPTOR pSecurityDescriptor,   // security descriptor
  HANDLE ClientToken,               // handle to client access token
  DWORD DesiredAccess,              // requested access rights 
  PGENERIC_MAPPING GenericMapping,  // map generic to specific rights
  PPRIVILEGE_SET PrivilegeSet,      // receives privileges used
  LPDWORD PrivilegeSetLength,       // size of privilege-set buffer
  LPDWORD GrantedAccess,     // retrieves mask of granted rights
  LPBOOL AccessStatus        // retrieves results of access check
);
 

Parameters

pSecurityDescriptor

Pointer to a SECURITY_DESCRIPTOR structure against which access is checked.

ClientToken

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

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.

GenericMapping

Pointer to the GENERIC_MAPPING structure associated with the object for which access is being checked.

PrivilegeSet

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

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

GrantedAccess

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

AccessStatus

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 returns TRUE. Otherwise, AccessStatus returns FALSE, and you can call GetLastError to get extended error information.

Return Values

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

The AccessCheck function compares the specified security descriptor with the specified access token and indicates, in the AccessStatus parameter, whether access is granted or denied. If access is granted, the requested access mask becomes the object's granted access mask.

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

AccessCheck fails with ERROR_INVALID_SECURITY_DESCR if the security descriptor does not contain owner and group SIDs.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use advapi32.lib.

See Also

Client/Server Access Control Overview, Client/Server Access Control Functions, AccessCheckAndAuditAlarm, AreAllAccessesGranted, AreAnyAccessesGranted, GENERIC_MAPPING, MapGenericMask, PrivilegeCheck, PRIVILEGE_SET, SECURITY_DESCRIPTOR