CreatePrivateObjectSecurityEx

The CreatePrivateObjectSecurityEx function allocates and initializes a self-relative security descriptor for a new private object. A protected server calls this function when it creates a new private object.

BOOL CreatePrivateObjectSecurityEx(
  PSECURITY_DESCRIPTOR ParentDescriptor,  // parent object SD
  PSECURITY_DESCRIPTOR CreatorDescriptor, // SD of object
  PSECURITY_DESCRIPTOR *NewDescriptor,    // new SD
  GUID *ObjectType,                       // object type
  BOOL IsContainerObject,                 // container status
  ULONG AutoInheritFlags,                 // inheritance options
  HANDLE Token,                           // handle to access token
  PGENERIC_MAPPING GenericMapping         // mapping options
);

Parameters

ParentDescriptor

[in] Pointer to the security descriptor for the parent container of the object. If there is no parent container, this parameter is NULL.

CreatorDescriptor

[in] 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.

NewDescriptor

[out] Pointer to a variable that receives a pointer to the newly allocated self-relative security descriptor. The caller must call the DestroyPrivateObjectSecurity function to free this security descriptor.

ObjectType

[in] Pointer to a GUID structure that identifies the type of object associated with CurrentSecurityDescriptor. Set ObjectType to NULL if the object does not have a GUID.

IsContainerObject

[in] 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.

AutoInheritFlags

[in] A set of bit flags that control how ACEs are inherited from ParentDescriptor. This parameter can be a combination of the following values.

Value	Meaning
SEF_DACL_AUTO_INHERIT	If this flag is set, the new DACL contains ACEs inherited from the DACL of the ParentDescriptor, as well as any explicit ACEs specified in the DACL of the CreatorDescriptor. If this flag is not set, the new DACL does not inherit ACEs.
SEF_SACL_AUTO_INHERIT	If this flag is set, the new SACL contains ACEs inherited from the SACL of the ParentDescriptor, as well as any explicit ACEs specified in the SACL of the CreatorDescriptor. If this flag is not set, the new SACL does not inherit ACEs.
SEF_DEFAULT_DESCRIPTOR_FOR_OBJECT	If this flag is set, the CreatorDescriptor is the default descriptor for the type of object specified by ObjectType. As such, the CreatorDescriptor is ignored if the ParentDescriptor has any object-specific ACEs for the type of object specified by the ObjectType-parameter. If no such ACEs are inherited, the CreatorDescriptor is handled as though this flag were not specified.
SEF_AVOID_PRIVILEGE_CHECK	If this flag is set, 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.
SEF_AVOID_OWNER_CHECK	If this flag is set, the function does not check the validity of the owner in the resultant NewDescriptor. If the SEF_AVOID_PRIVILEGE_CHECK flag is also set, the Token parameter can be NULL.
SEF_DEFAULT_OWNER_FROM_PARENT	If this flag is set, 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.
SEF_DEFAULT_GROUP_FROM_PARENT	If this flag is set, 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.

Token

[in] 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.

GenericMapping

[in] Pointer to a GENERIC_MAPPING structure that specifies the mapping from each generic right to specific rights for the object.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The CreatePrivateObjectSecurity function is identical to calling the CreatePrivateObjectSecurityEx function with ObjectType set to NULL and AutoInheritFlags set to zero.

The AutoInheritFlags are 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.

If AutoInheritFlags specifies the SEF_SACL_AUTO_INHERIT bit, the function applies similar rules to the new SACL.

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.

To verify the current security descriptor on an object, call CreatePrivateObjectSecurityEx with ParentDescriptor set to the security descriptor of the parent container and CreatorDescriptor set to the current security descriptor of the object. This call ensures that the ACEs are appropriately inherited from parent to child security descriptors.

If the CreatorDescriptor security descriptor contains a SACL, Token must have the SE_SECURITY_NAME privilege enabled. The CreatePrivateObjectSecurityEx function checks this privilege and may generate audits if it not enabled.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Advapi32.lib.

See Also

Client/Server Access Control Overview, Client/Server Access Control Functions, DestroyPrivateObjectSecurity, GENERIC_MAPPING, GetTokenInformation, OpenProcessToken, SECURITY_DESCRIPTOR, SECURITY_IMPERSONATION_LEVEL, SetPrivateObjectSecurityEx