SetPrivateObjectSecurityEx-Funktion (securitybaseapi.h)

Artikel
03/01/2024

Die SetPrivateObjectSecurityEx-Funktion ändert den Sicherheitsdeskriptor eines privaten Objekts, das vom Ressourcen-Manager verwaltet wird, der diese Funktion aufruft. Die SetPrivateObjectSecurityEx-Funktion verfügt über einen flags-Parameter, der angibt, ob der Ressourcen-Manager die automatische Vererbung von Zugriffssteuerungseinträgen (Access Control Entries , ACEs) unterstützt.

Syntax

BOOL SetPrivateObjectSecurityEx(
  [in]           SECURITY_INFORMATION SecurityInformation,
  [in]           PSECURITY_DESCRIPTOR ModificationDescriptor,
  [in, out]      PSECURITY_DESCRIPTOR *ObjectsSecurityDescriptor,
  [in]           ULONG                AutoInheritFlags,
  [in]           PGENERIC_MAPPING     GenericMapping,
  [in, optional] HANDLE               Token
);

Parameter

[in] SecurityInformation

Die festzulegenden Teile des Sicherheitsdeskriptors. Dieser Wert kann eine Kombination der SECURITY_INFORMATION Bitflags sein.

[in] ModificationDescriptor

Ein Zeiger auf eine SECURITY_DESCRIPTOR-Struktur . Die Teile dieses Sicherheitsdeskriptors, die durch den SecurityInformation-Parameter angegeben werden, werden auf den Sicherheitsdeskriptor ObjectsSecurityDescriptor angewendet.

[in, out] ObjectsSecurityDescriptor

Ein Zeiger auf einen Zeiger auf eine SECURITY_DESCRIPTOR-Struktur . Dieser Sicherheitsdeskriptor muss in selbstrelativer Form vorliegen. Der Arbeitsspeicher für den Sicherheitsdeskriptor muss aus dem Prozessheap (GetProcessHeap) mit der HeapAlloc-Funktion zugeordnet werden.

Bei der Eingabe ist dies der aktuelle Sicherheitsdeskriptor des privaten Objekts. Die Funktion ändert sie, um den neuen Sicherheitsdeskriptor zu erstellen. Bei Bedarf weist die SetPrivateObjectSecurityEx-Funktion zusätzlichen Arbeitsspeicher zu, um einen größeren Sicherheitsdeskriptor zu erstellen.

[in] AutoInheritFlags

Gibt die automatische Vererbung von ACEs an. Wenn der geschützte Server keine automatische Vererbung implementiert, sollte er null angeben. Andernfalls kann eine Kombination der folgenden Werte angegeben werden, die in Winnt.h definiert sind.

Wert	Bedeutung
SEF_DACL_AUTO_INHERIT 0x01	Die neue DACL (Discretionary Access Control List ) enthält ACEs, die von der DACL des übergeordneten Objekts geerbt werden, sowie alle expliziten ACEs, die in der DACL von ModificationDescriptor angegeben sind. Wenn dieses Flag nicht festgelegt ist, erbt die neue DACL keine ACEs.
SEF_SACL_AUTO_INHERIT 0x02	Die neue Systemzugriffssteuerungsliste (SACL ) enthält ACEs, die von der SACL des Sicherheitsdeskriptors geerbt werden, der dem übergeordneten Objekt zugeordnet ist, sowie alle expliziten ACEs, die in der SACL von ModificationDescriptor angegeben sind. Wenn dieses Flag nicht festgelegt ist, erbt die neue SACL keine ACEs.
SEF_AVOID_PRIVILEGE_CHECK 0x08	Die Funktion führt keine Berechtigungsüberprüfung aus. Wenn auch das flag SEF_AVOID_OWNER_CHECK festgelegt ist, kann der TokenparameterNULL sein. Verwenden Sie dieses Flag bei der Implementierung der automatischen Vererbung, um die Überprüfung der Berechtigungen für die einzelnen aktualisierten untergeordneten Elemente zu vermeiden.
SEF_AVOID_OWNER_CHECK 0x10	Die Funktion überprüft nicht die Gültigkeit des Besitzers im resultierenden ObjectsSecurityDescriptor , wie unter Hinweise beschrieben. Wenn auch das SEF_AVOID_PRIVILEGE_CHECK-Flag festgelegt ist, kann der TokenparameterNULL sein.
SEF_DEFAULT_OWNER_FROM_PARENT 0x20	Der Besitzer von ObjectsSecurityDescriptor ist standardmäßig der Besitzer des übergeordneten Objekts. Wenn dieses Flag nicht festgelegt ist, verwendet der Besitzer von ObjectsSecurityDescriptor standardmäßig den Besitzer des durch den Tokenparameter angegebenen Tokens. Der Besitzer des Tokens wird im Token selbst angegeben. Wenn der ModificationDescriptor-Parameter in beiden Fällen nicht NULL ist, wird der ObjectsSecurityDescriptor-Besitzer von ModificationDescriptor auf den Besitzer festgelegt.
SEF_DEFAULT_GROUP_FROM_PARENT 0x40	Die Gruppe von ObjectsSecurityDescriptor ist standardmäßig die Gruppe des Besitzers des übergeordneten Objekts. Wenn dieses Flag nicht festgelegt ist, wird die Gruppe von ObjectsSecurityDescriptor standardmäßig auf die Gruppe des Tokens festgelegt, das durch den Token-Parameter angegeben wird. Die Gruppe des Tokens wird im Token selbst angegeben. Wenn der ModificationDescriptor-Parameter in beiden Fällen nicht NULL ist, wird die Gruppe ObjectsSecurityDescriptor auf die Gruppe von ModificationDescriptor festgelegt.
SEF_MACL_NO_WRITE_UP 0x100	Ein Prinzipal mit einer obligatorischen Ebene, die niedriger als die des Objekts ist, kann nicht in das Objekt schreiben.
SEF_MACL_NO_READ_UP 0x200	Ein Prinzipal mit einer obligatorischen Ebene, die niedriger als die des Objekts ist, kann das Objekt nicht lesen.
SEF_MACL_NO_EXECUTE_UP 0x400	Ein Prinzipal mit einer obligatorischen Ebene, die niedriger als die des Objekts ist, kann das Objekt nicht ausführen.
SEF_AVOID_OWNER_RESTRICTION 0x1000	Alle vom Besitzer des übergeordneten Objekts angegebenen Einschränkungen, die die Fähigkeit des Aufrufers, eine DACL in ObjectsSecurityDescriptor anzugeben, einschränken würden, werden ignoriert.

