SetSecurityDescriptorDacl function (securitybaseapi.h)

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 SetSecurityDescriptorDacl(
  [in, out]      PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]           BOOL                 bDaclPresent,
  [in, optional] PACL                 pDacl,
  [in]           BOOL                 bDaclDefaulted
);

Parameters

[in, out] pSecurityDescriptor

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.

[in] bDaclPresent

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.

[in, optional] pDacl

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.

[in] bDaclDefaulted

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

See also

GetSecurityDescriptorDacl

InitializeSecurityDescriptor

IsValidSecurityDescriptor

Low-level Access Control

Low-level Access Control Functions

SECURITY_DESCRIPTOR

SECURITY_DESCRIPTOR_CONTROL

SetSecurityDescriptorGroup

SetSecurityDescriptorOwner

SetSecurityDescriptorSacl