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 組合：

值 意義
DELETE 刪除物件的必要專案。
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 成員是 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 參數所提供) 。 否則，會傳回 ZwDuplicateToken STATUS_BAD_IMPERSONATION_LEVEL。
TokenImpersonation 新的令牌是模擬令牌。 如果現有的令牌是模擬令牌，則所要求模擬層級 (，如新令牌的 ObjectAttributes 參數) 所提供，不得大於現有令牌的模擬層級。 否則， ZwDuplicateToken 會傳回STATUS_BAD_IMPERSONATION_LEVEL。

TokenType 參數是必要的，而且不能是 NULL。

[out] NewTokenHandle

呼叫端配置變數的指標，其類型為 HANDLE，可接收新令牌的句柄。 這個參數是必要的，而且不能是 NULL。

傳回值

如果呼叫成功，ZwDuplicateToken 會傳回STATUS_SUCCESS。 可能的錯誤傳回碼包括：

傳回碼 Description
STATUS_ACCESS_VIOLATION 發生記憶體存取違規。 例如，如果上一個模式是使用者模式，而且提供了無效的使用者模式記憶體， ZwDuplicateToken 會傳回STATUS_ACCESS_VIOLATION。
STATUS_INSUFFICIENT_RESOURCES 無法配置足夠的記憶體來複製新的令牌。
STATUS_INVALID_PARAMETER 偵測到無效的參數。
STATUS_BAD_IMPERSONATION_LEVEL 新令牌所要求的模擬層級大於現有令牌的模擬層級。
STATUS_ACCESS_DENIED 如果 ZwDuplicateToken 無法存取 ExistingTokenHandle，則會傳回STATUS_ACCESS_DENIED。 如果現有的令牌沒有TOKEN_DUPLICATE訪問許可權，就會發生這種情況。
STATUS_INVALID_HANDLE 如果 ExistingTokenHandle 參考無效的句柄，ZwDuplicateToken 會傳回STATUS_INVALID_HANDLE。

備註

如果 ObjectAttributes 參數未提供模擬層級資訊，則現有令牌的模擬層級將用於新的令牌。

就選擇性 ObjectAttributes 參數所指向的結構而言，OBJECT_ATTRIBUTES的 SecurityQualityOfService 成員會指向類型SECURITY_QUALITY_OF_SERVICE的結構。 如需此結構成員的詳細資訊 ，請參閱SECURITY_QUALITY_OF_SERVICE 。

在呼叫 InitializeObjectAttributes 宏之後，必須設定 SecurityQualityOfService 成員，因為 InitializeObjectAttributes 目前將 SecurityQualityOfService 設定為 NULL。

如需 ZwDuplicateToken 的使用者模式模擬資訊，請參閱 DuplicateTokenEx。

當您完成使用新的令牌時，請呼叫 ZwClose 函式以關閉令牌句柄。

如果在使用者模式中呼叫 ZwDuplicateToken 函式，您應該使用名稱 “NtDuplicateToken” 而不是 “ZwDuplicateToken”。

針對來自內核模式驅動程式的呼叫，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 (storport) 、 PowerIrpDDis (wdm)

另請參閱

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

SECURITY_IMPERSONATION_LEVEL