createRestrictedToken 函式 (securitybaseapi.h)
CreateRestrictedToken 函式會建立新的存取令牌,此令牌是現有存取令牌的受限制版本。 受限制的令牌可以停用 安全性標識符 , (SID) 、已刪除的許可權,以及限制 SID 的清單。 如需詳細資訊,請參閱 受限制的令牌。
語法
BOOL CreateRestrictedToken(
[in] HANDLE ExistingTokenHandle,
[in] DWORD Flags,
[in] DWORD DisableSidCount,
[in, optional] PSID_AND_ATTRIBUTES SidsToDisable,
[in] DWORD DeletePrivilegeCount,
[in, optional] PLUID_AND_ATTRIBUTES PrivilegesToDelete,
[in] DWORD RestrictedSidCount,
[in, optional] PSID_AND_ATTRIBUTES SidsToRestrict,
[out] PHANDLE NewTokenHandle
);
參數
[in] ExistingTokenHandle
主要或模擬令牌的句柄。 令牌也可以是受限制的令牌。 句柄必須具有令牌TOKEN_DUPLICATE存取權。
[in] Flags
指定其他許可權選項。 這個參數可以是零或下列值的組合。
值 | 意義 |
---|---|
|
停用新令牌中的所有許可權, 但 SeChangeNotifyPrivilege 許可權除外。 如果指定這個值,則會忽略 DeletePrivilegeCount 和 PrivilegesToDelete 參數。 |
|
如果使用此值,系統不會檢查 AppLocker 規則或套用 軟體限制原則。 針對 AppLocker,此旗標會停用所有四個規則集合的檢查:可執行檔、Windows Installer、腳本和 DLL。
在安裝期間建立必須執行擷取 DLL 的安裝程式時,請使用 SaferComputeTokenFromLevel 函式中的 旗標SAFER_TOKEN_MAKE_INERT。 您可以使用 GetTokenInformation 查詢令牌是否存在此旗標。 Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP: 在安裝KB2532445的系統上,呼叫端必須以LocalSystem或TrustedInstaller或系統的形式執行,否則系統會忽略此旗標。 For more information, see "You can circumvent AppLocker rules by using an Office macro on a computer that is running Windows 7 or Windows Server 2008 R2" in the Help and Support Knowledge Base at http://support.microsoft.com/kb/2532445. Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP: 不支援 AppLocker。 AppLocker 是在 Windows 7 和 Windows Server 2008 R2 中引進。 |
|
新的令牌是 LUA 令牌。
Windows Server 2003 和 Windows XP: 不支援這個值。 |
|
新的令牌包含限制只有在評估寫入存取權時才會考慮的SID。
Windows XP 與 SP2 和更新版本: 這個常數的值是0x4。 若要讓應用程式與 Windows XP 與 SP2 和更新版本的作業系統相容,應用程式應該呼叫 GetVersionEx 函式來查詢作業系統,以判斷應該使用的值。 Windows Server 2003 和 Windows XP SP1 和更早版本: 不支援這個值。 |
[in] DisableSidCount
指定 SidsToDisable 陣列中的項目數。
[in, optional] SidsToDisable
指定受限制令牌中僅限拒絕 SID 之SID_AND_ATTRIBUTES 結構的陣列指標。 系統會使用僅限拒絕的 SID 來拒絕存取安全性實體物件。 沒有僅限拒絕的 SID 不允許存取。
停用 SID 會開啟SE_GROUP_USE_FOR_DENY_ONLY,並關閉SE_GROUP_ENABLED和SE_GROUP_ENABLED_BY_DEFAULT。 其他屬性都會被忽略。
僅限拒絕屬性會套用至現有令牌 SID 的任何組合,包括具有SE_GROUP_MANDATORY屬性的使用者 SID 和群組 SID。 若要取得與現有令牌相關聯的 SID,請使用 GetTokenInformation 函式搭配 TokenUser 和 TokenGroups 旗標。 函式會忽略陣列中未在現有令牌中找到的任何SID。
函式會忽略SID_AND_ATTRIBUTES結構的 Attributes 成員。
如果未停用 SID,這個參數可以是 NULL 。
[in] DeletePrivilegeCount
指定 PrivilegesToDelete 陣列中的項目數。
[in, optional] PrivilegesToDelete
LUID_AND_ATTRIBUTES結構的陣列指標,指定在受限制令牌中刪除的許可權。
GetTokenInformation 函式可以搭配 TokenPrivileges 旗標使用,以擷取現有令牌所持有的許可權。 函式會忽略陣列中未由現有令牌持有的任何許可權。
函式會忽略LUID_AND_ATTRIBUTES結構的 Attributes 成員。
如果您不想刪除任何許可權,這個參數可以是 NULL 。
如果呼叫程式在此陣列中傳遞太多許可權, CreateRestrictedToken 會傳回ERROR_INVALID_PARAMETER。
[in] RestrictedSidCount
指定 SidsToRestrict 陣列中的項目數。
[in, optional] SidsToRestrict
SID_AND_ATTRIBUTES 結構的陣列指標,指定新令牌的限制 SID 清單。 如果現有的令牌是受限制的令牌,新令牌的限制 SID 清單就是此陣列的交集,以及限制現有令牌的 SID 清單。 不會執行任何檢查,以移除放在 SidsToRestrict 參數上的重複 SID。 重複的 SID 可讓受限制的令牌在限制 SID 清單中具有多餘的資訊。
SID_AND_ATTRIBUTES 結構的 Attributes 成員必須是零。 限制 SID 一律會啟用存取檢查。
如果您不想指定任何限制的 SID,這個參數可以是 NULL 。
[out] NewTokenHandle
接收新受限制令牌句柄之變數的指標。 此句柄具有與 ExistingTokenHandle 相同的訪問許可權。 新令牌的類型、 主要 或 模擬,與現有的令牌相同。 NewTokenHandle 中傳回的句柄可以重複。
傳回值
如果函式成功,則傳回非零的值。
如果此函式失敗,則傳回值為零。 若要取得擴充的錯誤資訊,請呼叫 GetLastError。
備註
CreateRestrictedToken 函式可以透過下列方式限制令牌:
- 將僅限拒絕屬性套用至令牌中的 SID,使其無法用來存取受保護的物件。 如需僅限拒絕屬性的詳細資訊,請參閱 存取令牌中的 SID 屬性。
- 從令牌中移除 許可權 。
- 指定限制 SID 的清單,系統會在檢查令牌對安全性實體物件的存取時使用。 系統會執行兩個存取檢查:一個使用令牌已啟用的SID,另一個則使用限制 SID 的清單。 只有在兩個存取檢查都允許要求的訪問許可權時,才會授與存取權。
您可以在 ImpersonateLoggedOnUser 函式中使用受限制的令牌。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
最低支援的伺服器 | Windows Server 2003 [僅限桌面應用程式] |
目標平台 | Windows |
標頭 | securitybaseapi.h (包含 Windows.h) |
程式庫 | Advapi32.lib |
Dll | Advapi32.dll |