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.
See Also