[in] GenericMapping

Ein Zeiger auf eine GENERIC_MAPPING-Struktur , die die spezifischen und Standardzugriffsrechte angibt, die den einzelnen generischen Zugriffsrechten entsprechen.

[in, optional] Token

Identifiziert das Zugriffstoken für den Client, in dessen Auftrag die Sicherheit des privaten Objekts geändert wird. Dieser Parameter ist erforderlich, um sicherzustellen, dass der Client einen legitimen Wert für eine neue Besitzersicherheits-ID (SID) bereitgestellt hat. Das Token muss für TOKEN_QUERY Zugriff geöffnet sein.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion ungleich null zurück.

Wenn die Funktion fehlschlägt, wird null zurückgegeben. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Wenn der AutoInheritFlags-Parameter null ist, ist SetPrivateObjectSecurityEx mit der SetPrivateObjectSecurity-Funktion identisch.

Diese Funktion ist nur für die Verwendung durch Ressourcen-Manager vorgesehen. Um die Standardmäßige Windows-Zugriffssteuerungssemantik für das Aktualisieren von Sicherheitsbeschreibungen zu implementieren, sollte ein Ressourcen-Manager überprüfen, ob die folgenden Bedingungen erfüllt sind, bevor SetPrivateObjectSecurityEx aufgerufen wird:

Wenn der Besitzer des Objekts festgelegt wird, muss der aufrufende Prozess entweder über WRITE_OWNER Berechtigung verfügen oder der Besitzer des Objekts sein.
Wenn die DACL des Objekts festgelegt wird, muss der aufrufende Prozess entweder über WRITE_DAC Berechtigung verfügen oder der Besitzer des Objekts sein.
Wenn die SACL des Objekts festgelegt wird, muss die berechtigung SE_SECURITY_NAME für den aufrufenden Prozess aktiviert werden.

Wenn die oben genannten Bedingungen nicht erfüllt sind, schlägt ein Aufruf dieser Funktion nicht fehl. Die Standardmäßige Windows-Zugriffsrichtlinie wird jedoch nicht erzwungen.

Der Prozess, der diese Funktion aufruft, sollte keine Identität eines Clients annehmen, da Clients in der Regel nicht über die entsprechenden Berechtigungen verfügen, die für zugrunde liegende Tokenvorgänge erforderlich sind.

Wenn AutoInheritFlags das SEF_DACL_AUTO_INHERIT Bit angibt, wendet die Funktion die folgenden Regeln auf die DACL an, um den neuen Sicherheitsdeskriptor aus dem aktuellen Deskriptor zu erstellen:

