AccessCheckByTypeAndAuditAlarm

[This is preliminary documentation and subject to change.]

The AccessCheckByTypeAndAuditAlarm function determines whether a security descriptor grants a specified set of access rights to the client being impersonated by the calling thread. 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. If the security descriptor has a SACL with ACEs that apply to the client, the function generates any necessary audit messages in the security event log. Alarms are not supported in the current version of Windows NT.

BOOL AccessCheckByTypeAndAuditAlarm(
  LPCTSTR SubsystemName,            // subsystem name
  LPVOID HandleId,                  // object's handle identifier
  LPCTSTR ObjectTypeName,           // type of object
  LPCTSTR ObjectName,               // name of object
  PSECURITY_DESCRIPTOR pSecurityDescriptor,   // security descriptor
  PSID PrincipalSelfSid,            // SID of object being checked
  DWORD DesiredAccess,              // requested access rights 
  AUDIT_EVENT_TYPE AuditType,       // type of audit 
  DWORD Flags,          // allows access check if no audit privilege
  POBJECT_TYPE_LIST ObjectTypeList, // array of object types
  DWORD ObjectTypeListLength,       // number of object type elements
  PGENERIC_MAPPING GenericMapping,  // map generic to specific rights
  BOOL ObjectCreation,       // flag is TRUE if creating an object
  LPDWORD GrantedAccess,     // retrieves mask of granted rights
  LPBOOL AccessStatus        // retrieves results of access check
  LPBOOL pfGenerateOnClose   // retrieves flag for audit generation
);
 

Parameters

SubsystemName
Pointer to a null-terminated string specifying the name of the subsystem calling the function. This string appears in any audit message that the function generates.
HandleId
Pointer to a unique 32-bit value representing the client's handle to the object. If the access is denied, the system ignores this value.
ObjectTypeName
Pointer to a null-terminated string specifying the type of object being created or accessed. This string appears in any audit message that the function generates.
ObjectName
Pointer to a null-terminated string specifying the name of the object being created or accessed. This string appears in any audit message that the function generates.
pSecurityDescriptor
Pointer to a SECURITY_DESCRIPTOR structure against which access is checked.
PrincipalSelfSid
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).

This parameter should be NULL if the protected object does not represent a principal.

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.

AuditType
Specifies the type of audit to be generated. This can be one of the values from the AUDIT_EVENT_TYPE enumeration type.
Flags
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.
ObjectTypeList
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, AccessCheckByTypeAndAuditAlarm fails and GetLastError returns ERROR_INVALID_PARAMETER.

ObjectTypeListLength
Specifies the number of elements in the ObjectTypeList array.
GenericMapping
Pointer to the GENERIC_MAPPING structure associated with the object for which access is being checked.
ObjectCreation
Specifies 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.
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, AccessStatus returns TRUE. Otherwise, AccessStatus returns FALSE and you can call GetLastError to get extended error information.
pfGenerateOnClose
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 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

If the PrincipalSelfSid and ObjectTypeList parameters are NULL, the AuditType parameter is AuditEventObjectAccess, and the Flags parameter is zero, AccessCheckByTypeAndAuditAlarm performs in the same way as the AccessCheckAndAuditAlarm function.

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.

AccessCheckByTypeAndAuditAlarm 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 Controlling 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 AccessCheckByTypeAndAuditAlarm function fails if the calling thread is not impersonating a client.

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

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use advapi32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Client/Server Access Control Overview, Client/Server Access Control Functions, AccessCheck, AccessCheckAndAuditAlarm, AccessCheckByType, AccessCheckByTypeResultList, AccessCheckByTypeResultListAndAuditAlarm, GENERIC_MAPPING, MapGenericMask, PRIVILEGE_SET, SECURITY_DESCRIPTOR