DuplicateTokenEx 函数 (securitybaseapi.h)

项目
08/25/2023

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 枚举中的下列值之一。

值	含义
TokenPrimary	新令牌是可在 CreateProcessAsUser 函数中使用的主令牌。
TokenImpersonation	新令牌是模拟令牌。

[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