AccessCheckAndAuditAlarm

	BOOL AccessCheckAndAuditAlarm(SubsystemName, HandleId, ObjectTypeName, ObjectName, SecurityDescriptor, DesiredAccess, GenericMapping, ObjectCreation, GrantedAccess, AccessStatus, pfGenerateOnClose)
	LPTSTR SubsystemName;
	LPVOID HandleId;
	LPTSTR ObjectTypeName;
	LPTSTR ObjectName;
	PSECURITY_DESCRIPTOR SecurityDescriptor;
	DWORD DesiredAccess;
	PGENERIC_MAPPING GenericMapping;
	BOOL ObjectCreation;
	LPDWORD GrantedAccess;
	LPBOOL AccessStatus;
	LPBOOL pfGenerateOnClose;

The AccessCheckAndAuditAlarm function performs an access validation and generates the corresponding audit and alarm messages. It will also, optionally, determine whether necessary privileges are held by the subject.

This service may only be used by a server application that chooses to impersonate its client and thereby specifies the client security context implicitly.

Parameters

SubsystemName

Pointer to a string that is the name of the subsystem calling the function.

HandleId

A unique value representing the client's handle to the object. This value is ignored (and may be re-used) if the access is denied.

ObjectTypeName

Pointer to a string that is the name of the type of object being created or accessed.

ObjectName

Pointer to a string that is the name of the object being created or accessed.

SecurityDescriptor

Pointer to the security descriptor against which access is to be checked.

DesiredAccess

The desired access mask. This mask must have been previously mapped to contain no generic accesses.

GenericMapping

Pointer to the generic mapping associated with the type of object being examined.

ObjectCreation

Boolean flag that specifies, if TRUE, that the function will create a new object if access is granted. A value of FALSE specifies that the function will open an existing object if access is granted.

GrantedAccess

Pointer to a variable that the function will fill, if the function is successful, with an access mask indicating which accesses were actually granted.

AccessStatus

Pointer to a Boolean variable that the function sets to indicate the success or failure of the access check.

If access is granted, the function sets the variable to the value STATUS_SUCCESS. If access is denied, the function sets the variable to STATUS_ACCESS_DENIED or, when mandatory access controls are implemented, to STATUS_OBJECT_NOT_FOUND.

pfGenerateOnClose

Pointer to a Boolean variable that the audit generation routine sets. This Boolean must be passed to ObjectCloseAuditAlarm when the object handle is closed.

Return Value

The return value is TRUE if the function was successful, or FALSE if an error occurred. Use the GetLastError function to obtain extended error information.

Comments

This routine compares the input security descriptor against the caller's impersonation token and indicates if access is granted or denied. If access is granted, then the desired access mask becomes the granted access mask for the object. The semantics of the access check routine is described in the DSA Security Architecture workbook.

This routine will also generate any necessary audit messages as a result of the access attempt.

This function requires the caller to have SeSecurityPrivilege privilege. The test for this privilege is always against the primary token of the calling process, not the impersonation token of the thread.