GetSecurityInfo-Funktion (aclapi.h)

Artikel
08/22/2023

Die GetSecurityInfo-Funktion ruft eine Kopie des Sicherheitsdeskriptors für ein Objekt ab, das durch ein Handle angegeben wird.

Syntax

DWORD GetSecurityInfo(
  [in]            HANDLE               handle,
  [in]            SE_OBJECT_TYPE       ObjectType,
  [in]            SECURITY_INFORMATION SecurityInfo,
  [out, optional] PSID                 *ppsidOwner,
  [out, optional] PSID                 *ppsidGroup,
  [out, optional] PACL                 *ppDacl,
  [out, optional] PACL                 *ppSacl,
  [out, optional] PSECURITY_DESCRIPTOR *ppSecurityDescriptor
);

Parameter

[in] handle

Ein Handle für das Objekt, aus dem Sicherheitsinformationen abgerufen werden sollen.

[in] ObjectType

SE_OBJECT_TYPE Enumerationswert, der den Typ des Objekts angibt.

[in] SecurityInfo

Eine Reihe von Bitflags, die den Typ der abzurufenden Sicherheitsinformationen angeben. Dieser Parameter kann eine Kombination der SECURITY_INFORMATION Bitflags sein.

[out, optional] ppsidOwner

Ein Zeiger auf eine Variable, die einen Zeiger auf die Besitzer-SID im Sicherheitsdeskriptor empfängt, der in ppSecurityDescriptor zurückgegeben wird. Der zurückgegebene Zeiger ist nur gültig, wenn Sie das flag OWNER_SECURITY_INFORMATION festlegen. Dieser Parameter kann NULL sein, wenn Sie die Besitzer-SID nicht benötigen.

[out, optional] ppsidGroup

Ein Zeiger auf eine Variable, die einen Zeiger auf die primäre Gruppen-SID im zurückgegebenen Sicherheitsdeskriptor empfängt. Der zurückgegebene Zeiger ist nur gültig, wenn Sie das flag GROUP_SECURITY_INFORMATION festlegen. Dieser Parameter kann NULL sein, wenn Sie die Gruppen-SID nicht benötigen.

[out, optional] ppDacl

Ein Zeiger auf eine Variable, die einen Zeiger auf die DACL im zurückgegebenen Sicherheitsdeskriptor empfängt. Der zurückgegebene Zeiger ist nur gültig, wenn Sie das flag DACL_SECURITY_INFORMATION festlegen. Dieser Parameter kann NULL sein, wenn Sie die DACL nicht benötigen.

[out, optional] ppSacl

Ein Zeiger auf eine Variable, die einen Zeiger auf die SACL im zurückgegebenen Sicherheitsdeskriptor empfängt. Der zurückgegebene Zeiger ist nur gültig, wenn Sie das flag SACL_SECURITY_INFORMATION festlegen. Dieser Parameter kann NULL sein, wenn Sie die SACL nicht benötigen.

[out, optional] ppSecurityDescriptor

Ein Zeiger auf eine Variable, die einen Zeiger auf den Sicherheitsdeskriptor des Objekts empfängt. Wenn Sie die Verwendung des Zeigers abgeschlossen haben, geben Sie den zurückgegebenen Puffer frei, indem Sie die Funktion LocalFree aufrufen.

Dieser Parameter ist erforderlich, wenn einer der Parameter ppsidOwner, ppsidGroup, ppDacl oder ppSacl nicht NULL ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.

Wenn die Funktion fehlschlägt, ist der Rückgabewert ein in WinError.h definierter Fehlercode ungleich null.

Hinweise

Wenn die Parameter ppsidOwner, ppsidGroup, ppDacl und ppSacl ungleich NULL sind und der SecurityInfo-Parameter angibt, dass sie aus dem Objekt abgerufen werden, zeigen diese Parameter auf die entsprechenden Parameter im Sicherheitsdeskriptor, der in ppSecurityDescriptor zurückgegeben wird.

Um den Besitzer, die Gruppe oder die DACL aus dem Sicherheitsdeskriptor des Objekts zu lesen, muss dem aufrufenden Prozess beim Öffnen des Handles READ_CONTROL Zugriff gewährt worden sein. Um READ_CONTROL Zugriff zu erhalten, muss der Aufrufer der Besitzer des Objekts sein, oder die DACL des Objekts muss den Zugriff gewähren.

Um die SACL aus dem Sicherheitsdeskriptor zu lesen, muss dem aufrufenden Prozess beim Öffnen des Handles ACCESS_SYSTEM_SECURITY Zugriff gewährt worden sein. Die richtige Möglichkeit, diesen Zugriff zu erhalten, besteht darin, die SE_SECURITY_NAME-Berechtigung im aktuellen Token des Aufrufers zu aktivieren, das Handle für ACCESS_SYSTEM_SECURITY Zugriff zu öffnen und dann die Berechtigung zu deaktivieren. Informationen zu den Sicherheitsauswirkungen des Aktivierens von Berechtigungen finden Sie unter Ausführen mit speziellen Berechtigungen.

Sie können die GetSecurityInfo-Funktion mit den folgenden Objekttypen verwenden:

Lokale oder Remotedateien oder Verzeichnisse in einem NTFS-Dateisystem
Named Pipes
Lokale oder Remotedrucker
Lokale oder Remote-Windows-Dienste
Netzwerkfreigaben
Registrierungsschlüssel
Semaphore, Ereignisse, Mutexe und wartebare Timer
Prozesse, Threads, Aufträge und Dateizuordnungsobjekte
Interaktive Servicefensterstationen und Desktops
Verzeichnisdienstobjekte

Diese Funktion verarbeitet keine Racebedingungen. Wenn Ihr Thread diese Funktion zu dem ungefähren Zeitpunkt aufruft, zu dem ein anderer Thread den Sicherheitsdeskriptor des Objekts ändert, kann diese Funktion fehlschlagen.

Beispiele

Ein Beispiel, das diese Funktion verwendet, finden Sie unter Suchen des Besitzers eines File-Objekts.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	aclapi.h
Bibliothek	Advapi32.lib
DLL	Advapi32.dll