ObjectPrivilegeAuditAlarm
TOC
Collapse the table of content
Expand the table of content

ObjectPrivilegeAuditAlarm function

The ObjectPrivilegeAuditAlarm function generates an audit message in the security event log. A protected server can use this function to log attempts by a client to use a specified set of privileges with an open handle to a private object. Alarms are not currently supported.

Syntax


BOOL WINAPI ObjectPrivilegeAuditAlarm(
  _In_ LPCTSTR        SubsystemName,
  _In_ LPVOID         HandleId,
  _In_ HANDLE         ClientToken,
  _In_ DWORD          DesiredAccess,
  _In_ PPRIVILEGE_SET Privileges,
  _In_ BOOL           AccessGranted
);

Parameters

SubsystemName [in]

A pointer to a null-terminated string specifying the name of the subsystem calling the function. This string appears in the audit message.

HandleId [in]

A pointer to a unique value representing the client's handle to the object.

ClientToken [in]

Identifies an access token representing the client that requested the operation. This handle must have been obtained by opening the token of a thread impersonating the client. The token must be open for TOKEN_QUERY access. The function uses this token to get the identity of the client for the audit message.

DesiredAccess [in]

Specifies an access mask indicating the privileged access types being used or whose use is being attempted. The access mask can be mapped by the MapGenericMask function so it does not contain any generic access types.

Privileges [in]

A pointer to a PRIVILEGE_SET structure containing the privileges that the client attempted to use. The names of the privileges appear in the audit message.

AccessGranted [in]

Indicates whether the client's attempt to use the privileges was successful. If this value is TRUE, the audit message indicates success. If this value is FALSE, the audit message indicates failure.

Return value

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 ObjectPrivilegeAuditAlarm function does not check the client's access to the object or check the client's access token to determine whether the privileges are held or enabled. Typically, you call the PrivilegeCheck function to determine whether the specified privileges are enabled in the access token, call the AccessCheck function to check the client's access to the object, and then call ObjectPrivilegeAuditAlarm to log the results.

The ObjectPrivilegeAuditAlarm function requires the calling process to have SE_AUDIT_NAME privilege enabled. The test for this privilege is always performed against the primary token of the calling process, not the impersonation token of the thread. This allows the calling process to impersonate a client during the call.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Winbase.h (include Windows.h)

Library

Advapi32.lib

DLL

Advapi32.dll

Unicode and ANSI names

ObjectPrivilegeAuditAlarmW (Unicode) and ObjectPrivilegeAuditAlarmA (ANSI)

See also

Client/Server Access Control Overview
Client/Server Access Control Functions
AccessCheck
AccessCheckAndAuditAlarm
MapGenericMask
ObjectCloseAuditAlarm
ObjectOpenAuditAlarm
PRIVILEGE_SET
PrivilegeCheck
PrivilegedServiceAuditAlarm

 

 

Show:
© 2016 Microsoft