Expand Minimize

SetSecurityDescriptorDacl function

The SetSecurityDescriptorDacl function sets information in a discretionary access control list (DACL). If a DACL is already present in the security descriptor, the DACL is replaced.

Syntax


BOOL WINAPI SetSecurityDescriptorDacl(
  _Inout_   PSECURITY_DESCRIPTOR pSecurityDescriptor,
  _In_      BOOL bDaclPresent,
  _In_opt_  PACL pDacl,
  _In_      BOOL bDaclDefaulted
);

Parameters

pSecurityDescriptor [in, out]

A pointer to the SECURITY_DESCRIPTOR structure to which the function adds the DACL. This security descriptor must be in absolute format, meaning that its members must be pointers to other structures, rather than offsets to contiguous data.

bDaclPresent [in]

A flag that indicates the presence of a DACL in the security descriptor. If this parameter is TRUE, the function sets the SE_DACL_PRESENT flag in the SECURITY_DESCRIPTOR_CONTROL structure and uses the values in the pDacl and bDaclDefaulted parameters. If this parameter is FALSE, the function clears the SE_DACL_PRESENT flag, and pDacl and bDaclDefaulted are ignored.

pDacl [in, optional]

A pointer to an ACL structure that specifies the DACL for the security descriptor. If this parameter is NULL, a NULL DACL is assigned to the security descriptor, which allows all access to the object. The DACL is referenced by, not copied into, the security descriptor.

bDaclDefaulted [in]

A flag that indicates the source of the DACL. If this flag is TRUE, the DACL has been retrieved by some default mechanism. If FALSE, the DACL has been explicitly specified by a user. The function stores this value in the SE_DACL_DEFAULTED flag of the SECURITY_DESCRIPTOR_CONTROL structure. If this parameter is not specified, the SE_DACL_DEFAULTED flag is cleared.

Return value

If the function succeeds, the function returns nonzero.

If the function fails, it returns zero. To get extended error information, call GetLastError.

Remarks

There is an important difference between an empty and a nonexistent DACL. When a DACL is empty, it contains no access control entries (ACEs); therefore, no access rights are explicitly granted. As a result, access to the object is implicitly denied.

When an object has no DACL (when the pDacl parameter is NULL), no protection is assigned to the object, and all access requests are granted. To help maintain security, restrict access by using a DACL.

There are three possible outcomes in different configurations of the bDaclPresent flag and the pDacl parameter:

  • When the pDacl parameter points to a DACL and the bDaclPresent flag is TRUE, a DACL is specified and it must contain access-allowed ACEs to allow access to the object.
  • When the pDacl parameter does not point to a DACL and the bDaclPresent flag is TRUE, a NULL DACL is specified. All access is allowed. You should not use a NULL DACL with an object because any user can change the DACL and owner of the security descriptor. This will interfere with use of the object.
  • When the pDacl parameter does not point to a DACL and the bDaclPresent flag is FALSE, a DACL can be provided for the object through an inheritance or default mechanism.

Examples

For an example that uses this function, see Creating a Security Descriptor for a New Object.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Winbase.h (include Windows.h)

Library

Advapi32.lib

DLL

Advapi32.dll

See also

Low-level Access Control
Low-level Access Control Functions
GetSecurityDescriptorDacl
InitializeSecurityDescriptor
IsValidSecurityDescriptor
SECURITY_DESCRIPTOR
SECURITY_DESCRIPTOR_CONTROL
SetSecurityDescriptorGroup
SetSecurityDescriptorOwner
SetSecurityDescriptorSacl

 

 

Community Additions

ADD
Show:
© 2014 Microsoft