This section shows how to manage ACLs, how to associate an ACL with a security descriptor, and how to add ACEs. Figure 15-1 shows the relationships between these objects and functions.
The first step is to initialize an ACL structure. The ACL should not be accessed directly, so its internal structure is not relevant. The program must, however, provide a buffer to serve as the ACL; the functions manage the contents.
BOOL InitializeAcl ( PACL pAcl, DWORD cbAcl, DWORD dwAclRevision)
pAcl is the address of a programmer-supplied buffer of cbAcl bytes. Subsequent discussion and Program 15-4 will show how to determine the ACL size, but 1KB is more than adequate for most purposes. dwAclRevision should be ACL_REVISION.
Next, add the ACEs in the order desired with the AddAccessAllowedAce and AddAccessDeniedAce functions.
BOOL AddAccessAllowedAce ( PACL pAcl, DWORD dwAclRevision DWORD dwAccessMask, PSID pSid) BOOL AddAccessDeniedAce ( PACL pAcl, DWORD dwAclRevision, DWORD dwAccessMask, PSID pSid)
pAcl points to the same ACL structure initialized with InitializeAcl, and dwAclRevision is ACL_REVISION again. pSid points to a SID, such as one that would be obtained from LookupAccountName.
The access mask (dwAccessMask) determines the rights to be granted or denied to the user or group specified by the SID. The predefined mask values will vary by the object type.
The final step is to associate an ACL with the security descriptor. In the case of the discretionary ACL, use the SetSecurityDescriptorDacl function.
BOOL SetSecurityDescriptorDacl ( PSECURITY_DESCRIPTOR pSecurityDescriptor, BOOL bDaclPresent, PACL pAcl, BOOL fDaclDefaulted)
bDaclPresent, if TRUE, indicates that there is an ACL in the pAcl structure. If FALSE, pAcl and fDaclDefaulted, the next two parameters, are ignored. The SECURITY_DESCRIPTOR_CONTROL's SE_DACL_PRESENT flag is also set to this parameter's value.