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 组合：
| 价值 | 意义 |
|---|---|
| 删除 | 需要删除对象。 |
| 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 | 需要调整访问令牌的会话 ID（SID）。 仅当调用线程的访问令牌中启用了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 对象的
[in] ObjectAttributes
指向描述新令牌请求属性的 OBJECT_ATTRIBUTES 结构的指针。
ObjectAttributes 参数是可选的，可以为 NULL。 如果
当 TokenType 参数设置为 TokenImpersonation时：
ObjectAttributes 参数可用于指定新令牌的模拟级别。 可以通过将 ObjectAttributes
- SecurityQualityOfService.ImpersonationLevel 设置为适当的 SECURITY_IMPERSONATION_LEVEL 如果现有令牌是模拟令牌，并且 ObjectAttributes 参数不提供模拟信息，则新令牌的模拟级别设置为现有令牌的模拟级别。
如果现有令牌是主令牌，并且未提供模拟级别信息，则新的模拟令牌将具有 SECURITY_IMPERSONATION_LEVEL 模拟级别。
[in] EffectiveOnly
一个布尔值，该值指示整个现有令牌是应复制到新令牌中还是只复制令牌的有效（当前已启用）部分。 如果设置为 TRUE，则仅复制当前启用的源令牌部分。 如果设置为 FALSE，将复制整个现有令牌。 这为受保护子系统的调用方提供了一种限制对受保护子系统可用的可选组和特权的方法。 例如，如果 EffectiveOnly 为 TRUE，则调用方可能会复制令牌，但删除 Administrators 组和 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_INVALID_HANDLE | 如果 ExistingTokenHandle 引用无效句柄，则 ZwDuplicateToken 返回STATUS_INVALID_HANDLE。 |
言论
如果 ObjectAttributes 参数未提供模拟级别信息，则现有令牌的模拟级别将用于新令牌。
对于可选 ObjectAttributes 参数所指向的结构，SecurityQualityOfServiceOBJECT_ATTRIBUTES 成员指向 SECURITY_QUALITY_OF_SERVICE类型的结构。 有关此结构的成员的信息，请参阅 SECURITY_QUALITY_OF_SERVICE。
调用
有关 ZwDuplicateToken的用户模式模拟信息，请参阅 DuplicateTokenEx。
使用完新令牌后，调用 ZwClose 函数以关闭令牌句柄。
如果在用户模式下调用 ZwDuplicateToken 函数，则应使用名称“NtDuplicateToken”而不是“ZwDuplicateToken”。
对于内核模式驱动程序的调用，NtXxx 和 ZwXxx 版本的 Windows 本机系统服务例程的行为方式可能以不同的方式处理和解释输入参数。 有关 NtXxx 与 ZwXxx 例程之间的关系的详细信息，请参阅 使用 Nt 和 Zw 版本的本机系统服务例程。
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | Windows 2000 |
| 目标平台 | 普遍 |
| 标头 | ntifs.h（包括 Ntifs.h、FltKernel.h） |
| 库 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI 符合性规则 | HwStorPortProhibitedDIS（storport），PowerIrpDDis（wdm） |