ZwDuplicateToken 函数 (ntifs.h)

  • 项目

ZwDuplicateToken 函数创建与现有令牌重复的新访问令牌的句柄。 此函数可以创建主令牌或模拟令牌。

语法

NTSYSAPI NTSTATUS ZwDuplicateToken(
  [in]  HANDLE             ExistingTokenHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  BOOLEAN            EffectiveOnly,
  [in]  TOKEN_TYPE         TokenType,
  [out] PHANDLE            NewTokenHandle
);

参数

[in] ExistingTokenHandle

使用TOKEN_DUPLICATE访问权限打开的现有访问令牌的句柄。 此参数是必需的，不能为 NULL。

[in] DesiredAccess

指定新令牌请求的访问权限的位掩码。 ZwDuplicateToken 将请求的访问权限与现有令牌的任意访问控制列表 (DACL) 进行比较，以确定向新令牌授予或拒绝了哪些权限。 若要请求与现有令牌相同的访问权限，请指定零。 若要请求对调用方有效的所有访问权限，请指定MAXIMUM_ALLOWED。 此参数是可选的，可以是零、MAXIMUM_ALLOWED或以下一个或多个值的按位 OR 组合：

值 含义
DELETE 删除对象所必需的。
READ_CONTROL 需要读取对象的 DACL 和所有权信息。 有关访问 SACL) (系统访问控制列表，请参阅下表后面的ACCESS_SYSTEM_SECURITY。
WRITE_DAC 需要更改对象的 DACL 信息。
WRITE_OWNER 需要更改对象的安全描述符中的所有权信息 (SECURITY_DESCRIPTOR) 。
ACCESS_SYSTEM_SECURITY 在对象的 ACL 中获取或设置 SACL 所必需的。 仅当调用线程的访问令牌中启用了SE_SECURITY_NAME特权时，操作系统才向新令牌授予此权限。
STANDARD_RIGHTS_READ 当前定义为等于 READ_CONTROL。
STANDARD_RIGHTS_WRITE 当前定义为等于 READ_CONTROL。
STANDARD_RIGHTS_EXECUTE 当前定义为等于 READ_CONTROL。
STANDARD_RIGHTS_REQUIRED 合并 DELETE、READ_CONTROL、WRITE_DAC 和 WRITE_OWNER 访问。
STANDARD_RIGHTS_ALL 合并 DELETE、READ_CONTROL、WRITE_DAC、WRITE_OWNER 和 SYNCHRONIZE 访问。 但是，SYNCHRONIZE 值不适用于令牌对象。 因此，STANDARD_RIGHTS_ALL在功能上等效于 STANDARD_RIGHTS_REQUIRED。
TOKEN_ADJUST_DEFAULT 需要更改访问令牌的默认所有者、主组或 DACL。
TOKEN_ADJUST_GROUPS 需要调整访问令牌中组的属性。
TOKEN_ADJUST_PRIVILEGES 在访问令牌中启用或禁用特权所必需的。
TOKEN_ADJUST_SESSIONID 需要 (访问令牌的 SID) 调整会话 ID。 仅当在调用线程的访问令牌中启用了SE_TCB_NAME特权时，操作系统才向新令牌授予此权限。
TOKEN_ASSIGN_PRIMARY 需要将主令牌附加到进程。 仅当在调用线程的访问令牌中启用了SE_ASSIGNPRIMARYTOKEN_NAME特权时，操作系统才向新令牌授予此权限。
TOKEN_DUPLICATE 需要复制访问令牌。 请注意，给定的 ExistingTokenHandle 令牌必须包含此权限才能成功使用此例程。
TOKEN_EXECUTE 将STANDARD_RIGHTS_EXECUTE和TOKEN_IMPERSONATE组合在一起。
TOKEN_IMPERSONATE 需要将模拟访问令牌附加到进程。
TOKEN_QUERY 查询访问令牌所必需的。
TOKEN_QUERY_SOURCE 查询访问令牌的源所必需的。
TOKEN_READ 将STANDARD_RIGHTS_READ和TOKEN_QUERY组合在一起。
TOKEN_WRITE 将STANDARD_RIGHTS_WRITE、TOKEN_ADJUST_PRIVILEGES、TOKEN_ADJUST_GROUPS和TOKEN_ADJUST_DEFAULT组合在一起。
TOKEN_ALL_ACCESS 合并令牌的所有可能的令牌访问权限。

有关其他信息，请参阅Windows SDK中 Access-Token 对象的访问权限。 请注意，访问令牌不支持 SYNCHRONIZE 权限。

[in] ObjectAttributes

指向描述新令牌请求属性 的OBJECT_ATTRIBUTES 结构的指针。 ObjectAttributes 参数是可选的，可以为 NULL。 如果 ObjectAttributes 参数为 NULL，或者 ObjectAttributes 参数指向的结构的 SecurityDescriptor 成员为 NULL，则新令牌将收到默认安全描述符，并且无法继承新令牌句柄。 在这种情况下，将从调用方令牌中存储的用户组、主组和 DACL 信息创建此默认安全描述符。

当 TokenType 参数设置为 TokenImpersonation 时：

  • ObjectAttributes 参数可用于指定新令牌的模拟级别。 这可以通过将 ObjectAttributes-SecurityQualityOfService.ImpersonationLevel >设置为适当的SECURITY_IMPERSONATION_LEVEL枚举值来实现。 有关详细信息，请参阅 SECURITY_QUALITY_OF_SERVICE。

  • 如果现有令牌是模拟令牌，并且 ObjectAttributes 参数不提供任何模拟信息，则新令牌的模拟级别将设置为现有令牌的模拟级别。

  • 如果现有令牌是主令牌，并且未提供模拟级别信息，则新的模拟令牌将具有 SECURITY_IMPERSONATION_LEVEL 模拟级别。

[in] EffectiveOnly

一个布尔值，该值指示是应将整个现有令牌复制到新令牌中，还是仅应将当前启用的有效 () 令牌的一部分。 如果设置为 TRUE，则仅复制源令牌的当前启用部分。 如果设置为 FALSE，则会复制整个现有令牌。 这为受保护子系统的调用方提供了一种限制向受保护子系统提供哪些可选组和特权的方法。 例如，如果 EffectiveOnly 为 TRUE，则调用方可以复制令牌，但删除管理员组和 SeTcbPrivilege 权限。 然后，生成的令牌可以传递到 CreateProcessAsUser) (子进程，这将限制子进程可以执行的操作。 此参数是必需的。

[in] TokenType

指定 TOKEN_TYPE 枚举中的以下值之一。

值 含义
TokenPrimary 新令牌是主令牌。 如果现有令牌是模拟令牌，则现有模拟令牌必须具有由 SecurityImpersonation 或 SecurityDelegation 的 ObjectAttributes 参数) 提供的模拟级别 (。 否则， ZwDuplicateToken 返回STATUS_BAD_IMPERSONATION_LEVEL返回。
TokenImpersonation 新令牌是模拟令牌。 如果现有令牌是模拟令牌，则新令牌的 ObjectAttributes 参数) 提供的所请求的模拟级别 (不得大于现有令牌的模拟级别。 否则， ZwDuplicateToken 返回STATUS_BAD_IMPERSONATION_LEVEL。

TokenType 参数是必需的，不能为 NULL。

[out] NewTokenHandle

指向调用方分配的变量（类型为 HANDLE）的指针，该变量接收新令牌的句柄。 此参数是必需的，不能为 NULL。

返回值

如果调用成功，ZwDuplicateToken 将返回STATUS_SUCCESS。 可能的错误返回代码包括以下内容：

返回代码 说明
STATUS_ACCESS_VIOLATION 出现内存访问冲突。 例如，如果以前的模式是用户模式，并且提供了无效的用户模式内存， 则 ZwDuplicateToken 返回STATUS_ACCESS_VIOLATION。
STATUS_INSUFFICIENT_RESOURCES 无法分配足够的内存来复制新令牌。
STATUS_INVALID_PARAMETER 检测到无效的参数。
STATUS_BAD_IMPERSONATION_LEVEL 新令牌请求的模拟级别大于现有令牌的模拟级别。
STATUS_ACCESS_DENIED 如果 ZwDuplicateToken 无法访问 ExistingTokenHandle，则返回STATUS_ACCESS_DENIED。 如果现有令牌没有TOKEN_DUPLICATE访问权限，则会发生这种情况。
STATUS_INVALID_HANDLE 如果 ExistingTokenHandle 引用无效句柄，ZwDuplicateToken 将返回STATUS_INVALID_HANDLE。

注解

如果 ObjectAttributes 参数未提供任何模拟级别信息，则现有令牌的模拟级别将用于新令牌。

对于可选 ObjectAttributes 参数指向的结构，OBJECT_ATTRIBUTES 的 SecurityQualityOfService 成员指向SECURITY_QUALITY_OF_SERVICE类型的结构。 有关此结构的成员的信息，请参阅 SECURITY_QUALITY_OF_SERVICE 。

必须在调用 InitializeObjectAttributes 宏后设置 SecurityQualityOfService 成员，因为 InitializeObjectAttributes 当前将 SecurityQualityOfService 设置为 NULL。

有关 ZwDuplicateToken 的用户模式模拟的信息，请参阅 DuplicateTokenEx。

使用完新令牌后，调用 ZwClose 函数以关闭令牌句柄。

如果对 ZwDuplicateToken 函数的调用在用户模式下发生，则应使用名称“NtDuplicateToken”而不是“ZwDuplicateToken”。

对于来自内核模式驱动程序的调用，Windows 本机系统服务例程的 NtXxx 和 ZwXxx 版本在处理和解释输入参数的方式上的行为可能有所不同。 有关例程的 NtXxx 和 ZwXxx 版本之间的关系的详细信息，请参阅 使用本机系统服务例程的 Nt 和 Zw 版本。

要求

要求 值
最低受支持的客户端 Windows 2000
目标平台 通用
标头 ntifs.h (包括 Ntifs.h、FltKernel.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 符合性规则 HwStorPortProhibitedDDI (storport) 、 PowerIrpDDis (wdm)

另请参阅

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

SECURITY_IMPERSONATION_LEVEL