CreateRestrictedToken-Funktion (securitybaseapi.h)

Artikel
03/01/2024

Die CreateRestrictedToken-Funktion erstellt ein neues Zugriffstoken , bei dem es sich um eine eingeschränkte Version eines vorhandenen Zugriffstokens handelt. Das eingeschränkte Token kann über deaktivierte Sicherheitsbezeichner (SIDs), gelöschte Berechtigungen und eine Liste einschränkender SIDs verfügen. Weitere Informationen finden Sie unter Eingeschränkte Token.

Syntax

BOOL CreateRestrictedToken(
  [in]           HANDLE               ExistingTokenHandle,
  [in]           DWORD                Flags,
  [in]           DWORD                DisableSidCount,
  [in, optional] PSID_AND_ATTRIBUTES  SidsToDisable,
  [in]           DWORD                DeletePrivilegeCount,
  [in, optional] PLUID_AND_ATTRIBUTES PrivilegesToDelete,
  [in]           DWORD                RestrictedSidCount,
  [in, optional] PSID_AND_ATTRIBUTES  SidsToRestrict,
  [out]          PHANDLE              NewTokenHandle
);

Parameter

[in] ExistingTokenHandle

Ein Handle für ein primäres Token oder Identitätswechseltoken. Das Token kann auch ein eingeschränktes Token sein. Das Handle muss TOKEN_DUPLICATE Zugriff auf das Token haben.

[in] Flags

Gibt zusätzliche Berechtigungsoptionen an. Dieser Parameter kann null oder eine Kombination der folgenden Werte sein.

Wert	Bedeutung
DISABLE_MAX_PRIVILEGE 0x1	Deaktiviert alle Berechtigungen im neuen Token mit Ausnahme der SeChangeNotifyPrivilege-Berechtigung . Wenn dieser Wert angegeben wird, werden die Parameter DeletePrivilegeCount und PrivilegesToDelete ignoriert.
SANDBOX_INERT 0x2	Wenn dieser Wert verwendet wird, überprüft das System weder AppLocker-Regeln noch wendet Softwareeinschränkungsrichtlinien an. Für AppLocker deaktiviert dieses Flag überprüfungen für alle vier Regelsammlungen: Ausführbare Datei, Windows Installer, Skript und DLL. Verwenden Sie beim Erstellen eines Setupprogramms, das extrahierte DLLs während der Installation ausführen muss, das Flag SAFER_TOKEN_MAKE_INERT in der SaferComputeTokenFromLevel-Funktion . Ein Token kann mithilfe von GetTokenInformation nach dem Vorhandensein dieses Flags abgefragt werden. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Auf Systemen, auf denen KB2532445 installiert ist, muss der Aufrufer als LocalSystem oder TrustedInstaller ausgeführt werden, sonst ignoriert das System dieses Flag. Weitere Informationen finden Sie unter "Sie können AppLocker-Regeln umgehen, indem Sie ein Office-Makro auf einem Computer mit Windows 7 oder Windows Server 2008 R2 verwenden" in der Hilfe- und Support-Wissensdatenbank unter http://support.microsoft.com/kb/2532445. Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: AppLocker wird nicht unterstützt. AppLocker wurde in Windows 7 und Windows Server 2008 R2 eingeführt.
LUA_TOKEN 0x4	Das neue Token ist ein LUA-Token. Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
WRITE_RESTRICTED 0x8	Das neue Token enthält einschränkende SIDs, die nur beim Auswerten des Schreibzugriffs berücksichtigt werden. Windows XP mit SP2 und höher: Der Wert dieser Konstanten ist 0x4. Damit eine Anwendung mit Windows XP mit SP2 und höheren Betriebssystemen kompatibel ist, sollte die Anwendung das Betriebssystem abfragen, indem sie die GetVersionEx-Funktion aufruft, um zu bestimmen, welcher Wert verwendet werden soll. Windows Server 2003 und Windows XP mit SP1 und früher: Dieser Wert wird nicht unterstützt.

[in] DisableSidCount

Gibt die Anzahl der Einträge im Array SidsToDisable an.

[in, optional] SidsToDisable

Ein Zeiger auf ein Array von SID_AND_ATTRIBUTES Strukturen, die die siDs nur für deny im eingeschränkten Token angeben. Das System verwendet eine Deny-Only-SID, um den Zugriff auf ein sicherungsfähiges Objekt zu verweigern. Das Fehlen einer Nur-Deny-SID lässt den Zugriff nicht zu.

Durch deaktivieren einer SID wird SE_GROUP_USE_FOR_DENY_ONLY aktiviert und SE_GROUP_ENABLED und SE_GROUP_ENABLED_BY_DEFAULT deaktiviert. Alle anderen Attribute werden ignoriert.

