SetSecurityDescriptorControl

[This is preliminary documentation and subject to change.]

The SetSecurityDescriptorControl function sets the control bits of a security descriptor. The function can set only the control bits that relate to automatic inheritance of ACEs. To set the other control bits of a security descriptor, use the Win32 functions, such as SetSecurityDescriptorDacl, for modifying the components of a security descriptor.

BOOL SetSecurityDescriptorControl(
  PSECURITY_DESCRIPTOR pSecurityDescriptor,    // security descriptor
  SECURITY_DESCRIPTOR_CONTROL ControlBitsOfInterest,  // bits to set
  SECURITY_DESCRIPTOR_CONTROL ControlBitsToSet // new control bits 
);
 

Parameters

pSecurityDescriptor

Pointer to a SECURITY_DESCRIPTOR structure whose control and revision information are set.

ControlBitsOfInterest

A SECURITY_DESCRIPTOR_CONTROL mask that indicates the control bits to set. This mask can be a combination of the following flags.

Value	Meaning
SE_DACL_AUTO_INHERIT_REQ	Requests that the provider for the object protected by the security descriptor automatically propagate the DACL to existing child objects. If the provider supports automatic inheritance, it propagates the DACL to any existing child objects, and sets the SE_DACL_AUTO_INHERITED bit in the security descriptors of the object and its child objects.
SE_DACL_AUTO_INHERITED	Indicates a security descriptor in which the DACL is set up to support automatic propagation of inheritable ACEs to existing child objects. This bit is set only if the automatic inheritance algorithm has been performed for the object and its existing child objects. This bit is not set in security descriptors for Windows NT versions 4.0 and earlier, which did not support automatic propagation of inheritable ACEs.
SE_DACL_PROTECTED	Protects the DACL of the security descriptor from being modified by inheritable ACEs.
SE_SACL_AUTO_INHERIT_REQ	Requests that the provider for the object protected by the security descriptor automatically propagate the SACL to existing child objects. If the provider supports automatic inheritance, it propagates the SACL to any existing child objects, and sets the SE_SACL_AUTO_INHERITED bit in the security descriptors of the object and its child objects.
SE_SACL_AUTO_INHERITED	Indicates a security descriptor in which the SACL is set up to support automatic propagation of inheritable ACEs to existing child objects. This bit is set only if the automatic inheritance algorithm has been performed for the object and its existing child objects. This bit is not set in security descriptors for Windows NT versions 4.0 and earlier, which did not support automatic propagation of inheritable ACEs.
SE_SACL_PROTECTED	Protects the SACL of the security descriptor from being modified by inheritable ACEs.

ControlBitsToSet

A SECURITY_DESCRIPTOR_CONTROL mask that indicates the new values for the control bits specified by the ControlBitsOfInterest mask. This parameter can be a combination of the flags listed for the ControlBitsOfInterest parameter.

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 SetSecurityDescriptorControl function specifies the control bit or bits to modify, and whether the bits are on or off. For example, the following code marks the DACL on the security descriptor as protected:

SetSecurityDescriptorControl( &SecDesc,
            SE_DACL_PROTECTED, SE_DACL_PROTECTED );
 

And this code marks the DACL as not protected:

SetSecurityDescriptorControl( &SecDesc,
            SE_DACL_PROTECTED, 0 );
 

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

Access Control Overview, Access Control Functions, GetSecurityDescriptorControl, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL