SetPrivateObjectSecurityEx 函式 (securitybaseapi.h)

  • 發行項

SetPrivateObjectSecurityEx 函式會修改由呼叫此函式之資源管理員所維護之私用對象的安全性描述元。 SetPrivateObjectSecurityEx 函式具有旗標參數，指定資源管理員是否支援 (ACE 自動繼承訪問控制專案) 。

語法

BOOL SetPrivateObjectSecurityEx(
  [in]           SECURITY_INFORMATION SecurityInformation,
  [in]           PSECURITY_DESCRIPTOR ModificationDescriptor,
  [in, out]      PSECURITY_DESCRIPTOR *ObjectsSecurityDescriptor,
  [in]           ULONG                AutoInheritFlags,
  [in]           PGENERIC_MAPPING     GenericMapping,
  [in, optional] HANDLE               Token
);

參數

[in] SecurityInformation

要設定的安全性描述元部分。 這個值可以是 SECURITY_INFORMATION 位旗標的組合。

[in] ModificationDescriptor

SECURITY_DESCRIPTOR 結構的指標。 SecurityInformation 參數所指示的這個安全性描述元部分會套用至 ObjectsSecurityDescriptor 安全性描述元。

[in, out] ObjectsSecurityDescriptor

指向SECURITY_DESCRIPTOR結構的指標。 此安全性描述項必須採用 自我相對 形式。 安全性描述元的記憶體必須從進程堆積配置， (GetProcessHeap) 與 HeapAlloc 函式。

在輸入時，這是私用物件目前的安全性描述項。 函式會修改它，以產生新的安全性描述元。 如有必要， SetPrivateObjectSecurityEx 函 式會配置額外的記憶體，以產生較大的安全性描述元。

[in] AutoInheritFlags

指定 ACE 的自動繼承。 如果受保護的伺服器未實作自動繼承，則應該指定零;否則，它可以指定 Winnt.h 中定義的下列值組合。

值 意義
SEF_DACL_AUTO_INHERIT
0x01
 新的 任意訪問控制清單 (DACL) 包含繼承自物件父系 DACL 的 ACE，以及修改修改描述 元 DACL 中指定的任何明確 ACE。 如果未設定此旗標，新的 DACL 不會繼承 ACE。
SEF_SACL_AUTO_INHERIT
0x02
 新的 系統訪問控制清單 (SACL) 包含繼承自與物件父系相關聯之安全描述元 SACL 的 ACL，以及 SACL of ModificationDescriptor 中指定的任何明確 ACE。 如果未設定此旗標，新的 SACL 不會繼承 ACE。
SEF_AVOID_PRIVILEGE_CHECK
0x08
 函式不會執行許可權檢查。 如果同時設定 SEF_AVOID_OWNER_CHECK 旗標， Token 參數可以是 NULL。 實作自動繼承時，請使用此旗標，以避免檢查每個更新子系的許可權。
SEF_AVOID_OWNER_CHECK
0x10
 函式不會檢查結果 ObjectsSecurityDescriptor 中擁有者的有效性，如中所述。 如果同時設定 SEF_AVOID_PRIVILEGE_CHECK 旗標， Token 參數可以是 NULL。
SEF_DEFAULT_OWNER_FROM_PARENT
0x20
 ObjectsSecurityDescriptor 的擁有者預設為物件的父系擁有者。 如果未設定此旗標， ObjectsSecurityDescriptor 的擁有者預設為 Token 參數所指定的 令牌 擁有者。 令牌的擁有者是在令牌本身中指定。 不論是哪一種情況，如果ModificationDescriptor 參數不是 NULL，ObjectsSecurityDescriptor 擁有者就會從ModificationDescriptor 設定為擁有者。
SEF_DEFAULT_GROUP_FROM_PARENT
0x40
 ObjectsSecurityDescriptor 群組預設為物件父系擁有者的群組。 如果未設定此旗標， ObjectsSecurityDescriptor 群組預設為 Token 參數所指定的 令牌 群組。 令牌群組是在令牌本身中指定。 不論是哪一種情況，如果ModificationDescriptor 參數不是 NULL，ObjectsSecurityDescriptor 群組就會從ModificationDescriptor 設定為群組。
SEF_MACL_NO_WRITE_UP
0x100
 低於物件之必要層級的主體無法寫入物件。
SEF_MACL_NO_READ_UP
0x200
 低於物件之強制層級的主體無法讀取物件。
SEF_MACL_NO_EXECUTE_UP
0x400
 低於物件之強制層級的主體無法執行 物件。
SEF_AVOID_OWNER_RESTRICTION
0x1000
 會忽略物件父系擁有者所指定的任何限制，以限制呼叫者在 ObjectsSecurityDescriptor 中指定 DACL 的能力。

[in] GenericMapping

GENERIC_MAPPING 結構的指標，指定對應至每個泛型訪問許可權的特定和標準訪問許可權。

[in, optional] Token

識別代表私人物件安全性修改之用戶端的 存取令牌 。 這是必要參數，以確保用戶端已為新的擁有者 安全性標識碼 提供合法值， (SID) 。 令牌必須開啟，才能TOKEN_QUERY存取。

傳回值

如果函式成功，函式會傳回非零。

如果函式失敗，則會傳回零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

如果 AutoInheritFlags 參數為零， SetPrivateObjectSecurityEx 與 SetPrivateObjectSecurity 函式相同。

