CreatePrivateObjectSecurityEx

[This is preliminary documentation and subject to change.]

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.

The CreatePrivateObjectSecurityEx function is identical to the CreatePrivateObjectSecurity function except for the following:

• CreatePrivateObjectSecurityEx can specify the object type GUID of the new object
• CreatePrivateObjectSecurityEx can specify flags that control how ACEs are inherited from the security descriptor of the parent container.

BOOL CreatePrivateObjectSecurityEx(
  PSECURITY_DESCRIPTOR ParentDescriptor, 
                            // security descriptor of parent object
  PSECURITY_DESCRIPTOR CreatorDescriptor, 
                            // current security descriptor of object
  PSECURITY_DESCRIPTOR *NewDescriptor, 
                            // receives the new security descriptor
  GUID * ObjectType,        // type of object
  BOOL IsContainerObject,   // identifies container objects
  ULONG AutoInheritFlags,   // identifies container objects
  HANDLE Token,             // identifies container objects
  PGENERIC_MAPPING GenericMapping  // map generic to specific rights
);
 

Parameters

ParentDescriptor

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

CreatorDescriptor

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

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

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

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

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. The Token parameter can be NULL. This flag is useful while implementing automatic inheritance to avoid checking privileges on each child updated.

Token

Identifies 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

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, and the caller's token must have the SE_AUDIT_NAME privilege enabled. The CreatePrivateObjectSecurityEx function checks these privileges, and may generate audits if they are not enabled.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use advapi32.lib.

See Also

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