ZwDuplicateToken 函式 （ntifs.h）
ZwDuplicateToken 函式會建立對複製現有令牌的新 存取令牌 句柄。 此函式可以建立主要令牌或模擬令牌。
語法
NTSYSAPI NTSTATUS ZwDuplicateToken(
[in] HANDLE ExistingTokenHandle,
[in] ACCESS_MASK DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[in] BOOLEAN EffectiveOnly,
[in] TOKEN_TYPE TokenType,
[out] PHANDLE NewTokenHandle
);
參數
[in] ExistingTokenHandle
使用TOKEN_DUPLICATE訪問許可權開啟之現有存取令牌的句柄。 這個參數是必要的，而且不能是 NULL。
[in] DesiredAccess
指定新令牌要求訪問許可權的位掩碼。 ZwDuplicateToken 比較要求的訪問許可權與現有令牌的任意訪問控制清單 （DACL） 來判斷要授與或拒絕給新令牌的許可權。 若要要求與現有令牌相同的訪問許可權，請指定零。 若要要求所有對呼叫者有效的訪問許可權，請指定MAXIMUM_ALLOWED。 此參數是選擇性的，可以是零、MAXIMUM_ALLOWED或下列一或多個值的位 OR 組合：
| 價值 | 意義 |
|---|---|
| 刪除 | 需要刪除物件。 |
| READ_CONTROL | 讀取物件的 DACL 和擁有權資訊的必要專案。 如需系統訪問控制清單的存取權（SACL），請參閱下表稍後的ACCESS_SYSTEM_SECURITY。 |
| WRITE_DAC | 需要變更物件的 DACL 資訊。 |
| WRITE_OWNER | 需要變更物件之安全性描述元中擁有權資訊 （SECURITY_DESCRIPTOR）。 |
| ACCESS_SYSTEM_SECURITY | 需要取得或設定物件 ACL 中的 SACL。 只有在呼叫線程的存取令牌中啟用SE_SECURITY_NAME許可權時，操作系統才會將此許可權授與給新的令牌。 |
| STANDARD_RIGHTS_READ | 目前定義為等於 READ_CONTROL。 |
| STANDARD_RIGHTS_WRITE | 目前定義為等於 READ_CONTROL。 |
| STANDARD_RIGHTS_EXECUTE | 目前定義為等於 READ_CONTROL。 |
| STANDARD_RIGHTS_REQUIRED | 結合 DELETE、READ_CONTROL、WRITE_DAC和WRITE_OWNER存取。 |
| STANDARD_RIGHTS_ALL | 結合 DELETE、READ_CONTROL、WRITE_DAC、WRITE_OWNER 和 SYNCHRONIZE 存取。 不過，SYNCHRONIZE 值不適用於令牌物件。 因此，STANDARD_RIGHTS_ALL的功能相當於STANDARD_RIGHTS_REQUIRED。 |
| TOKEN_ADJUST_DEFAULT | 需要變更存取令牌的預設擁有者、主要群組或 DACL。 |
| TOKEN_ADJUST_GROUPS | 需要調整存取令牌中群組的屬性。 |
| TOKEN_ADJUST_PRIVILEGES | 啟用或停用存取令牌中許可權的必要專案。 |
| TOKEN_ADJUST_SESSIONID | 需要調整存取令牌的會話標識碼（SID）。 只有在呼叫線程的存取令牌中啟用SE_TCB_NAME許可權時，操作系統才會將此許可權授與新的令牌。 |
| TOKEN_ASSIGN_PRIMARY | 將主要令牌附加至進程的必要專案。 只有在呼叫線程的存取令牌中啟用SE_ASSIGNPRIMARYTOKEN_NAME許可權時，操作系統才會將此許可權授與給新的令牌。 |
| TOKEN_DUPLICATE | 需要複製存取令牌。 請注意，指定的 ExistingTokenHandle 令牌必須包含此許可權，才能成功使用此例程。 |
| TOKEN_EXECUTE | 結合STANDARD_RIGHTS_EXECUTE和TOKEN_IMPERSONATE。 |
| TOKEN_IMPERSONATE | 將模擬存取令牌附加至進程的必要專案。 |
| TOKEN_QUERY | 查詢存取令牌的必要專案。 |
| TOKEN_QUERY_SOURCE | 查詢存取令牌來源的必要專案。 |
| TOKEN_READ | 結合STANDARD_RIGHTS_READ和TOKEN_QUERY。 |
| TOKEN_WRITE | 結合STANDARD_RIGHTS_WRITE、TOKEN_ADJUST_PRIVILEGES、TOKEN_ADJUST_GROUPS和TOKEN_ADJUST_DEFAULT。 |
| TOKEN_ALL_ACCESS | 結合令牌的所有可能令牌訪問許可權。 |
如需詳細資訊，請參閱 Windows SDK 中的 Access-Token 物件的訪問許可權。 請注意，存取令牌不支援 SYNCHRONIZE 許可權。
[in] ObjectAttributes
描述新令牌所要求屬性之 OBJECT_ATTRIBUTES 結構的指標。 ObjectAttributes 參數是選擇性的，可以是 NULL。 如果 ObjectAttributes 參數為 NULL，或者如果 ObjectAttributes 參數所指向之結構的 SecurityDescriptor 成員，則新令牌會收到預設的安全性描述元，而且無法繼承新的令牌句柄。 在此情況下，會從儲存在呼叫端令牌中的使用者群組、主要群組和 DACL 資訊建立這個預設安全性描述元。
當 TokenType 参數設定為 TokenImpersonation時：
ObjectAttributes 參數可用來指定新令牌的模擬層級。 若要達成此目的，您可以將 ObjectAttributes->SecurityQualityOfService.ImpersonationLevel 設定為適當的 SECURITY_IMPERSONATION_LEVEL 列舉值。 如需詳細資訊，請參閱 SECURITY_QUALITY_OF_SERVICE。
如果現有的令牌是模擬令牌，且 ObjectAttributes 參數不會提供模擬資訊，則新令牌的模擬層級會設定為現有令牌的模擬層級。
如果現有的令牌是主要令牌，而且未提供模擬層級資訊，則新的模擬令牌將具有 SECURITY_IMPERSONATION_LEVEL 模擬層級。
[in] EffectiveOnly
布爾值，指出整個現有令牌是否應該複製到新的令牌中，或只是令牌的有效（目前已啟用）部分。 如果設定為 TRUE，則只會複製目前啟用的來源令牌部分。 如果設定為 FALSE，則會複製整個現有的令牌。 這為受保護子系統的呼叫端提供一種方法，以限制受保護子系統可使用哪些選擇性群組和許可權。 例如，如果 EffectiveOnly 為 TRUE，則呼叫端可能會複製令牌，但移除 Administrators 群組和 SeTcbPrivilege 許可權。 然後，產生的令牌可以傳遞至子進程 （CreateProcessAsUser），這會限制子進程可以執行的動作。 這是必要參數。
[in] TokenType
從 TOKEN_TYPE 列舉指定下列其中一個值。
| 價值 | 意義 |
|---|---|
| TokenPrimary | 新的令牌是主要令牌。 如果現有的令牌是模擬令牌，則現有的模擬令牌必須具有 SecurityImpersonation 或 SecurityDelegationObjectAttributes 參數所提供的模擬層級。 否則，會傳回 ZwDuplicateToken 傳回STATUS_BAD_IMPERSONATION_LEVEL。 |
| TokenImpersonation | 新的令牌是模擬令牌。 如果現有的令牌是模擬令牌，則新令牌的 ObjectAttributes 參數所提供的要求模擬層級不得大於現有令牌的模擬層級。 否則，ZwDuplicateToken 會傳回STATUS_BAD_IMPERSONATION_LEVEL。 |
需要 TokenType 參數，而且不能是 NULL。
[out] NewTokenHandle
呼叫端配置的變數指標，類型為 HANDLE，可接收新令牌的句柄。 這個參數是必要的，而且不能是 NULL。
傳回值
如果呼叫成功，ZwDuplicateToken 會傳回STATUS_SUCCESS。 可能的錯誤傳回碼包括下列專案：
| 傳回碼 | 描述 |
|---|---|
| STATUS_ACCESS_VIOLATION | 發生記憶體存取違規。 例如，如果上一個模式是使用者模式，並提供無效的使用者模式記憶體，ZwDuplicateToken 會傳回STATUS_ACCESS_VIOLATION。 |
| STATUS_INSUFFICIENT_RESOURCES | 無法配置足夠的記憶體來複製新的令牌。 |
| STATUS_INVALID_PARAMETER | 偵測到無效的參數。 |
| STATUS_BAD_IMPERSONATION_LEVEL | 新令牌所要求的模擬層級大於現有令牌的模擬層級。 |
| STATUS_ACCESS_DENIED | |
| STATUS_INVALID_HANDLE | ZwDuplicateToken 如果 ExistingTokenHandle 參考無效的句柄，STATUS_INVALID_HANDLE。 |
言論
如果 ObjectAttributes 參數未提供模擬層級資訊，則現有的令牌模擬層級將用於新的令牌。
至於選擇性 ObjectAttributes 參數所指向的結構，SecurityQualityOfService 成員 OBJECT_ATTRIBUTES 指向類型 SECURITY_QUALITY_OF_SERVICE的結構。 如需此結構成員的詳細資訊，請參閱 SECURITY_QUALITY_OF_SERVICE。
如需 ZwDuplicateToken的使用者模式模擬資訊，請參閱 DuplicateTokenEx。
當您完成使用新的令牌時，請呼叫 ZwClose 函式以關閉令牌句柄。
如果在使用者模式中呼叫 ZwDuplicateToken 函式，您應該使用名稱 “NtDuplicateToken” 而不是 “ZwDuplicateToken”。
對於內核模式驅動程式的呼叫，NtXxx 和 ZwXxx 版本的 Windows 原生系統服務例程，在處理和解譯輸入參數的方式上可能會有不同的行為。 如需 nt NtXxx 與 ZwXxx 例程之間關聯性的詳細資訊，請參閱 使用 Nt 和 Zw 版本的原生系統服務例程。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows 2000 |
| 目標平臺 | 普遍 |
| 標頭 | ntifs.h （include Ntifs.h， FltKernel.h） |
| 連結庫 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI 合規性規則 | HwStorPortProhibitedDIs（storport），PowerIrpDDis（wdm） |