Securitybaseapi.h (DuplicateTokenEx 函式)
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 指定下列其中一個值。
值 | 意義 |
---|---|
|
新的權杖是您可以在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) |
程式庫 | Advapi32.lib |
Dll | Advapi32.dll |