CreateRestrictedToken 函数 (securitybaseapi.h)
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
指定其他特权选项。 此参数可以是零,也可以是以下值的组合。
值 | 含义 |
---|---|
|
禁用新令牌中的所有特权, SeChangeNotifyPrivilege 特权除外。 如果指定此值,将忽略 DeletePrivilegeCount 和 PrivilegesToDelete 参数。 |
|
如果使用此值,则系统不会检查 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 令牌。
Windows Server 2003 和 Windows XP: 不支持此值。 |
|
新令牌包含限制 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 列表。 仅当两个访问检查都允许请求的访问权限时,才授予访问权限。
可以在 ImpersonateLoggedOnUser 函数中使用受限令牌。
要求
要求 | 值 |
---|---|
最低受支持的客户端 | Windows XP [仅限桌面应用] |
最低受支持的服务器 | Windows Server 2003 [仅限桌面应用] |
目标平台 | Windows |
标头 | securitybaseapi.h (包括 Windows.h) |
Library | Advapi32.lib |
DLL | Advapi32.dll |