ntDuplicateToken 函式 (ntifs.h)
NtDuplicateToken 函式會建立新存取令牌的句柄，以複製現有的令牌。 此函式可以建立主要令牌或模擬令牌。
語法
__kernel_entry NTSYSCALLAPI NTSTATUS NtDuplicateToken(
[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
指定新令牌要求訪問許可權的位掩碼。 NtDuplicateToken 會比較所要求的訪問許可權與現有令牌的任意訪問控制清單 (DACL) ，以判斷對新令牌授與或拒絕哪些許可權。 若要要求與現有令牌相同的訪問許可權，請指定零。 若要要求所有對呼叫端有效的訪問許可權，請指定MAXIMUM_ALLOWED。 這個參數是選擇性的，可以是零、MAXIMUM_ALLOWED或下列一或多個值的位 OR 組合：
如需詳細資訊，請參閱 Access-Token 對象的訪問許可權。 請注意，存取令牌不支援 SYNCHRONIZE 許可權。
[in] ObjectAttributes
OBJECT_ATTRIBUTES結構的指標，描述新令牌的要求屬性。 ObjectAttributes 參數是選擇性的，而且可以是 NULL。 如果 ObjectAttributes 參數為 NULL，或如果 ObjectAttributes 參數所指向結構的 SecurityDescriptor 成員是 NULL，則新令牌會收到預設的安全性描述元，而且無法繼承新的令牌句柄。 在此情況下，會從儲存在呼叫端令牌中的使用者群組、主要群組和 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 或 SecurityDelegation 的 ObjectAttributes 參數所提供) 。 否則，會傳回 NtDuplicateToken STATUS_BAD_IMPERSONATION_LEVEL。 |
| TokenImpersonation | 新的令牌是模擬令牌。 如果現有的令牌是模擬令牌，則所要求模擬層級 (，如新令牌的 ObjectAttributes 參數) 所提供，不得大於現有令牌的模擬層級。 否則， NtDuplicateToken 會傳回STATUS_BAD_IMPERSONATION_LEVEL。 |
TokenType 參數是必要的，而且不能是 NULL。
[out] NewTokenHandle
呼叫端配置的變數指標，屬於 HANDLE 類型，可接收新令牌的句柄。 這個參數是必要的，而且不能是 NULL。
傳回值
如果呼叫成功，NtDuplicateToken 會傳回STATUS_SUCCESS。 可能的錯誤傳回碼包括下列專案：
| 傳回碼 | Description |
|---|---|
| STATUS_ACCESS_VIOLATION | 發生記憶體存取違規。 例如，如果先前的模式是使用者模式，而且提供了無效的使用者模式記憶體， 則 NtDuplicateToken 會傳回STATUS_ACCESS_VIOLATION。 |
| STATUS_INSUFFICIENT_RESOURCES | 無法配置足夠的記憶體來複製新的令牌。 |
| STATUS_INVALID_PARAMETER | 偵測到無效的參數。 |
| STATUS_BAD_IMPERSONATION_LEVEL | 新令牌的要求模擬層級大於現有令牌的模擬層級。 |
| STATUS_ACCESS_DENIED | NtDuplicateToken 無法存取 ExistingTokenHandle。 如果現有的令牌沒有TOKEN_DUPLICATE訪問許可權，就會發生這種情況。 |
| STATUS_INVALID_HANDLE | ExistingTokenHandle 是指無效的句柄。 |
備註
如果 ObjectAttributes 參數未提供模擬層級資訊，則現有的令牌模擬層級將用於新的令牌。
對於選擇性 ObjectAttributes 參數所指向的結構，OBJECT_ATTRIBUTES的 SecurityQualityOfService 成員會指向類型SECURITY_QUALITY_OF_SERVICE的結構。 如需此結構成員的資訊 ，請參閱SECURITY_QUALITY_OF_SERVICE 。
呼叫 InitializeObjectAttributes 宏之後，必須設定 SecurityQualityOfService 成員，因為 InitializeObjectAttributes 目前會將 SecurityQualityOfService 設定為 NULL。
如需 NtDuplicateToken 的使用者模式模擬資訊，請參閱 Windows SDK 檔中的 DuplicateTokenEx。
當您完成使用新的令牌時，請呼叫 NtClose 函式以關閉令牌句柄。
如果 對 NtDuplicateToken 函式的呼叫發生在使用者模式中，您應該使用名稱 “NtDuplicateToken”，而不是 “NtDuplicateToken”。
對於核心模式驅動程式的呼叫，Windows 原生系統服務例程的 NtXxx 和 ZwXxx 版本在處理和解譯輸入參數的方式可能會有不同的行為。 如需例程 NtXxx 和 ZwXxx 版本之間的關聯性詳細資訊，請參閱 使用 Nt 和 Zw 版本的原生系統服務例程。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 2000 |
| 目標平台 | Universal |
| 標頭 | ntifs.h (包括 Ntifs.h、FltKernel.h) |
| 程式庫 | NtosKrnl.lib |
| Dll | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI 合規性規則 | HwStorPortProhibitedDIS、 PowerIrpDDis |