AccessCheckAndAuditAlarmA-Funktion (winbase.h)

Artikel
08/27/2023

Die AccessCheckAndAuditAlarm-Funktion bestimmt, ob ein Sicherheitsdeskriptor dem Client, der vom aufrufenden Thread identitätswechselt wird, einen angegebenen Satz von Zugriffsrechten gewährt. Wenn die Sicherheitsbeschreibung über eine SACL mit ACEs verfügt, die für den Client gelten, generiert die Funktion alle erforderlichen Überwachungsmeldungen im Sicherheitsereignisprotokoll.

Alarme werden derzeit nicht unterstützt.

Syntax

BOOL AccessCheckAndAuditAlarmA(
  [in]           LPCSTR               SubsystemName,
  [in, optional] LPVOID               HandleId,
  [in]           LPSTR                ObjectTypeName,
  [in, optional] LPSTR                ObjectName,
  [in]           PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in]           DWORD                DesiredAccess,
  [in]           PGENERIC_MAPPING     GenericMapping,
  [in]           BOOL                 ObjectCreation,
  [out]          LPDWORD              GrantedAccess,
  [out]          LPBOOL               AccessStatus,
  [out]          LPBOOL               pfGenerateOnClose
);

Parameter

[in] SubsystemName

Ein Zeiger auf eine NULL-beendete Zeichenfolge, die den Namen des Subsystems angibt, das die Funktion aufruft. Diese Zeichenfolge wird in jeder Überwachungsmeldung angezeigt, die von der Funktion generiert wird.

[in, optional] HandleId

Ein Zeiger auf einen eindeutigen Wert, der das Handle des Clients auf das Objekt darstellt. Wenn der Zugriff verweigert wird, ignoriert das System diesen Wert.

[in] ObjectTypeName

Ein Zeiger auf eine NULL-beendete Zeichenfolge, die den Typ des Objekts angibt, auf das erstellt oder zugegriffen wird. Diese Zeichenfolge wird in jeder Überwachungsmeldung angezeigt, die von der Funktion generiert wird.

[in, optional] ObjectName

Ein Zeiger auf eine NULL-beendete Zeichenfolge, die den Namen des Objekts angibt, auf das erstellt oder zugegriffen wird. Diese Zeichenfolge wird in jeder Überwachungsmeldung angezeigt, die von der Funktion generiert wird.

[in] SecurityDescriptor

Ein Zeiger auf die SECURITY_DESCRIPTOR-Struktur , für die der Zugriff überprüft wird.

[in] DesiredAccess

Zugriffsmaske , die die zu überprüfenden Zugriffsrechte angibt. Diese Maske muss von der MapGenericMask-Funktion zugeordnet worden sein, um keine generischen Zugriffsrechte zu enthalten.

Wenn dieser Parameter MAXIMUM_ALLOWED ist, legt die Funktion die Zugriffsmaske GrantedAccess fest, um die maximalen Zugriffsrechte anzugeben, die der Sicherheitsdeskriptor dem Client zulässt.

[in] GenericMapping

Ein Zeiger auf die GENERIC_MAPPING Struktur, die dem Objekt zugeordnet ist, für das der Zugriff überprüft wird.

[in] ObjectCreation

Gibt ein Flag an, das bestimmt, ob die aufrufende Anwendung ein neues Objekt erstellt, wenn der Zugriff gewährt wird. Der Wert TRUE gibt an, dass die Anwendung ein neues Objekt erstellt. Der Wert FALSE gibt an, dass die Anwendung ein vorhandenes Objekt öffnet.

[out] GrantedAccess

Ein Zeiger auf eine Zugriffsmaske , die die gewährten Zugriffsrechte empfängt. Wenn AccessStatus auf FALSE festgelegt ist, legt die Funktion die Zugriffsmaske auf Null fest. Wenn die Funktion fehlschlägt, wird die Zugriffsmaske nicht festgelegt.

[out] AccessStatus

Ein Zeiger auf eine Variable, die die Ergebnisse der Zugriffsprüfung empfängt. Wenn der Sicherheitsdeskriptor die angeforderten Zugriffsrechte für den Client zulässt, wird AccessStatus auf TRUE festgelegt. Andernfalls ist AccessStatus auf FALSE festgelegt.

[out] pfGenerateOnClose

Ein Zeiger auf ein Flag, das von der Überwachungsgenerierungsroutine festgelegt wird, wenn die Funktion zurückgibt. Übergeben Sie dieses Flag an die ObjectCloseAuditAlarm-Funktion , wenn das Objekthandle geschlossen ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Weitere Informationen finden Sie in der Übersicht über die Funktionsweise von AccessCheck .

Die AccessCheckAndAuditAlarm-Funktion erfordert, dass der aufrufende Prozess die berechtigung SE_AUDIT_NAME aktiviert hat. Der Test für diese Berechtigung wird für das primäre Token des aufrufenden Prozesses durchgeführt, nicht für das Identitätswechseltoken des Threads.

Die AccessCheckAndAuditAlarm-Funktion schlägt fehl, wenn der aufrufende Thread keine Identität eines Clients angreift.

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (einschließlich Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll