CreateRestrictedToken-Funktion (securitybaseapi.h)

Die CreateRestrictedToken--Funktion erstellt ein neues Zugriffstoken, das eine eingeschränkte Version eines vorhandenen Zugriffstokens ist. Das eingeschränkte Token kann Sicherheits-IDs (SIDs), gelöschte Berechtigungen und eine Liste mit eingeschränkten SIDs deaktiviert haben. Weitere Informationen finden Sie unter Restricted Tokens.

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 zu einem primären oder Identitätswechseltokens. Das Token kann auch ein eingeschränktes Token sein. Das Handle muss über TOKEN_DUPLICATE Zugriff auf das Token verfügen.

[in] Flags

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

[in] DisableSidCount

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

[in, optional] SidsToDisable

Ein Zeiger auf ein Array von SID_AND_ATTRIBUTES Strukturen, die die nur deny-only-SIDs im eingeschränkten Token angeben. Das System verwendet eine nur verweigerte SID, um den Zugriff auf ein sicherungsfähiges Objekt zu verweigern. Das Fehlen einer nur verweigerten SID lässt keinen Zugriff zu.

Durch Deaktivieren einer SID wird SE_GROUP_USE_FOR_DENY_ONLY aktiviert und SE_GROUP_ENABLED und SE_GROUP_ENABLED_BY_DEFAULTdeaktiviert. Alle anderen Attribute werden ignoriert.

Nur-Verweigerungsattribute gelten für jede Kombination der SIDs eines vorhandenen Tokens, einschließlich der Benutzer-SID und Gruppen-SIDs, die das attribut SE_GROUP_MANDATORY aufweisen. Verwenden Sie zum Abrufen der SIDs, die dem vorhandenen Token zugeordnet sind, die GetTokenInformation--Funktion mit den Flags TokenUser und TokenGroups. Die Funktion ignoriert alle SIDs im Array, die nicht auch im vorhandenen Token gefunden werden.

Die Funktion ignoriert das Attributes Member der SID_AND_ATTRIBUTES Struktur.

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

[in] DeletePrivilegeCount

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

[in, optional] PrivilegesToDelete

Ein Zeiger auf ein Array von LUID_AND_ATTRIBUTES Strukturen, die die Zu löschenden Berechtigungen im eingeschränkten Token angeben.

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

Die Funktion ignoriert die Attributes Member der LUID_AND_ATTRIBUTES-Strukturen.

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

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

[in] RestrictedSidCount

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

[in, optional] SidsToRestrict

Ein Zeiger auf ein Array von SID_AND_ATTRIBUTES Strukturen, die eine Liste der einschränkenden 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änkung von 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 einem eingeschränkten Token redundante Informationen in der einschränkenden SID-Liste.

Das Attributes Member der SID_AND_ATTRIBUTES-Struktur muss null sein. Das Einschränken von SIDs ist für Zugriffsprüfungen immer aktiviert.

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

[out] NewTokenHandle

Ein Zeiger auf eine Variable, die ein Handle für das neue eingeschränkte Token empfängt. Dieses Handle verfügt über dieselben Zugriffsrechte wie ExistingTokenHandle. Das neue Token ist derselbe Typ, primären oder Identitätswechselals 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 fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

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

• Wenden Sie das Nur-Verweigern-Attribut auf SIDs im Token an, sodass 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 der einschränkenden 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, die die aktivierten SIDs des Tokens verwendet, 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 eines eigenen Tokens aufruft, muss der aufrufende Prozess nicht über die SE_ASSIGNPRIMARYTOKEN_NAME Berechtigung verfügen.

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

Anforderungen

Siehe auch

Übersicht über die Zugriffssteuerung

grundlegende Zugriffssteuerungsfunktionen

CreateProcessAsUser-

GetTokenInformation-

ImpersonateLoggedOnUser-

IsTokenRestricted-

LUID_AND_ATTRIBUTES

SID_AND_ATTRIBUTES