Microsoft KB Archive/188760

HOWTO: Specify Access Control on Window NT/Windows 2000 Container Objects

Q188760

The information in this article applies to:

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

SUMMARY

Programmatically specifying access control for Windows NT container objects is more complex than for other Win32 objects. This is because access control on container objects allows you to specify access to the container and access for objects that will be created in the container in the future.

MORE INFORMATION

A Windows NT securable object is a container if it can logically contain other securable objects. The following table shows the relationship between a container object and the objects it might contain:

   Container Object         Objects Contained
   -----------------------------------------------

   Directory                Files/Directories

   Registry Key             Registry Subkeys

   Windowstation            Desktop

   Printer                  Print Jobs

Windows NT and Windows 2000 support Access Control List (ACL) inheritance. This means that when a new object is created within a container object, the new object inherits permissions (access control entries marked as inheritable) from the parent container object by default.

When you programmatically assign access control to container objects, you must explicitly set the inheritance attribute of each access control entry (ACE). Use the following flags to set the ACE inheritance properties:

CONTAINER_INHERIT_ACE - Child objects that are containers, such as directories, inherit the ACE as an effective ACE.
OBJECT_INHERIT_ACE - Noncontainer child objects, such as files, inherit the ACE as an effective ACE.
INHERIT_ONLY_ACE - The ACE does not apply to the object to which it is attached but can be inherited by child objects.

For a complete description of these and the other possible AceFlags values, see the Win32 Platform SDK documentation for the ACE_HEADER structure.

There are two ways to assign inheritance flags to an access control entry, described below. Both require familiarity with access control. For additional information, see the Win32 Platform SDK and the following article in the Microsoft Knowledge Base:

Q102102 HOWTO: Add an Access-Allowed ACE to a File

Once the ACE is in the discretionary access-control list (DACL) through AddAccessAllowed/DeniedAce(), set the AceFlags member of the new ACE. You do this by using the GetAce() API to retrieve a pointer to the new ACE. Use this pointer to set the AceFlags member of the ACE header structure as follows:

{  // You can add this to step 14 of Q102102, which demonstrates adding
   // an Access Allowed ACE to a DACL.

   // Add the access-allowed ACE to the new DACL.
   if(!AddAccessAllowedAce(pNewACL,ACL_REVISION2,dwAcessMask, pSid))
   {
   // Handle AddAccessAllowedAce Error.
   }

   // Get pointer to ACE you just added, so you can change the AceFlags.
   if(!GetAce( pNewACL,
               AclInfo.AceCount, // last ACE in Acl (Zero indexed),
                                 // We added one after we got the count
                                 // So we don't subtract one here
               &pTempAce ))
   {
   // Handle GetAce Error.
   }

   // Set AceFlags member.
   pTempAce->Header.AceFlags = bAceFlags;
}

This extra step is necessary because the AddAccessAllowedAce() API does not have a parameter to specify this attribute of a new ACE. Windows 2000 introduces the AddAccessAllowedAceEx() API, which does have a parameter to specify the AceFlags member of a new ACE. Applications should check for the existence of AddAccessAllowedAce() in Advapi32.dll by calling LoadLibrary() and GetProcessAddress() APIs.

Alternatively, you can build the entire ACE and set the AceFlags member of the ACE_Header Structure as follows:

Additional query words: directory sid special security printer

Keywords : kbAccCtrl kbAPI kbKernBase kbSDKWin32 kbSecurity kbDSupport kbGrpDSKernBase
Issue type : kbhowto
Technology : kbAudDeveloper kbWin32sSearch kbWin32API