Wenn das flag SE_DACL_PROTECTED nicht in den Steuerbits des aktuellen Sicherheitsdeskriptors oder des ModificationDescriptor festgelegt ist, erstellt die Funktion den Ausgabesicherheitsdeskriptor aus den geerbten ACEs des aktuellen Sicherheitsdeskriptors und nicht inheritierten ACEs von ModificationDescriptor. Das heißt, es ist unmöglich, einen geerbten ACE zu ändern, indem die Zugriffssteuerungsliste (Access Control List , ACL) für ein Objekt geändert wird. Dieses Verhalten behält die geerbten ACEs bei, da sie vom übergeordneten Container geerbt wurden.
Ein ACL-Editor sollte geerbte ACEs nicht verfügbar machen, um zu verhindern, dass sie geändert werden.
Wenn SE_DACL_PROTECTED in ModificationDescriptor festgelegt ist, wird der aktuelle Sicherheitsdeskriptor ignoriert. Der Ausgabesicherheitsdeskriptor wird als Kopie von ModificationDescriptor erstellt, wobei alle INHERITED_ACE Bits deaktiviert sind.
Im Idealfall sollte ein ACL-Editor die INHERITED_ACE Bits deaktivieren, die dem Aufrufer mitteilen, dass die acEs, die vom übergeordneten Objekt geerbt wurden, jetzt explizit für das Objekt festgelegt werden.
Wenn SE_DACL_PROTECTED im aktuellen Sicherheitsdeskriptor und nicht in ModificationDescriptor festgelegt ist, wird der aktuelle Sicherheitsdeskriptor ignoriert. Der Ausgabesicherheitsdeskriptor wird als Kopie von ModificationDescriptor erstellt. Es liegt in der Verantwortung des Aufrufers sicherzustellen, dass für die richtigen ACEs das INHERITED_ACE Bit aktiviert ist.

Wenn AutoInheritFlags das SEF_SACL_AUTO_INHERIT Bit angibt, wendet die Funktion ähnliche Regeln auf die neue SACL an.

Für DACLs und SACLs werden bestimmte ACEs-Typen in der Eingabe ObjectsSecurityDescriptor und in ModificationDescriptor durch zwei ACEs in der Ausgabe ObjectsSecurityDescriptor ersetzt. Insbesondere führt ein vererbbarer ACE, der mindestens eines der folgenden zugeordneten Elemente enthält, zu zwei ACEs in der ObjectsSecurityDescriptor-Ausgabe. Zu den zuordnungsfähigen Elementen gehören:

Generische Zugriffsrechte in der ACCESS_MASK-Struktur
Creator Owner SID oder Creator Group SID als ACE-Antragstellerbezeichner

ACEs mit einem dieser zuordnungsfähigen Elemente führen zu den folgenden beiden ACEs in der ObjectsSecurityDescriptor-Ausgabe:

Ein ACE, bei dem es sich um eine Kopie des Originals handelt, aber das flag INHERIT_ONLY festgelegt ist
Ein ACE, in dem das INHERITED_ACE Bit aktiviert ist und die generischen Elemente bestimmten Elementen zugeordnet werden:
- Generische Zugriffsrechte werden durch die entsprechenden Standard- und spezifischen Zugriffsrechte ersetzt, die in der Eingabe GenericMapping angegeben sind.
- Creator Owner SID wird durch den Besitzer in der Ausgabe SecurityDescriptor ersetzt.
- Die Erstellergruppen-SID wird durch die Gruppe in der Ausgabe SecurityDescriptor ersetzt.

Wenn AutoInheritFlags das SEF_AVOID_PRIVILEGE_CHECK Bit nicht angibt, wird die Gültigkeitsprüfung des Besitzers gemäß den folgenden Regeln durchgeführt. Der Besitzer in ModificationDescriptor:

Muss eine rechtlich gebildete SID sein
Muss mit dem TokenUser in Token übereinstimmen.

oder

Muss mit einer Gruppe in tokenGroups in Token übereinstimmen, wobei die Attribute in der Gruppe:
- Einschließen von SE_GROUP_OWNER
- Einschließen von SE_GROUP_USE_FOR_DENY_ONLY

Ein Ressourcen-Manager, der den Besitzer für eine Teilstruktur von Objekten festlegt, kann den Mehraufwand für die Überprüfung der Gültigkeit redundanter Besitzer vermeiden. Wenn der Besitzer in ModificationDescriptor und Token für iterative Aufrufe dieser Funktion identisch bleiben, kann das SEF_AVOID_PRIVILEGE_CHECK Bit in AutoInheritFlags für Aufrufe nach einem ersten Aufruf festgelegt werden, in dem die Gültigkeitsprüfung des Besitzers durchgeführt wird. Aufrufer, die keinen Zugriff auf das Token des Clients haben, der letztendlich den Besitzer festlegt, sollten auch die Überprüfung der Besitzer überspringen.

Hinweis Das SEF_AVOID_PRIVILEGE_CHECK Bit, das in der SetPrivateObjectSecurityEx-Funktion verwendet wird, entspricht dem SEF_AVOID_OWNER_CHECK Bit, das in der CreatePrivateObjectSecurityEx-Funktion verwendet wird.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	securitybaseapi.h (Einschließen von Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll