SeFilterToken-Funktion (ntifs.h)

Artikel
10/04/2023

Die SeFilterToken-Routine erstellt ein neues Zugriffstoken, das eine eingeschränkte Version eines vorhandenen Zugriffstokens ist.

Syntax

NTSTATUS SeFilterToken(
  [in]           PACCESS_TOKEN     ExistingToken,
  [in]           ULONG             Flags,
  [in, optional] PTOKEN_GROUPS     SidsToDisable,
  [in, optional] PTOKEN_PRIVILEGES PrivilegesToDelete,
  [in, optional] PTOKEN_GROUPS     RestrictedSids,
                 PACCESS_TOKEN     *FilteredToken
);

Parameter

[in] ExistingToken

Zeiger auf ein primäres Token oder ein Identitätswechseltoken. Das Token kann auch ein eingeschränktes Token sein. Dieses Token muss bereits für TOKEN_DUPLICATE Zugriff geöffnet sein. Dieser Zeiger kann aus einem vorhandenen Tokenhandle abgerufen werden, indem ObReferenceObjectByHandle aufgerufen und TOKEN_DUPLICATE als DesiredAccess-Typ angegeben wird.

[in] Flags

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

Wert	Bedeutung
DISABLE_MAX_PRIVILEGE	Deaktiviert alle Berechtigungen im neuen Token außer SE_CHANGE_NOTIFY_PRIVILEGE. Wenn dieser Wert angegeben wird, wird der PrivilegesToDelete-Parameter ignoriert.
SANDBOX_INERT	Speichert das TOKEN_SANDBOX_INERT-Flag im Token.

[in, optional] SidsToDisable

Zeiger auf eine TOKEN_GROUPS-Struktur, die ein Array von SID_AND_ATTRIBUTES Strukturen enthält, die die siDs nur für die Ablehnung im eingeschränkten Token angeben. Das System verwendet eine nur verweigernde SID, um den Zugriff auf ein sicherungsfähiges Objekt zu verweigern. Das Fehlen einer Nur-Ablehnungs-SID lässt keinen Zugriff zu.

Das Deaktivieren einer SID aktiviert SE_GROUP_USE_FOR_DENY_ONLY und deaktiviert SE_GROUP_ENABLED und SE_GROUP_ENABLED_BY_DEFAULT. Alle anderen Attribute werden ignoriert.

Nur-Verweigern-Attribute gelten für jede 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, rufen Sie SeQueryInformationToken mit den Flags TokenUser und TokenGroups auf. SeFilterToken ignoriert alle SIDs im Array, die nicht auch im vorhandenen Token gefunden werden.

SeFilterToken ignoriert die Attributes-Elemente der SID_AND_ATTRIBUTES-Strukturen.

Dieser Parameter ist optional und kann NULL sein.

[in, optional] PrivilegesToDelete

Zeiger auf eine TOKEN_PRIVILEGES-Struktur, die ein Array von LUID_AND_ATTRIBUTES Strukturen enthält, die die zu löschenden Berechtigungen im eingeschränkten Token angeben.

Um die Berechtigungen des vorhandenen Tokens abzurufen, rufen Sie SeQueryInformationToken mit dem TokenPrivileges-Flag auf. SeFilterToken ignoriert alle Berechtigungen im Array, die nicht vom vorhandenen Token gehalten werden.

SeFilterToken ignoriert die Attributes-Elemente der LUID_AND_ATTRIBUTES-Strukturen.

Dieser Parameter ist optional und kann NULL sein.

[in, optional] RestrictedSids

Zeiger auf eine TOKEN_GROUPS-Struktur, die ein Array von SID_AND_ATTRIBUTES Strukturen enthält, 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.

Die Attributes-Member der SID_AND_ATTRIBUTES-Strukturen müssen null sein. Einschränkende SIDs sind immer für Zugriffsprüfungen aktiviert.

Dieser Parameter ist optional und kann NULL sein.

FilteredToken

Zeiger auf eine vom Aufrufer zugewiesene Variable, die die Adresse des neuen eingeschränkten Tokens empfängt. Das neue Token ist derselbe Typ (primär oder identitätswechsel) wie das vorhandene Token.

Rückgabewert

Wenn mindestens einer der Parameterwerte ungültig war, gibt SeFilterToken STATUS_INVALID_PARAMETER zurück. (Dieser Wert wird zurückgegeben, wenn das Zieltoken kein Identitätswechseltoken ist.) Andernfalls gibt SeFilterToken STATUS_SUCCESS zurück.

Hinweise

SeFilterToken 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 Deny-only-Attribut finden Sie unter SID-Attribute in einem Zugriffstoken in der Microsoft Windows SDK-Dokumentation.
Entfernen Sie Berechtigungen aus dem Token.
Geben Sie eine Liste einschränkender SIDs an, die das System verwendet, wenn der Tokenzugriff auf ein sicherungsfähiges Objekt überprüft wird. Das System führt zwei Zugriffsprüfungen durch: eine mit den aktivierten SIDs des Tokens und eine mit der Liste der einschränkenden SIDs. Der Zugriff wird nur gewährt, wenn beide Zugriffsprüfungen die angeforderten Zugriffsrechte zulassen.

Das eingeschränkte Token kann zusammen mit SeCreateClientSecurity und SeImpersonateClientEx verwendet werden, um einen Prozess zu erstellen, der über eingeschränkte Zugriffsrechte und Berechtigungen verfügt.

Weitere Informationen zur Sicherheit und Zugriffssteuerung finden Sie unter Windows-Sicherheitsmodell für Treiberentwickler und in der Dokumentation zu diesen Themen im Windows SDK.

Wenn das in NewToken zurückgegebene Token nicht mehr benötigt wird, geben Sie es durch Aufrufen von ObDereferenceObject frei.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	< DISPATCH_LEVEL