ntDuplicateToken 函数 (ntifs.h)
NtDuplicateToken 函数创建与现有令牌重复的新访问令牌的句柄。 此函数可以创建主令牌或模拟令牌。
语法
__kernel_entry NTSYSCALLAPI NTSTATUS NtDuplicateToken(
[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
指定新令牌请求的访问权限的位掩码。 NtDuplicateToken 将请求的访问权限与现有令牌的任意访问控制列表 (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 | 合并令牌的所有可能的令牌访问权限。 |
有关详细信息，请参阅 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，则调用方可以复制令牌，但删除 Administrators 组和 SeTcbPrivilege 权限。 然后，生成的令牌可以传递给一个子进程 (CreateProcessAsUser) ，这将限制子进程可以执行的操作。 此参数是必需的。
[in] TokenType
指定 TOKEN_TYPE 枚举中的下列值之一。
| 值 | 含义 |
|---|---|
| TokenPrimary | 新令牌是主令牌。 如果现有令牌是模拟令牌，则现有模拟令牌必须具有由 SecurityImpersonation 或 SecurityDelegation 的 ObjectAttributes 参数) 提供的模拟级别 (。 否则， NtDuplicateToken 返回STATUS_BAD_IMPERSONATION_LEVEL返回。 |
| TokenImpersonation | 新令牌是模拟令牌。 如果现有令牌是模拟令牌，则新令牌的 ObjectAttributes 参数) (请求的模拟级别不得大于现有令牌的模拟级别。 否则， NtDuplicateToken 返回STATUS_BAD_IMPERSONATION_LEVEL。 |
TokenType 参数是必需的，不能为 NULL。
[out] NewTokenHandle
指向调用方分配的变量（类型为 HANDLE）的指针，该变量接收新令牌的句柄。 此参数是必需的，不能为 NULL。
返回值
如果调用成功，NtDuplicateToken 将返回STATUS_SUCCESS。 可能的错误返回代码包括以下内容：
| 返回代码 | 说明 |
|---|---|
| STATUS_ACCESS_VIOLATION | 出现内存访问冲突。 例如，如果以前的模式为用户模式，并且提供了无效的用户模式内存， 则 NtDuplicateToken 将返回STATUS_ACCESS_VIOLATION。 |
| STATUS_INSUFFICIENT_RESOURCES | 无法分配足够的内存来复制新令牌。 |
| STATUS_INVALID_PARAMETER | 检测到无效的参数。 |
| STATUS_BAD_IMPERSONATION_LEVEL | 新令牌请求的模拟级别大于现有令牌的模拟级别。 |
| STATUS_ACCESS_DENIED | NtDuplicateToken 无法访问 ExistingTokenHandle。 如果现有令牌没有TOKEN_DUPLICATE访问权限，则会发生这种情况。 |
| STATUS_INVALID_HANDLE | ExistingTokenHandle 是指无效的句柄。 |
注解
如果 ObjectAttributes 参数未提供任何模拟级别信息，则现有令牌的模拟级别将用于新令牌。
对于可选 ObjectAttributes 参数指向的结构，OBJECT_ATTRIBUTES 的 SecurityQualityOfService 成员指向SECURITY_QUALITY_OF_SERVICE类型的结构。 有关此结构的成员的信息，请参阅 SECURITY_QUALITY_OF_SERVICE 。
必须在调用 InitializeObjectAttributes 宏后设置 SecurityQualityOfService 成员，因为 InitializeObjectAttributes 当前将 SecurityQualityOfService 设置为 NULL。
有关 NtDuplicateToken 的用户模式模拟的信息，请参阅Windows SDK文档中的 DuplicateTokenEx。
使用完新令牌后，调用 NtClose 函数以关闭令牌句柄。
如果对 NtDuplicateToken 函数的调用在用户模式下发生，则应使用名称“NtDuplicateToken”而不是“NtDuplicateToken”。
对于来自内核模式驱动程序的调用，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，PowerIrpDDis |