GetNamedSecurityInfoA-Funktion (aclapi.h)

Artikel
02/26/2024

Die GetNamedSecurityInfo-Funktion ruft eine Kopie des Sicherheitsdeskriptors für ein mit dem Namen angegebenes Objekt ab.

Syntax

DWORD GetNamedSecurityInfoA(
  [in]            LPCSTR               pObjectName,
  [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] pObjectName

Ein Zeiger auf eine NULL-Zeichenfolge, die den Namen des Objekts angibt, aus dem Sicherheitsinformationen abgerufen werden sollen. Beschreibungen der Zeichenfolgenformate für die verschiedenen Objekttypen finden Sie unter SE_OBJECT_TYPE.

[in] ObjectType

Gibt einen Wert aus der SE_OBJECT_TYPE-Enumeration an, der den Typ des Vom pObjectName-Parameter benannten 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 oder NULL zurückgegeben wird, wenn der Sicherheitsdeskriptor keine Besitzer-SID aufweist. Der zurückgegebene Zeiger ist nur gültig, wenn Sie das flag OWNER_SECURITY_INFORMATION festlegen. Außerdem kann dieser Parameter 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 oder NULL empfängt, wenn der Sicherheitsdeskriptor keine Gruppen-SID aufweist. Der zurückgegebene Zeiger ist nur gültig, wenn Sie das GROUP_SECURITY_INFORMATION-Flag festlegen. Außerdem kann dieser Parameter 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 oder NULL empfängt, wenn der Sicherheitsdeskriptor keine DACL aufweist. Der zurückgegebene Zeiger ist nur gültig, wenn Sie das DACL_SECURITY_INFORMATION-Flag festlegen. Außerdem kann dieser Parameter 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 oder NULL empfängt, wenn der Sicherheitsdeskriptor keine SACL aufweist. Der zurückgegebene Zeiger ist nur gültig, wenn Sie das flag SACL_SECURITY_INFORMATION festlegen. Außerdem kann dieser Parameter NULL sein, wenn Sie die SACL nicht benötigen.

[out, optional] ppSecurityDescriptor

Ein Zeiger auf eine Variable, die einen Zeiger auf die Sicherheitsbeschreibung 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 nonzero-Fehlercode, der in WinError.h definiert ist.

Hinweise

Wenn einer der Parameter ppsidOwner, ppsidGroup, ppDacl oder ppSacl nicht NULL ist 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. Wenn der Sicherheitsdeskriptor die angeforderten Informationen nicht enthält, wird der entsprechende Parameter auf NULL festgelegt.

Um den Besitzer, die Gruppe oder die DACL aus der Sicherheitsbeschreibung des Objekts zu lesen, muss die DACL des Objekts READ_CONTROL Zugriff auf den Aufrufer gewähren, oder der Aufrufer muss der Besitzer des Objekts sein.

Zum Lesen der Systemzugriffssteuerungsliste des -Objekts muss die SE_SECURITY_NAME-Berechtigung für den aufrufenden Prozess aktiviert sein. Informationen zu den Sicherheitsauswirkungen des Aktivierens von Berechtigungen finden Sie unter Ausführen mit speziellen Berechtigungen.

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

Lokale oder Remotedateien oder Verzeichnisse auf einem NTFS-Dateisystem
Lokale oder Remotedrucker
Lokale oder Windows-Remotedienste
Netzwerkfreigaben
Registrierungsschlüssel
Semaphore, Ereignisse, Mutexes und wartebare Timer
Dateizuordnungsobjekte
Verzeichnisdienstobjekte

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

Diese Funktion überträgt Informationen im Klartext. Die von dieser Funktion übertragenen Informationen werden signiert, es sei denn, die Signatur wurde für das System deaktiviert, aber es wird keine Verschlüsselung durchgeführt.

Weitere Informationen zum Steuern des Zugriffs auf Objekte über Benutzerkonten, Gruppenkonten oder Anmeldesitzungen finden Sie unter Steuern des Zugriffs auf ein Objekt durch DACLs.

Beispiele

Ein Beispiel, das GetNamedSecurityInfo verwendet, finden Sie unter Ändern der ACLs eines Objekts.

Hinweis

Der aclapi.h-Header definiert GetNamedSecurityInfo als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

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