CreatePrivateObjectSecurityEx function (securitybaseapi.h)
The CreatePrivateObjectSecurityEx function allocates and initializes a self-relative security descriptor for a new private object created by the resource manager calling this function.
Syntax
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
);
Parameters
[in, optional] ParentDescriptor
A pointer to the security descriptor for the parent container of the object. If there is no parent container, this parameter is NULL.
[in, optional] CreatorDescriptor
A pointer to a security descriptor provided by the creator of the object. If the object's creator does not explicitly pass security information for the new object, this parameter can be NULL. Alternatively, this parameter can point to a default security descriptor.
[out] NewDescriptor
A pointer to a variable that receives a pointer to the newly allocated self-relative security descriptor. When you have finished using the security descriptor, free it by calling the
DestroyPrivateObjectSecurity function.
[in, optional] ObjectType
A pointer to a GUID structure that identifies the type of object associated with NewDescriptor. If the object does not have a GUID, set ObjectType to NULL.
[in] IsContainerObject
Specifies whether the new object can contain other objects. A value of TRUE indicates that the new object is a container. A value of FALSE indicates that the new object is not a container.
[in] AutoInheritFlags
A set of bit flags that control how access control entries (ACEs) are inherited from ParentDescriptor. This parameter can be a combination of the following values.
| Value | Meaning |
|---|---|
|
The function does not check the validity of the owner in the resultant NewDescriptor as described in Remarks below. If the SEF_AVOID_PRIVILEGE_CHECK flag is also set, the Token parameter can be NULL. |
|
Any restrictions specified by the ParentDescriptor that would limit the caller's ability to specify a DACL in the CreatorDescriptor are ignored. |
|
The function does not perform privilege checking. If the SEF_AVOID_OWNER_CHECK flag is also set, the Token parameter can be NULL. This flag is useful while implementing automatic inheritance to avoid checking privileges on each child updated. |
|
The new discretionary access control list (DACL) contains ACEs inherited from the DACL of ParentDescriptor, as well as any explicit ACEs specified in the DACL of CreatorDescriptor. If this flag is not set, the new DACL does not inherit ACEs. |
|
CreatorDescriptor is the default descriptor for the type of object specified by ObjectType. As such, CreatorDescriptor is ignored if ParentDescriptor has any object-specific ACEs for the type of object specified by the ObjectType parameter. If no such ACEs are inherited, CreatorDescriptor is handled as though this flag were not specified. |
|
The group of NewDescriptor defaults to the group from ParentDescriptor. If not set, the group of NewDescriptor defaults to the group of the token specified by the Token parameter. The group of the token is specified in the token itself. In either case, if the CreatorDescriptor parameter is not NULL, the NewDescriptor group is set to the group from CreatorDescriptor. |
|
The owner of NewDescriptor defaults to the owner from ParentDescriptor. If not set, the owner of NewDescriptor defaults to the owner of the token specified by the Token parameter. The owner of the token is specified in the token itself. In either case, if the CreatorDescriptor parameter is not NULL, the NewDescriptor owner is set to the owner from CreatorDescriptor. |
|
When this flag is set, the mandatory label ACE in CreatorDescriptor is not used to create a mandatory label ACE in NewDescriptor. Instead, a new SYSTEM_MANDATORY_LABEL_ACE with an access mask of SYSTEM_MANDATORY_LABEL_NO_EXECUTE_UP and the SID from the token's integrity SID is added to NewDescriptor. |
|
When this flag is set, the mandatory label ACE in CreatorDescriptor is not used to create a mandatory label ACE in NewDescriptor. Instead, a new SYSTEM_MANDATORY_LABEL_ACE with an access mask of SYSTEM_MANDATORY_LABEL_NO_READ_UP and the SID from the token's integrity SID is added to NewDescriptor. |
|
When this flag is set, the mandatory label ACE in CreatorDescriptor is not used to create a mandatory label ACE in NewDescriptor. Instead, a new SYSTEM_MANDATORY_LABEL_ACE with an access mask of SYSTEM_MANDATORY_LABEL_NO_WRITE_UP and the SID from the token's integrity SID is added to NewDescriptor. |
|
The new system access control list (SACL) contains ACEs inherited from the SACL of ParentDescriptor, as well as any explicit ACEs specified in the SACL of CreatorDescriptor. If this flag is not set, the new SACL does not inherit ACEs. |
[in, optional] Token
A handle to the access token for the client process on whose behalf the object is being created. If this is an impersonation token, it must be at SecurityIdentification level or higher. For a full description of the SecurityIdentification impersonation level, see the SECURITY_IMPERSONATION_LEVEL enumerated type.
The client token contains default security information, such as the default owner, primary group, and DACL. The function uses these defaults if the information is not in the input security descriptors. The token must be open for TOKEN_QUERY access.
If all of the following conditions are true, then the handle must be opened for TOKEN_DUPLICATE access in addition to TOKEN_QUERY access.
- The token handle refers to a primary token.
- The security descriptor of the token contains one or more ACEs with the OwnerRights SID.
- A security descriptor is specified for the CreatorDescriptor parameter.
- The caller of this function does not set the SEF_AVOID_OWNER_RESTRICTION flag in the AutoInheritFlags parameter.
[in] GenericMapping
A pointer to a GENERIC_MAPPING structure that specifies the mapping from each generic right to specific rights for the object.
Return value
If the function succeeds, the function returns nonzero.
If the function fails, it returns zero. To get extended error information, call GetLastError. Some of the extended error codes and their meanings are listed in the following table.
| Return code | Description |
|---|---|
|
The function cannot retrieve an owner for the new security descriptor or the SID cannot be assigned as an owner. This occurs when validating the owner SID against the passed-in token. |
|
The function cannot retrieve a primary group for the new security descriptor. |
|
The function received NULL instead of a token for owner validation or privilege checking. |
|
A SACL is being set, SEF_AVOID_PRIVILEGE_CHECK was not passed in, and the token passed in did not have SE_SECURITY_NAME enabled. |
Remarks
The CreatePrivateObjectSecurity function is identical to calling the CreatePrivateObjectSecurityEx function with ObjectType set to NULL and AutoInheritFlags set to zero.
The AutoInheritFlags parameter is distinct from the similarly named bits in the Control member of the SECURITY_DESCRIPTOR structure. For an explanation of the control bits, see SECURITY_DESCRIPTOR_CONTROL.
If AutoInheritFlags specifies the SEF_DACL_AUTO_INHERIT bit, the function applies the following rules to the DACL in the new security descriptor:
- The SE_DACL_AUTO_INHERITED flag is set in the Control member of the new security descriptor.
- The DACL of the new security descriptor inherits ACEs from the ParentDescriptor regardless of whether CreatorDescriptor is the default security descriptor or was explicitly specified by the creator. The new DACL is a combination of the parent and creator DACLs as defined by the rules of inheritance.
- Inherited ACEs are marked as INHERITED_ACE.
For both DACLs and SACLs, certain types of ACEs in ParentDescriptor and CreatorDescriptor will be manipulated and possibly replaced by two ACEs in NewDescriptor. Specifically, an inheritable ACE that contains at least one of the following mappable elements may result in two ACEs in the output security descriptor. Mappable elements include:
- Generic access rights in the ACCESS_MASK
- Creator Owner SID or Creator Group SID as the ACE subject identifier
- An ACE that is a copy of the original, but with the INHERIT_ONLY flag set. However, this ACE will not be created if either of the following two conditions exist:
- The IsContainerObject parameter is FALSE. Inheritable ACEs are meaningless on noncontainer objects.
- The original ACE contains the NO_PROPAGATE_INHERIT flag. The original ACE is intended to be inherited as an effective ACE on children, but not inheritable below those children.
- An effective ACE in which the INHERITED_ACE bit is turned on and the generic elements are mapped to specific elements, including:
- Generic access rights are replaced by the corresponding standard and specific access rights indicated in the input GenericMapping.
- Creator Owner SID is replaced with the Owner in the resultant NewDescriptor
- Creator Group SID is replaced with the Group in the resultant NewDescriptor
Callers that do not have access to the token of the client that will ultimately be setting the owner may choose to skip owner validation checking.
To create a security descriptor for a new object, call CreatePrivateObjectSecurityEx with ParentDescriptor set to the security descriptor of the parent container and CreatorDescriptor set to the security descriptor proposed by the creator of the object.
If the CreatorDescriptor security descriptor contains a SACL, Token must have the SE_SECURITY_NAME privilege enabled or the caller must specify the SEF_AVOID_PRIVILEGE_CHECK flag in AutoInheritFlags.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | securitybaseapi.h (include Windows.h) |
| Library | Advapi32.lib |
| DLL | Advapi32.dll |
See also
Client/Server Access Control Functions