CreateRestrictedToken 函数 (securitybaseapi.h)

项目
03/13/2024

CreateRestrictedToken 函数创建一个新的访问令牌，该令牌是现有访问令牌的受限版本。受限令牌可以具有禁用的安全标识符 (SID) 、已删除的权限和限制 SID 的列表。有关详细信息，请参阅受限令牌。

语法

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
);

参数

[in] ExistingTokenHandle

主令牌或模拟令牌的句柄。该令牌也可以是受限令牌。句柄必须具有对令牌TOKEN_DUPLICATE访问权限。

[in] Flags

指定其他特权选项。此参数可以是零，也可以是以下值的组合。

值	含义
DISABLE_MAX_PRIVILEGE 0x1	禁用新令牌中的所有特权， SeChangeNotifyPrivilege 特权除外。如果指定此值，将忽略 DeletePrivilegeCount 和 PrivilegesToDelete 参数。
SANDBOX_INERT 0x2	如果使用此值，则系统不会检查 AppLocker 规则或应用软件限制策略。对于 AppLocker，此标志禁用检查所有四个规则集合：可执行文件、Windows 安装程序、脚本和 DLL。创建必须在安装过程中运行提取的 DLL 的安装程序时，请使用 SaferComputeTokenFromLevel 函数中的标志SAFER_TOKEN_MAKE_INERT。可以使用 GetTokenInformation 查询令牌是否存在此标志。 Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP：在安装了KB2532445的系统上，调用方必须以 LocalSystem 或 TrustedInstaller 身份运行，否则系统会忽略此标志。有关详细信息，请参阅帮助和支持知识库 http://support.microsoft.com/kb/2532445中的“可以在运行 Windows 7 或 Windows Server 2008 R2 的计算机上使用 Office 宏来规避 AppLocker 规则”。 Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP：不支持 AppLocker。 AppLocker 是在 Windows 7 和 Windows Server 2008 R2 中引入的。
LUA_TOKEN 0x4	新令牌是 LUA 令牌。 Windows Server 2003 和 Windows XP：不支持此值。
WRITE_RESTRICTED 0x8	新令牌包含限制 SID，仅在评估写入访问权限时才会考虑这些 SID。 SP2 及更高版本的 Windows XP：此常量的值0x4。若要使应用程序与 SP2 及更高版本的操作系统的 Windows XP 兼容，应用程序应通过调用 GetVersionEx 函数来查询操作系统，以确定应使用哪个值。 Windows Server 2003 和 Windows XP SP1 及更早版本：不支持此值。

[in] DisableSidCount

指定 SidsToDisable 数组中的条目数。

[in, optional] SidsToDisable

指向 SID_AND_ATTRIBUTES 结构的数组的指针，这些结构指定受限令牌中的仅拒绝 SID。系统使用仅限拒绝的 SID 来拒绝对安全对象的访问。缺少仅限拒绝的 SID 不允许访问。

禁用 SID 会打开SE_GROUP_USE_FOR_DENY_ONLY并关闭SE_GROUP_ENABLED和SE_GROUP_ENABLED_BY_DEFAULT。将忽略所有其他属性。

仅拒绝属性适用于现有令牌的 SID 的任意组合，包括具有SE_GROUP_MANDATORY属性的用户 SID 和组 SID。若要获取与现有令牌关联的 SID，请使用具有 TokenUser 和 TokenGroups 标志的 GetTokenInformation 函数。函数将忽略数组中未在现有令牌中找到的任何 SID。

函数忽略 SID_AND_ATTRIBUTES 结构的 Attributes 成员。

如果没有要禁用 SID，此参数可以为 NULL 。

[in] DeletePrivilegeCount

指定 PrivilegesToDelete 数组中的条目数。

[in, optional] PrivilegesToDelete

指向 LUID_AND_ATTRIBUTES 结构的数组的指针，这些结构指定要在受限令牌中删除的权限。

GetTokenInformation 函数可与 TokenPrivileges 标志一起使用，以检索现有令牌拥有的权限。函数将忽略数组中不由现有令牌持有的任何特权。

函数忽略LUID_AND_ATTRIBUTES结构的 Attributes 成员。

如果不想删除任何特权，此参数可以为 NULL 。

如果调用程序在此数组中传递了过多的权限， CreateRestrictedToken 将返回ERROR_INVALID_PARAMETER。

[in] RestrictedSidCount

指定 SidsToRestrict 数组中的条目数。

[in, optional] SidsToRestrict

指向 SID_AND_ATTRIBUTES 结构的数组的指针，这些结构指定新令牌的 SID 限制列表。如果现有令牌是受限令牌，则新令牌的 SID 限制列表是此数组的交集，也是限制现有令牌的 SID 列表。不执行任何检查来删除放置在 SidsToRestrict 参数上的重复 SID。重复 SID 允许受限令牌在限制 SID 列表中包含冗余信息。

SID_AND_ATTRIBUTES 结构的 Attributes 成员必须为零。始终为访问检查启用限制 SID。

如果不想指定任何限制 SID，此参数可以为 NULL 。

[out] NewTokenHandle

指向变量的指针，该变量接收新的受限令牌的句柄。此句柄具有与 ExistingTokenHandle 相同的访问权限。新令牌的类型（主要令牌或模拟令牌）与现有令牌相同。 NewTokenHandle 中返回的句柄可以重复。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

注解

CreateRestrictedToken 函数可以通过以下方式限制令牌：

将仅拒绝属性应用于令牌中的 SID，以便它们不能用于访问受保护的对象。有关仅拒绝属性的详细信息，请参阅访问令牌中的 SID 属性。
从令牌中删除权限。
指定限制 SID 的列表，系统在检查令牌对安全对象的访问权限时会使用该列表。系统执行两个访问检查：一个使用令牌的已启用 SID，另一个使用限制 SID 列表。仅当两个访问检查都允许请求的访问权限时，才授予访问权限。

可以使用 CreateProcessAsUser 函数中的受限令牌创建具有受限访问权限和特权的进程。如果进程使用其自己的令牌的受限版本调用 CreateProcessAsUser ，则调用进程不需要具有SE_ASSIGNPRIMARYTOKEN_NAME特权。

可以在 ImpersonateLoggedOnUser 函数中使用受限令牌。

谨慎使用受限令牌的应用程序应在默认桌面以外的桌面上运行受限制的应用程序。这是防止受限制的应用程序（使用 SendMessage 或 PostMessage）攻击默认桌面上不受限制的应用程序所必需的。如有必要，请出于应用程序目的在桌面之间切换。

要求

要求	值
最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	securitybaseapi.h (包括 Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll