Securitybaseapi.h (DuplicateTokenEx 函式)

發行項
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
);

參數

[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)
程式庫	Advapi32.lib
Dll	Advapi32.dll