DuplicateTokenEx 函数 (securitybaseapi.h)
DuplicateTokenEx 函数创建一个复制现有令牌的新访问令牌。 此函数可以创建 主令牌 或 模拟令牌。
语法
BOOL DuplicateTokenEx(
[in] HANDLE hExistingToken,
[in] DWORD dwDesiredAccess,
[in, optional] LPSECURITY_ATTRIBUTES lpTokenAttributes,
[in] SECURITY_IMPERSONATION_LEVEL ImpersonationLevel,
[in] TOKEN_TYPE TokenType,
[out] PHANDLE phNewToken
);
parameters
[in] hExistingToken
使用TOKEN_DUPLICATE访问权限打开的访问令牌的句柄。
[in] dwDesiredAccess
指定新令牌的请求访问权限。 DuplicateTokenEx 函数将请求的访问权限与现有令牌的任意访问控制列表 (DACL) 进行比较，以确定授予或拒绝了哪些权限。 若要请求与现有令牌相同的访问权限，请指定零。 若要请求对调用方有效的所有访问权限，请指定MAXIMUM_ALLOWED。
有关访问令牌访问权限的列表，请参阅 Access-Token 对象的访问权限。
[in, optional] lpTokenAttributes
指向 SECURITY_ATTRIBUTES 结构的指针，该结构指定新令牌 的安全描述符 ，并确定子进程是否可以继承令牌。 如果 lpTokenAttributes 为 NULL，则令牌将获取默认安全描述符，并且无法继承句柄。 如果安全描述符包含 系统访问控制列表 (SACL) ，则令牌ACCESS_SYSTEM_SECURITY访问权限，即使 未在 dwDesiredAccess 中请求也是如此。
若要在新令牌的安全描述符中设置所有者，调用方的进程令牌必须具有 SE_RESTORE_NAME 权限集。
[in] ImpersonationLevel
指定 SECURITY_IMPERSONATION_LEVEL 枚举中的值，该值指示新标记的模拟级别。
[in] TokenType
指定 TOKEN_TYPE 枚举中的下列值之一。
| 值 | 含义 |
|---|---|
|
新令牌是可在 CreateProcessAsUser 函数中使用的主令牌。 |
|
新令牌是模拟令牌。 |
[out] phNewToken
指向接收新令牌的 HANDLE 变量的指针。
使用完新令牌后，调用 CloseHandle 函数以关闭令牌句柄。
返回值
如果函数成功，该函数将返回非零值。
如果函数失败，则返回零。 要获得更多的错误信息，请调用 GetLastError。
注解
DuplicateTokenEx 函数允许创建可在 CreateProcessAsUser 函数中使用的主令牌。 这允许模拟客户端的服务器应用程序创建具有客户端 安全上下文 的进程。 请注意， DuplicateToken 函数只能创建对 CreateProcessAsUser 无效的模拟令牌。
下面是使用 DuplicateTokenEx 创建 主令牌的典型方案。 服务器应用程序创建一个线程，该线程调用某个模拟函数（如 ImpersonateNamedPipeClient）来模拟客户端。 然后，模拟线程调用 OpenThreadToken 函数来获取自己的令牌，该令牌是具有客户端安全上下文的 模拟令牌 。 线程在调用 DuplicateTokenEx 时指定此模拟令牌，并指定 TokenPrimary 标志。 DuplicateTokenEx 函数创建具有客户端安全上下文的主令牌。
要求
| 最低受支持的客户端 | Windows XP [桌面应用 | UWP 应用] |
| 最低受支持的服务器 | Windows Server 2003 [桌面应用 | UWP 应用] |
| 目标平台 | Windows |
| 标头 | securitybaseapi.h (包括 Windows.h) |
| Library | Advapi32.lib |
| DLL | Advapi32.dll |