此函式僅供資源管理員使用。 若要實作更新安全性描述元的標準 Windows 訪問控制語意，資源管理員應該先確認符合下列條件，再呼叫 SetPrivateObjectSecurityEx：

  • 如果要設定對象的擁有者，呼叫 進程 必須具有WRITE_OWNER許可權，或是對象的擁有者。
  • 如果要設定物件的 DACL，呼叫進程必須具有WRITE_DAC許可權，或是對象的擁有者。
  • 如果設定物件的 SACL，則必須為呼叫進程啟用SE_SECURITY_NAME許可權。
如果不符合上述條件，此函式的呼叫不會失敗，但是不會強制執行標準 Windows 存取原則。

呼叫此函式的進程不應該模擬客戶端，因為用戶端通常沒有基礎令牌作業所需的適當許可權。

如果 AutoInheritFlags 指定SEF_DACL_AUTO_INHERIT位，函式會將下列規則套用至 DACL，以從目前的描述項建立新的安全性描述元：

  • 如果未在目前安全性描述項或 ModificationDescriptor的控制位中設定SE_DACL_PROTECTED旗標，則函式會從目前安全性描述元的繼承 ACE 和 Noninherited ACE 的 ModificationDescriptor 建構輸出安全性描述元。 也就是說，在對象上變更 ACL) (訪問控制清單 ，就無法變更繼承的 ACE。 此行為會保留繼承的 ACE，因為它們繼承自父容器。

    ACL 編輯器應該讓繼承的 ACE 無法使用，以防止它們遭到修改。

  • 如果在 ModificationDescriptor 中設定SE_DACL_PROTECTED，則會忽略目前的安全性描述元。 輸出安全性描述元會建置為已關閉任何INHERITED_ACE位的 ModificationDescriptor 複本。

    在理想情況下，ACL 編輯器應該關閉INHERITED_ACE位，指出 ACE 繼承自物件父系的 ACE 現在已在對象上明確設定。

  • 如果SE_DACL_PROTECTED是在目前的安全性描述元中設定，而不是 在ModificationDescriptor中設定，則會忽略目前的安全性描述元。 輸出安全性描述元會建置為 ModificationDescriptor的複本。 呼叫者必須負責確保正確的 ACE 已開啟INHERITED_ACE位。
如果 AutoInheritFlags 指定SEF_SACL_AUTO_INHERIT位，則函式會將類似的規則套用至新的 SACL。

針對 DACL 和 SCL，輸入 ObjectsSecurityDescriptor 和 ModificationDescriptor 中的特定 ACE 類型將會由輸出 ObjectsSecurityDescriptor 中的兩個 ACE 取代。 具體而言，至少包含下列其中一個可對應的元素的可繼承 ACE 會導致輸出 ObjectsSecurityDescriptor 中有兩個 ACE。 可對應的元素包括：

  • ACCESS_MASK 結構中的一般訪問許可權
  • 建立者擁有者 SID 或建立者群組 SID 作為 ACE 主體標識碼
具有上述任一可對應元素的 ACE 會導致輸出 ObjectsSecurityDescriptor 中的下列兩個 ACE：
  • ACE，其為原始復本，但已設定INHERIT_ONLY旗標
  • 開啟INHERITED_ACE位且泛型項目會對應至特定專案的 ACE：
    • 泛型訪問許可權會取代為輸入 GenericMapping 中所指出的對應標準和特定訪問許可權。
    • 建立者擁有者 SID 會取代為輸出 SecurityDescriptor 中的擁有者
    • 建立者群組 SID 會取代為輸出 SecurityDescriptor 中的群組
如果 AutoInheritFlags 未指定SEF_AVOID_PRIVILEGE_CHECK位，則會根據下列規則執行擁有者有效性檢查。 ModificationDescriptor 中的擁有者：
  • 必須是合法形式的 SID
  • 必須符合 Token 中的 TokenUser
Or
  • 必須符合 TokenGroups 中 TokenGroups 中的群組，其中群組上的屬性：
    • 包含SE_GROUP_OWNER
    • 包含SE_GROUP_USE_FOR_DENY_ONLY
在物件的子樹上設定 Owner 的資源管理員，可以避免重複擁有者有效性檢查的額外負荷。 如果 ModificationDescriptor 和 Token 中的擁有者在此函式的反覆呼叫中維持不變，則SEF_AVOID_PRIVILEGE_CHECK位可能會在 AutoInheritFlags 中設定，以便執行擁有者有效性檢查的初始呼叫之後進行呼叫。 沒有用戶端令牌存取權的呼叫端，最終將設定擁有者也應該選擇略過擁有者驗證檢查。
注意SetPrivateObjectSecurityEx 函式中使用的SEF_AVOID_PRIVILEGE_CHECK位相當於 CreatePrivateObjectSecurityEx 函式中使用的SEF_AVOID_OWNER_CHECK位。
 

規格需求

需求 值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限桌面應用程式]
目標平台 Windows
標頭 securitybaseapi.h (包含 Windows.h)
程式庫 Advapi32.lib
Dll Advapi32.dll

另請參閱

ACCESS_MASK

用戶端/伺服器 存取控制 函式

用戶端/伺服器 存取控制 概觀

CreatePrivateObjectSecurityEx

DestroyPrivateObjectSecurity

GENERIC_MAPPING

GetPrivateObjectSecurity

SECURITY_DESCRIPTOR

SECURITY_INFORMATION

SetFileSecurity

SetKernelObjectSecurity

SetPrivateObjectSecurity

SetUserObjectSecurity