Home Library Learn Downloads Support Community
Sign in | United States - English | |
3 out of 5 rated this helpful - Rate this topic

AccessCheck function

Applies to: desktop apps only

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.

Syntax

Copy 
BOOL WINAPI AccessCheck(
  __in       PSECURITY_DESCRIPTOR pSecurityDescriptor,
  __in       HANDLE ClientToken,
  __in       DWORD DesiredAccess,
  __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.

ClientToken [in]

A handle to an impersonation token that represents the client that is 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.

GenericMapping [in]

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

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

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, which indicates that the client has the requested access.

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

The AccessCheck function does not generate an audit. If your application requires audits for access checks, use functions such as AccessCheckAndAuditAlarm, AccessCheckByTypeAndAuditAlarm, AccessCheckByTypeResultListAndAuditAlarm, or AccessCheckByTypeResultListAndAuditAlarmByHandle, instead of AccessCheck.

Examples

For an example that uses this function, see Verifying Client Access with ACLs.

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header
Winbase.h (include Windows.h)

Library
Advapi32.lib

DLL
Advapi32.dll

See also

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

 

 

Send comments about this topic to Microsoft

Build date: 3/7/2012

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
PrivilegeSet is not that kind of optional Parameter

You must not set Parameter PrivilegeSet to a NULL value. Instead call AccessCheck twice to get a value for PrivilegeSetLength. The first call fails with ERROR_INSUFFICIENT_BUFFER if you set PrivilegeSetLength to zero. Then allocate memory for PrivilegeSet (LocalAlloc(LPTR, PrivilegeSetLength)) and call AccessCheck a second time.It is possible to use the following code if you know that only max one privilege is used for the access check (namely SeTakeOwnershipPrivilege)

DWORD privilegeSetLength = sizeof(PRIVILEGE_SET);
PRIVILEGE_SET privilegeSet = {0};

However, in future versions of Windows there can be more than one used privilege in the access check and thus make the function AccessCheck fail with ERROR_INSUFFICIENT_BUFFER again.

History
ERROR_NO_IMPERSONATION_TOKEN (1309)
This error means that your token (parameter ClientToken) is not an impersonation token (=thread token) but a primary one. So you have to convert it (DuplicateToken) to a thread token first. If you just want to use the current token of the process you can also use 
ImpersonateSelf(SecurityImpersonation)
and then call OpenThreadToken to retrieve an impersonated token for AccessCheck (like the example). Don't forget to call RevertToSelf in the end.

AccessCheck doesn't care about whether the thread is actually impersonated or not.


History