Microsoft KB Archive/102103

INFO: Computing the Size of a New ACL

Q102103

The information in this article applies to:

Microsoft Win32 Application Programming Interface (API), used with:
- the operating system: Microsoft Windows NT, versions 3.1, 3.5
- the operating system: Microsoft Windows 2000

SUMMARY

When adding an access-allowed access control entry (ACE) to a discretionary access control list (DACL), it is useful to know the exact size needed for the new DACL. This is particularly useful when creating a new DACL and copying over the existing ACEs. The below code computes the size needed for a DACL if an access-allowed ACE is added:

   ACL_SIZE_INFORMATION AclInfo;

   GetAclInformation(pACL,&AclInfo,sizeof(ACL_SIZE_INFORMATION),
                     AclSizeInformation))

   dwNewACLSize = AclInfo.AclBytesInUse +
                  sizeof(ACCESS_ALLOWED_ACE) +
                  GetLengthSid(UserSID) - sizeof(DWORD);

MORE INFORMATION

The call to GetAclInformation() takes a pointer to an ACL. This point is supplied by your program and should point to the DACL you want to add an access-allowed ACE to. The GetAclInformation() call fills out a ACL_SIZE_INFORMATION structure, which provides size information on the ACL.

The second statement computes what the new size of the ACL will be if an access-allowed ACE is added. This is accomplished by adding the current bytes being used to the size of an ACCESS_ALLOWED_ACE. We then add the size of the security identifier (SID) (provided by your application) that is to used in the AddAccessAllowedAce() API call. Subtracting out the size of a DWORD is the final adjustment needed to obtain the exact size. This adjust is to compensate for a place holder member in the ACCESS_ALLOWED_ACE structure which is used in variable length ACEs.

When adding an ACE to an existing ACL, often there is not enough free space in the ACL to accommodate the additional ACE. In this situation, it is necessary to allocate a new ACL and copy over the existing ACEs and then add the access-allowed ACE. The above code can be used to determine the amount of memory to allocate for the new ACL.

Additional query words: 3.10 3.50

Keywords : kbAccCtrl kbOSWin2000 kbSecurity kbDSupport
Issue type : kbinfo
Technology : kbAudDeveloper kbWin32sSearch kbWin32API