DuplicateTokenEx 函数（securitybaseapi.h）

项目
11/20/2024

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
);

参数

[in] hExistingToken

使用TOKEN_DUPLICATE访问权限打开的访问令牌的句柄。

[in] dwDesiredAccess

指定新令牌的请求访问权限。 DuplicateTokenEx 函数将请求的访问权限与现有令牌的自由访问控制列表（DACL）进行比较，以确定授予或拒绝哪些权限。若要请求与现有令牌相同的访问权限，请指定零。若要请求对调用方有效的所有访问权限，请指定MAXIMUM_ALLOWED。

有关访问令牌的访问权限列表，请参阅 Access-Token 对象的访问权限。

[in, optional] lpTokenAttributes

指向 SECURITY_ATTRIBUTES 结构的指针，该结构指定新令牌安全描述符，并确定子进程是否可以继承令牌。如果 lpTokenAttributesNULL，则令牌将获取默认的安全描述符，并且无法继承句柄。如果安全描述符包含系统访问控制列表（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 应用]
目标平台	窗户
标头	securitybaseapi.h （包括 Windows.h）
库	Advapi32.lib
DLL	Advapi32.dll