Checking Access to Private Objects

A protected server application must check a client's access rights before allowing the client to access a protected private object. To do this, the server passes an impersonation token, a security descriptor, and a set of requested access rights to AccessCheck. The access control entries (ACEs) in the security descriptor's DACL specify the access rights allowed or denied to various trustees. The AccessCheck function compares the trustee in each ACE to the trustees identified in the impersonation token. For a description of the algorithm used to grant or deny access, see How DACLs Control Access to an Object.

The AccessCheckAndAuditAlarm function performs a similar access check. In addition, it generates audit records in the security event log depending on the SACL in the security descriptor.

The AccessCheckByType and AccessCheckByTypeAndAuditAlarm functions are similar to AccessCheck and AccessCheckAndAuditAlarm except that they allow you to check access to the subobjects of an object, such as property sets or properties. The AccessCheckByTypeResultList and AccessCheckByTypeResultListAndAuditAlarm functions are also similar to AccessCheck except that they provide the access check results for each subobject in a hierarchy of the object's properties and property sets. These functions use the OBJECT_TYPE_LIST structure to describe the hierarchy of objects for which access is checked. The functions that generate an audit message use the AUDIT_EVENT_TYPE enumeration type to indicate whether the object being checked is a directory service object. For more information about the hierarchy of an object and its subobjects, see ACEs to Control Access to an Object's Properties.

The requested access rights passed to the AccessCheck and AccessCheckAndAuditAlarm functions must not include any generic access rights. The server can use the MapGenericMask function to convert any generic access rights to the corresponding specific and standard rights according to the mapping specified in the GENERIC_MAPPING structure.

The AreAllAccessesGranted and AreAnyAccessesGranted functions compare a requested access mask with a granted access mask.

For sample code that uses the AccessCheck function, see Verifying Client Access with ACLs in C++.

The ConvertToAutoInheritPrivateObjectSecurity function creates and returns a security descriptor in a format that allows the automatic propagation of inheritable ACEs. This security descriptor contains all of the ACEs, inherited and noninherited, in the current security descriptor and is in self-relative format. The ConvertToAutoInheritPrivateObjectSecurity function determines whether the ACEs are inherited or noninherited by comparing all of the ACEs in the current security descriptor with all of the ACEs in its parent security descriptor. There may not be a one-to-one correspondence between the two groups of ACEs. For instance, an ACE that allows read/write permission can be equivalent to two ACEs: an ACE that allows read permission and an ACE that allows write permission. A parent security descriptor may not be supplied when the current security descriptor is the parent.