AccessCheckByTypeResultListAndAuditAlarmByHandleA function (winbase.h)

Article
08/03/2022

The AccessCheckByTypeResultListAndAuditAlarmByHandle function determines whether a security descriptor grants a specified set of access rights to the client that the calling thread is impersonating. The difference between this function and AccessCheckByTypeResultListAndAuditAlarm is that this function allows the calling thread to perform the access check before impersonating the client.

The function can check access to a hierarchy of objects, such as an object, its property sets, and properties. The function reports the access rights granted or denied to each object type in the hierarchy. If the security descriptor has a system access control list (SACL) with access control entries (ACEs) that apply to the client, the function generates any necessary audit messages in the security event log. Alarms are not currently supported.

Syntax

BOOL AccessCheckByTypeResultListAndAuditAlarmByHandleA(
  [in]                LPCSTR               SubsystemName,
  [in]                LPVOID               HandleId,
  [in]                HANDLE               ClientToken,
  [in]                LPCSTR               ObjectTypeName,
  [in, optional]      LPCSTR               ObjectName,
  [in]                PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                DWORD                DesiredAccess,
  [in]                AUDIT_EVENT_TYPE     AuditType,
  [in]                DWORD                Flags,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [in]                PGENERIC_MAPPING     GenericMapping,
  [in]                BOOL                 ObjectCreation,
  [out]               LPDWORD              GrantedAccess,
  [out]               LPDWORD              AccessStatusList,
  [out]               LPBOOL               pfGenerateOnClose
);

Parameters

[in] SubsystemName

A pointer to a null-terminated string that specifies the name of the subsystem calling the function. This string appears in any audit message that the function generates.

[in] HandleId

A pointer to a unique value that represents the client's handle to the object. If the access is denied, the system ignores this value.

[in] ClientToken

A handle to a token object that represents the client that requested the operation. This handle must be obtained through a communication session layer, such as a local named pipe, to prevent possible security policy violations. The caller must have TOKEN_QUERY access for the specified token.

[in] ObjectTypeName

A pointer to a null-terminated string that specifies the type of object being created or accessed. This string appears in any audit message that the function generates.

[in, optional] ObjectName

A pointer to a null-terminated string that specifies the name of the object being created or accessed. This string appears in any audit message that the function generates.

[in] SecurityDescriptor

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

[in, optional] PrincipalSelfSid

A pointer to a 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 ACE 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.

[in] DesiredAccess

An access mask that specifies the access rights to check. This mask must have been mapped by the MapGenericMask function so that it contains no generic access rights.

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

[in] AuditType

The type of audit to be generated. This can be one of the values from the AUDIT_EVENT_TYPE enumeration type.

[in] Flags

A flag that controls the function's behavior if the calling process does not have the SE_AUDIT_NAME privilege enabled. If the AUDIT_ALLOW_NO_PRIVILEGE flag is set, the function performs the access check without generating audit messages when the privilege is not enabled. If this parameter is zero, the function fails if the privilege is not enabled.

[in, out, optional] 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 that indicates 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, AccessCheckByTypeResultListAndAuditAlarmByHandle fails, and GetLastError returns ERROR_INVALID_PARAMETER.

[in] ObjectTypeListLength

The number of elements in the ObjectTypeList array.

[in] GenericMapping

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

[in] ObjectCreation

A flag that determines whether the calling application will create a new object when access is granted. A value of TRUE indicates the application will create a new object. A value of FALSE indicates the application will open an existing object.

[out] GrantedAccess

A pointer to an array of access masks. The function sets each access mask to indicate the access rights granted to the corresponding element in the object type list. If the function fails, it does not set the access masks.

[out] AccessStatusList

A pointer to an array of status codes for the corresponding elements in the object type list. The function sets an element to zero to indicate success or to a nonzero value to indicate the specific error during the access check. If the function fails, it does not set any of the elements in the array.

[out] pfGenerateOnClose

A pointer to a flag set by the audit-generation routine when the function returns. Pass this flag to the ObjectCloseAuditAlarm function when the object handle is closed.

Return value

If the function succeeds, the function returns nonzero.

If the function fails, it returns zero. To get extended error information, call GetLastError.

Remarks

For more information, see the How AccessCheck Works overview.

Like AccessCheckByTypeResultListAndAuditAlarm, the AccessCheckByTypeResultListAndAuditAlarmByHandle function is a combination of the AccessCheckByTypeResultList and AccessCheckAndAuditAlarm functions. However, AccessCheckByTypeResultListAndAuditAlarmByHandle also requires a client token handle to provide security information on the client.

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 AccessCheckByTypeResultListAndAuditAlarmByHandle 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.

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.

To generate audit messages in the security event log, the calling process must have the SE_AUDIT_NAME privilege enabled. The system checks for this privilege in the primary token of the calling process, not the impersonation token of the thread. If the Flags parameter includes the AUDIT_ALLOW_NO_PRIVILEGE flag, the function performs the access check without generating audit messages when the privilege is not enabled.

The AccessCheckByTypeResultListAndAuditAlarmByHandle function fails if the calling thread is not impersonating a client.

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

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	winbase.h (include Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll