CreatePrivateObjectSecurityEx 函式 (securitybaseapi.h)

  • 發行項

CreatePrivateObjectSecurityEx 函式會配置並初始化資源管理員呼叫此函式之新私用物件之自我相對安全性描述元。

語法

BOOL CreatePrivateObjectSecurityEx(
  [in, optional] PSECURITY_DESCRIPTOR ParentDescriptor,
  [in, optional] PSECURITY_DESCRIPTOR CreatorDescriptor,
  [out]          PSECURITY_DESCRIPTOR *NewDescriptor,
  [in, optional] GUID                 *ObjectType,
  [in]           BOOL                 IsContainerObject,
  [in]           ULONG                AutoInheritFlags,
  [in, optional] HANDLE               Token,
  [in]           PGENERIC_MAPPING     GenericMapping
);

參數

[in, optional] ParentDescriptor

物件父容器 之安全性描述元 的指標。 如果沒有父容器，則此參數為 NULL。

[in, optional] CreatorDescriptor

物件建立者提供之安全性描述元的指標。 如果物件的建立者未明確傳遞新對象的安全性資訊，這個參數可以是 NULL。 或者，此參數可以指向預設的安全性描述元。

[out] NewDescriptor

變數的指標，可接收新配置之自我相對安全性描述元的指標。 當您完成使用安全性描述元時，請呼叫 來釋放它
DestroyPrivateObjectSecurity 函式。

[in, optional] ObjectType

GUID 結構的指標，識別與 NewDescriptor 相關聯的物件類型。 如果對象沒有 GUID，請將 ObjectType 設定為 NULL。

[in] IsContainerObject

指定新物件是否可以包含其他物件。 TRUE 的值表示新物件是容器。 FALSE 值表示新物件不是容器。

[in] AutoInheritFlags

一組位旗標，控制 訪問控制專案 (ACE) 繼承自 ParentDescriptor 的方式。 此參數可以是下列值的組合。

值 意義
SEF_AVOID_OWNER_CHECK
0x10
 函式不會檢查結果 NewDescriptor 中擁有者的有效性，如下所述。 如果同時設定SEF_AVOID_PRIVILEGE_CHECK旗標， Token 參數可以是 NULL。
SEF_AVOID_OWNER_RESTRICTION
0x1000
 系統會忽略 ParentDescriptor 所指定的任何限制，以限制呼叫者在 CreatorDescriptor 中指定 DACL 的能力。
SEF_AVOID_PRIVILEGE_CHECK
0x08
 函式不會執行許可權檢查。 如果同時設定SEF_AVOID_OWNER_CHECK旗標， Token 參數可以是 NULL。 此旗標在實作自動繼承時很有用，以避免檢查每個更新子系的許可權。
SEF_DACL_AUTO_INHERIT
0x01
 新的 任意訪問控制清單 (DACL) 包含繼承自 ParentDescriptor DACL 的 ACL，以及 CreatorDescriptor DACL 中指定的任何明確 ACE。 如果未設定此旗標，則新的 DACL 不會繼承 ACE。
SEF_DEFAULT_DESCRIPTOR_FOR_OBJECT
0x04
 CreatorDescriptor 是 ObjectType 所指定物件類型的預設描述元。 因此，如果 ParentDescriptor 針對 ObjectType 參數所指定的物件類型，則會忽略 CreatorDescriptor。 如果沒有繼承這類 ACE， 則會處理 CreatorDescriptor ，就像未指定此旗標一樣。
SEF_DEFAULT_GROUP_FROM_PARENT
0x40
 NewDescriptor 群組預設為 ParentDescriptor 的群組。 如果未設定， NewDescriptor 的群組預設為 Token 參數所指定的 令牌 群組。 令牌的群組是在令牌本身中指定。 在任一情況下，如果 CreatorDescriptor 參數不是 NULL， 則 NewDescriptor 群組會設定為 CreatorDescriptor 中的群組。
SEF_DEFAULT_OWNER_FROM_PARENT
0x20
 NewDescriptor 的擁有者預設為 ParentDescriptor 的擁有者。 如果未設定， NewDescriptor 的擁有者預設為 Token 參數所指定的 令牌 擁有者。 令牌的擁有者是在令牌本身中指定。 在這兩種情況下，如果 CreatorDescriptor 參數不是 NULL， 則 NewDescriptor 擁有者會設定為 CreatorDescriptor 的擁有者。
SEF_MACL_NO_EXECUTE_UP
0x400
 設定此旗標時， CreatorDescriptor 中的強制標籤 ACE 不會用來在 NewDescriptor 中建立強制標籤 ACE。 相反地，具有SYSTEM_MANDATORY_LABEL_NO_EXECUTE_UP存取遮罩的新SYSTEM_MANDATORY_LABEL_ACE，而令牌完整性 SID 中的 SID 會新增至 NewDescriptor。
SEF_MACL_NO_READ_UP
0x200
 設定此旗標時， CreatorDescriptor 中的強制標籤 ACE 不會用來在 NewDescriptor 中建立強制標籤 ACE。 相反地，具有SYSTEM_MANDATORY_LABEL_NO_READ_UP存取遮罩的新SYSTEM_MANDATORY_LABEL_ACE，而令牌完整性 SID 中的 SID 會新增至 NewDescriptor。
SEF_MACL_NO_WRITE_UP
0x100
 設定此旗標時， CreatorDescriptor 中的強制標籤 ACE 不會用來在 NewDescriptor 中建立強制標籤 ACE。 相反地，具有SYSTEM_MANDATORY_LABEL_NO_WRITE_UP存取遮罩的新SYSTEM_MANDATORY_LABEL_ACE，而令牌完整性 SID 中的 SID 會新增至 NewDescriptor。
SEF_SACL_AUTO_INHERIT
0x02
 新的 系統訪問控制清單 (SACL) 包含繼承自 ParentDescriptor SACL 的 ACE，以及 CREATORDescriptor SACL 中指定的任何明確 ACE。 如果未設定此旗標，新的 SACL 不會繼承 ACE。

[in, optional] Token

客戶端進程的存取令牌句柄，其代表正在建立物件。 如果這是 模擬令牌，它必須位於 SecurityIdentification 層級或更高層級。 如需 SecurityIdentification 模擬層級的完整描述，請參閱 SECURITY_IMPERSONATION_LEVEL 列舉類型。

用戶端令牌包含預設安全性資訊，例如預設擁有者、主要群組和 DACL。 如果資訊不在輸入安全性描述元中，函式會使用這些預設值。 令牌必須開啟才能 TOKEN_QUERY 存取。

如果下列所有條件都成立，則除了 TOKEN_QUERY 存取之外，還必須開啟句柄以供 TOKEN_DUPLICATE 存取。

  • 令牌句柄是指主要令牌。
  • 令牌的安全性描述元包含一或多個具有 OwnerRights SID 的 ACE。
  • 為 CreatorDescriptor 參數指定安全性描述元。
  • 此函式的呼叫端不會在 AutoInheritFlags 參數中設定SEF_AVOID_OWNER_RESTRICTION旗標。

[in] GenericMapping

GENERIC_MAPPING 結構的指標，指定每個泛型許可權與物件特定許可權的對應。

傳回值

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

如果函式失敗，它會傳回零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。 下表列出一些擴充錯誤碼及其意義。

傳回碼 Description
ERROR_INVALID_OWNER
 函式無法擷取新安全性描述元的擁有者，或無法將 SID 指派為擁有者。 針對傳入的令牌驗證擁有者 SID 時，就會發生這種情況。
ERROR_INVALID_PRIMARY_GROUP
 函式無法擷取新安全性描述元的主要群組。
ERROR_NO_TOKEN
 函式收到 NULL ，而不是擁有者驗證或許可權檢查的令牌。
ERROR_PRIVILEGE_NOT_HELD
 正在設定 SACL，SEF_AVOID_PRIVILEGE_CHECK未傳入，而傳入的令牌未啟用SE_SECURITY_NAME。

備註

CreatePrivateObjectSecurity 函式與呼叫 CreatePrivateObjectSecurityEx 函式相同，且 ObjectType 設定為 NULL 且 AutoInheritFlags 設定為零。

AutoInheritFlags 參數與 SECURITY_DESCRIPTOR 結構的 Control 成員中類似的具名位不同。 如需控件位的說明，請參閱 SECURITY_DESCRIPTOR_CONTROL。

如果 AutoInheritFlags 指定SEF_DACL_AUTO_INHERIT位，函式會將下列規則套用至新安全性描述元中的 DACL：

  • SE_DACL_AUTO_INHERITED旗標是在新安全性描述元的 Control 成員中設定。
  • 不論 CreatorDescriptor 是預設的安全性描述元，還是由建立者明確指定，新安全性描述元的 DACL 都會從 ParentDescriptor 繼承 ACE。 新的 DACL 是父系和建立者 DACL 的組合，如繼承規則所定義。
  • 繼承的 ACE 會標示為INHERITED_ACE。
如果 AutoInheritFlags 指定SEF_SACL_AUTO_INHERIT位，則函式會將類似的規則套用至新的 SACL。

對於 DACL 和 SCL， 將會操作 ParentDescriptor 和 CreatorDescriptor 中特定類型的 ACE，而且可能由 NewDescriptor 中的兩個 ACE 取代。 具體而言，至少包含下列其中一個可對應元素的可繼承 ACE 可能會導致輸出安全性描述元中有兩個 ACE。 可對應的元素包括：

  • ACCESS_MASK中的一般訪問許可權
  • 建立者擁有者 SID 或建立者群組 SID 作為 ACE 主體標識碼
具有上述任一可對應元素的 ACE 會導致 NewDescriptor 中的下列 ACE：
  • ACE，這是原始的複本，但已設定INHERIT_ONLY旗標。 不過，如果下列兩個條件存在，將不會建立此 ACE：
    • IsContainerObject 參數為 FALSE。 可繼承的 ACE 在非容器對象上沒有意義。
    • 原始 ACE 包含NO_PROPAGATE_INHERIT旗標。 原始 ACE 的目的是要繼承為子系的有效 ACE，但無法繼承到這些子系下方。
  • 有效的 ACE，其中已開啟INHERITED_ACE位，而泛型元素會對應至特定元素，包括：
    • 泛型訪問許可權會取代為輸入 GenericMapping 中所指出的對應標準和特定訪問許可權。
    • 建立者擁有者 SID 會取代為結果 NewDescriptor 中的擁有者
    • 建立者群組 SID 會取代為結果 NewDescriptor 中的群組
如果 AutoInheritFlags 未指定SEF_AVOID_OWNER_CHECK位，則會執行擁有者有效性檢查。 結果 NewDescriptor 中的擁有者必須是合法形式的 SID，而且必須符合 Token 中的 TokenUser，或符合 令牌 中 TokenGroups 中的群組，其中群組上的屬性必須包含SE_GROUP_OWNER，且不得包含SE_GROUP_USE_FOR_DENY_ONLY。

無法存取用戶端令牌的呼叫端，最終將設定擁有者可以選擇略過擁有者驗證檢查。

若要為新物件建立安全性描述元，請呼叫 CreatePrivateObjectSecurityEx ，並將 ParentDescriptor 設定為父容器的安全性描述元，並將 CreatorDescriptor 設定為物件建立者所建議的安全性描述元。

如果 CreatorDescriptor 安全性描述元 包含 SACL， 令牌 必須啟用SE_SECURITY_NAME許可權，否則呼叫端必須在 AutoInheritFlags 中指定SEF_AVOID_PRIVILEGE_CHECK旗標。

規格需求

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

另請參閱

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

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

CreatePrivateObjectSecurity

DestroyPrivateObjectSecurity

GENERIC_MAPPING

GUID

GetTokenInformation

OpenProcessToken

SECURITY_DESCRIPTOR

SECURITY_DESCRIPTOR_CONTROL

SECURITY_IMPERSONATION_LEVEL

SetPrivateObjectSecurityEx