Deny-only-Attribute gelten für eine beliebige Kombination der SIDs eines vorhandenen Tokens, einschließlich der Benutzer-SID und Gruppen-SIDs, die über das attribut SE_GROUP_MANDATORY verfügen. Um die SIDs abzurufen, die dem vorhandenen Token zugeordnet sind, verwenden Sie die GetTokenInformation-Funktion mit den TokenUser- und TokenGroups-Flags. Die Funktion ignoriert alle SIDs im Array, die nicht auch im vorhandenen Token gefunden werden.

Die Funktion ignoriert das Attributes-Element der SID_AND_ATTRIBUTES-Struktur .

Dieser Parameter kann NULL sein, wenn keine SIDs deaktiviert werden sollen.

[in] DeletePrivilegeCount

Gibt die Anzahl der Einträge im Array PrivilegesToDelete an.

[in, optional] PrivilegesToDelete

Ein Zeiger auf ein Array von LUID_AND_ATTRIBUTES Strukturen, die die Berechtigungen zum Löschen im eingeschränkten Token angeben.

Die GetTokenInformation-Funktion kann mit dem TokenPrivileges-Flag verwendet werden, um die Vom vorhandenen Token gehaltenen Berechtigungen abzurufen. Die Funktion ignoriert alle Berechtigungen im Array, die nicht vom vorhandenen Token gehalten werden.

Die Funktion ignoriert die Attribute-Member der LUID_AND_ATTRIBUTES Strukturen.

Dieser Parameter kann NULL sein, wenn Sie keine Berechtigungen löschen möchten.

Wenn das aufrufende Programm zu viele Berechtigungen in diesem Array übergibt, gibt CreateRestrictedToken ERROR_INVALID_PARAMETER zurück.

[in] RestrictedSidCount

Gibt die Anzahl der Einträge im Array SidsToRestrict an.

[in, optional] SidsToRestrict

Ein Zeiger auf ein Array von SID_AND_ATTRIBUTES Strukturen, die eine Liste einschränkender SIDs für das neue Token angeben. Wenn das vorhandene Token ein eingeschränktes Token ist, ist die Liste der einschränkenden SIDs für das neue Token die Schnittmenge dieses Arrays und die Liste der einschränkenden SIDs für das vorhandene Token. Es wird keine Überprüfung durchgeführt, um doppelte SIDs zu entfernen, die im SidsToRestrict-Parameter platziert wurden. Doppelte SIDs ermöglichen es einem eingeschränkten Token, redundante Informationen in der einschränkenden SID-Liste zu enthalten.

Das Attributes-Element der SID_AND_ATTRIBUTES-Struktur muss 0 sein. Einschränkende SIDs sind immer für Zugriffsprüfungen aktiviert.

Dieser Parameter kann NULL sein, wenn Sie keine einschränkenden SIDs angeben möchten.

[out] NewTokenHandle

Ein Zeiger auf eine Variable, die ein Handle auf das neue eingeschränkte Token empfängt. Dieses Handle verfügt über dieselben Zugriffsrechte wie ExistingTokenHandle. Das neue Token ist derselbe Typ( primär oder identitätswechsel) wie das vorhandene Token. Das in NewTokenHandle zurückgegebene Handle kann dupliziert werden.

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

Die CreateRestrictedToken-Funktion kann das Token auf folgende Weise einschränken:

Wenden Sie das Attribut deny-only auf SIDs im Token an, damit sie nicht für den Zugriff auf gesicherte Objekte verwendet werden können. Weitere Informationen zum Attribut deny-only finden Sie unter SID-Attribute in einem Zugriffstoken.
Entfernen Sie Berechtigungen aus dem Token.
Geben Sie eine Liste einschränkender SIDs an, die das System verwendet, wenn es den Zugriff des Tokens auf ein sicherungsfähiges Objekt überprüft. Das System führt zwei Zugriffsprüfungen durch: eine mit den aktivierten SIDs des Tokens und eine andere mithilfe der Liste der einschränkenden SIDs. Der Zugriff wird nur gewährt, wenn beide Zugriffsprüfungen die angeforderten Zugriffsrechte zulassen.

Sie können das eingeschränkte Token in der CreateProcessAsUser-Funktion verwenden, um einen Prozess mit eingeschränkten Zugriffsrechten und Berechtigungen zu erstellen. Wenn ein Prozess CreateProcessAsUser mit einer eingeschränkten Version seines eigenen Tokens aufruft, muss der aufrufende Prozess nicht über die berechtigung SE_ASSIGNPRIMARYTOKEN_NAME verfügen.

Sie können das eingeschränkte Token in der Funktion ImpersonateLoggedOnUser verwenden.

Vorsicht Anwendungen, die eingeschränkte Token verwenden, sollten die eingeschränkte Anwendung auf anderen Desktops als dem Standarddesktop ausführen. Dies ist erforderlich, um einen Angriff durch eine eingeschränkte Anwendung mithilfe von SendMessage oder PostMessage auf uneingeschränkte Anwendungen auf dem Standarddesktop zu verhindern. Wechseln Sie bei Bedarf zwischen Desktops für Ihre Anwendungszwecke.

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ßlich Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll