AccessCheckAndAuditAlarm

AccessCheckAndAuditAlarm

The AccessCheckAndAuditAlarm function performs an access validation and generates corresponding audit messages. An application can also use this function to determine whether necessary privileges are held by a client process. This function is generally used by a server application impersonating a client process. Alarms are not supported in the current version of Windows NT.

BOOL AccessCheckAndAuditAlarm(

LPCTSTR SubsystemName,	// address of string for subsystem name
LPVOID HandleId,	// address of handle identifier
LPTSTR ObjectTypeName,	// address of string for object type
LPTSTR ObjectName,	// address of string for object name
PSECURITY_DESCRIPTOR SecurityDescriptor,	// address of security descriptor
DWORD DesiredAccess,	// mask for requested access rights
PGENERIC_MAPPING GenericMapping,	// address of GENERIC_MAPPING
BOOL ObjectCreation,	// object-creation flag
LPDWORD GrantedAccess,	// address of mask for granted rights
LPBOOL AccessStatus,	// address of flag for results
LPBOOL pfGenerateOnClose	// pointer to flag for audit generation
);

Parameters

SubsystemName

Pointer to a null-terminated string specifying the name of the subsystem calling the function ¾ for example, "DEBUG" or "WIN32."

HandleId

Points to a unique 32-bit value representing the client's handle to the object. If the access is denied, this value is ignored and may be reused.

ObjectTypeName

Points to a null-terminated string specifying the type of object being created or accessed. This string appears in the audit log for the object.

ObjectName

Points to a null-terminated string specifying the name of the object being created or accessed. This string appears in the audit log for the object.

SecurityDescriptor

Points to the SECURITY_DESCRIPTOR structure against which access is checked.

DesiredAccess

Specifies an access mask giving the requested access rights. This mask must have been mapped to contain no generic access rights by the MapGenericMask function.

GenericMapping

Points to the GENERIC_MAPPING structure associated with the type of object being examined.

ObjectCreation

Specifies a flag that determines whether the calling application will create a new object when access is granted. If this flag is TRUE, the application creates a new object; if it is FALSE, the application opens an existing object.

GrantedAccess

Points to a buffer that receives an access mask indicating which access rights were granted, if the function succeeds.

AccessStatus

Points to a flag that the function sets to indicate the success or failure of the access check. If access is granted, this flag is TRUE; otherwise, it is FALSE.

pfGenerateOnClose

Pointer to a flag set by the audit-generation routine when the function returns. This flag must be passed 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

The AccessCheckAndAuditAlarm function compares the specified security descriptor with the impersonation access token of the calling process and indicates whether access is granted or denied. If access is granted, the requested access mask becomes the granted access mask for the object. This function also generates any necessary audit messages as a result of the access attempt.

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