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