Sysinternals Freeware - Mark Russinovich & Bryce Cogswell

Documentation for NT 4.0 ACL Editors

Copyright 1998-2002 Mark Russinovich
Last Updated: May 3, 2002

ACL Editor Documentation

Windows 2000 introduces new security editors that are fully documented in the Platform SDK. However, NT 4.0's security editors, which are used by Reged32 and Explorer, have never been documented by Microsoft. Back when I implemented WinObj v2.0 I derived the interfaces for the NT system ACL (Access Control List) editors, which are implemented by acledit.dll. I've decided to now finally publicly document the APIs, which are useful for applications that wish to support standard security editing features under NT 4.0.

SedDiscretionaryAclEditor

This function pops up a discretionary ACL editor dialog box.

DWORD SedDiscretionaryAclEditor(
    HWND Owner,
    HINSTANCE Instance,
    PWCHAR MachineName, // optional
    PACLDLGCONTROL AclDlgControl,
    PACLEDITCONTROL AclEditControl,
    PWCHAR ObjectName,
    PACLCHANGE ChangeCallback,
    PVOID ChangeCallbackContext,
    PSECURITY_DESCRIPTOR ObjectSecurity,
    BOOLEAN NoReadPermission,
    BOOLEAN ReadOnly,
    PDWORD ChangeContextStatus,
    PVOID MustBeZero
);

Parameters

Owner

Handle to window of dialog owner.

Instance

This is the instance handle of the application that will be associated with the dialog box.

MachineName

This is an optional parameter that specifies the name of the computer (e.g. \\mark) where local account lookups for security descriptors will be performed. Specify NULL for the local machine.

AclDlgControl

Points to a caller supplied ACL dialog control data structure.

AclEditControl

Points to a caller-supplied ACL edit entry control data structure.

ObjectName

Specifies the text of the object name (e.g. "C:\temp\") field printed in the dialog box.

ChangeCallback

Callback that is invoked if the user enters changes into the editor and then dismisses the dialog.

ChangeCallbackContext

Context parameter that will be passed unchanged to the ChangeCallback procedure.

ObjectSecurity

The security descriptor associated with the object. The descriptor is interpreted with respect to user accounts and permissions and the information is displayed in the dialog box.

NoReadPermission

Tell the user that they cannot view the security information, but they can attempt to overwrite it if they want. The object security descriptor information is not displayed in the dialog.

ReadOnly

Tell the user that they can only view the object's security information. The Add and Remove buttons on the dialog are disabled.

ChangeContextStatus

The dialog ignores this value which it passes as a parameter to the change callback function. The change callback function can return a status code to the code that invoked the dialog box if a pointer to a status variable is passed for this parameter.

MustBeZero

Set to zero.

Returns

The function returns a non-zero value on failure. Failure is returned if the security context is invalid for example.

SedTakeOwnership

This function pops up an ownership editor dialog box.

DWORD SedTakeOwnership(
    HWND Owner,
    HINSTANCE Instance,
    PWCHAR MachineName, // optional
    PWCHAR ObjectType,
    PWCHAR ObjectName,
    DWORD ObjectCount,
    PACLCHANGE ChangeCallback,
    PVOID ChangeCallbackContext,
    PSECURITY_DESCRIPTOR ObjectSecurity,
    BOOLEAN NoReadPermission,
    BOOLEAN NoOwnerChange,
    PDWORD ChangeContextStatus,
    PACLHELPCONTROL HelpInfo,
    PVOID MustBeZero
);

Parameters

Owner

Handle to window of dialog owner.

Instance

This is the instance handle of the application that will be associated with the dialog box.

MachineName

This is an optional parameter that specifies the name of the computer (e.g. \\mark) where local account lookups for security descriptors will be performed. Specify NULL for the local machine.

ObjectType

Specifies the text that will displayed for the object type (e.g. "Directory").

ObjectName

Specifies the text of the object name (e.g. "C:\temp\") field printed in the dialog box.

ObjectCount

If more than one then ObjectName is ignored.

ChangeCallback

Callback that is invoked if the user enters changes into the editor and then dismisses the dialog.

ChangeCallbackContext

Context parameter that will be passed unchanged to the ChangeCallback procedure.

ObjectSecurity

The security descriptor associated with the object. The descriptor is interpreted with respect to user accounts and permissions and the information is displayed in the dialog box.

NoReadPermission

Tell the user that they cannot view the security information, but they can attempt to overwrite it if they want. The object security descriptor information is not displayed in the dialog.

NoOwnerChange

Set to true to indicate that the user doesn't have permission to change ownership of the object.

ChangeContextStatus

The dialog ignores this value which it passes as a parameter to the change callback function. The change callback function can return a status code to the code that invoked the dialog box if a pointer to a status variable is passed for this parameter.

HelpInfo

Pointer to a help information structure that is referenced when the user enters the Help button on the dialog box.

MustBeZero

Set to zero.

Returns

The function returns a non-zero value on failure. Failure is returned if the security context is invalid for example.

SedSystemAclEditor

This function pops up a system ACL editor dialog box.

DWORD SedSystemAclEditor(
    HWND Owner,
    HINSTANCE Instance,
    PWCHAR MachineName, // optional
    PACLDLGCONTROL AclDlgControl,
    PACLEDITCONTROL AclEditControl,
    PWCHAR ObjectName,
    PACLCHANGE ChangeCallback,
    PVOID ChangeCallbackContext,
    PSECURITY_DESCRIPTOR ObjectSecurity,
    BOOLEAN NoReadPermission,
    PDWORD ChangeContextStatus,
    PVOID MustBeZero
);

Parameters

Owner

Handle to window of dialog owner.

Instance

This is the instance handle of the application that will be associated with the dialog box.

MachineName

This is an optional parameter that specifies the name of the computer (e.g. \\mark) where local account lookups for security descriptors will be performed. Specify NULL for the local machine.

AclDlgControl

Points to a caller supplied ACL dialog control data structure.

AclEditControl

Points to a caller-supplied ACL edit entry control data structure.

ObjectName

Specifies the text of the object name (e.g. "C:\temp\") field printed in the dialog box.

ChangeCallback

Callback that is invoked if the user enters changes into the editor and then dismisses the dialog.

ChangeCallbackContext

Context parameter that will be passed unchanged to the ChangeCallback procedure.

ObjectSecurity

The security descriptor associated with the object. The descriptor is interpreted with respect to user accounts and permissions and the information is displayed in the dialog box.

NoReadPermission

Tell the user that they do not have a privilege required for viewing the object's auditing information.

ChangeContextStatus

The dialog ignores this value which it passes as a parameter to the change callback function. The change callback function can return a status code to the code that invoked the dialog box if a pointer to a status variable is passed for this parameter.

MustBeZero

Set to zero.

Returns

The function returns a non-zero value on failure. Failure is returned if the security context is invalid for example.

ACLDLGCONTROL

The ACLDLGCONTROL structure specifies the attributes of the SedDiscritionaryAclEditor and SedSystemAclEditor dialog boxes.

typedef struct {
    UCHAR Version;
    BOOLEAN IsContainer;
    BOOLEAN AllowNewObject;
    BOOLEAN MapSpecificToGeneric; 
    PDWORD GenericAccessMap; 
    PDWORD GenericMappingNewObjects; 
    PWCHAR DialogTitle;
    PACLHELPCONTROL HelpInfo;
    PWCHAR SubReplaceTitle;
    PWCHAR SubReplaceObjectsTitle;
    PWCHAR SubReplaceConfirmation;
    PWCHAR SpecialAccess;
    PWCHAR SpecialNewAccess; 
} ACLDLGCONTROL,       *PACLDLGCONTROL;

Members Version

Set to 1.

IsContainer

Indicates if object is a container.

AllowNewObject

Allow permissions to be applied to new (non-existent) objects.

MapSpecificToGeneric

Determines if generic mapping entry is used.

GenericAccessMap

Points to a GENERIC_MAPPING (defined in the Win32 SDK) structure that specifies a mapping of generic to specific and standard access types. The access map array used by Explorer is:

DWORD            AccessMasks[4] = {
            0x120089, 0x120116, 0x1200A0, 0x1F01FF
};

The access map array used by Regedt32 is:

DWORD            RegistryAccessMasks[4] = {
            0x120019, 0x20006, 0x20019, 0xF003F
}

GenericMappingNewObjects

Interpreted as specific access types for new objects. Pass the same GENERIC_MAPPING structure as for the GenericAccessMap parameter.

DialogTitle

Specifies the text that will be displayed in the title bar of the dialog box.

HelpInfo

Points to PACLHELPCONTROL structure that defines the help actions taken when the user presses the dialog box's Help button.

SubReplaceTitle

Specifies the text that is included next to the check box that allows a user to recursively replace security descriptors on children containers of the object that is being edited.

SubReplaceObjectsTitle

Specifies the text that is included next to the check box that allows a user to recursively replace security descriptors on children objects of the object that is being edited.

SubReplaceConfirmation

Species the text in the dialog box that is presented the user if they checked the check box that will result in a replacement of the security descriptors of all the children of the object being edited.

SpecialAccess

Specifies the text that is displayed for the entry in the pre-defined security settings drop down menu that the user can select to open a specific access editor dialog. Regedt32 and Explorer specify "Special Access..." for this string.

SpecialNewAccess

Specifies the text that is displayed for the entry in the pre-defined security settings drop down menu that the user can select to open a specific access editor dialog for new objects.

ACLEDITCONTROL

The ACLEDITCONTROL structure specifies security masks that the security editor dialog box uses when the user specifies that they want to edit specific security attributes for an object. They can do this by either selecting the "Special Access..." entry in the security settings drop-down list or by double clicking on an existing security entry in the dialog's main window.

typedef struct {
    DWORD           NumberOfEntries;
    PACLEDITENTRY   Entries;
    PWCHAR          DefaultPermissionName;
} ACLEDITCONTROL, *PACLEDITCONTROL;

Members

NumberOfEntries

Specifies the number of entries being passed.

Entries

Points to an array of ACLEDITENTRY structures. Each entry in the list will result in an additional check box in the specific access security editor dialog box. When the user selects the entry the corresponding access mask bits will be added to the resulting security descriptor entry.

DefaultPermissionName

The permission that should be selected by default in the combo box in the Add permission dialog.

ACLEDITENTRY

The ACLEDITENTRY structure specifies security masks that the security editor dialog box uses when the user specifies that they want to edit specific security attributes for an object.

typedef struct {
            DWORD            Type;
            DWORD            AccessMask;
            DWORD            AccessMask1; // optional
            PWCHAR          Name;
} ACLEDITENTRY,         *PACLEDITENTRY;

Members

Type

Specifies whether the entry is a generic access entry, a specific access entry or a combination.

AccessMask

If the user checks the box for this entry this access mask will be applied to the entry that the user is defining.

AccessMask1

Used for special access or ignored.

Name

Specifies the text label that will identify this access setting (e.g. "Read").

See the following pages for the definitions for these data structures used by Explorer and Regedt32.

Registry Editor Key Settings

ACLEDITENTRY aclEditEntryRegistry[] = {
            { 2, KEY_QUERY_VALUE,                 0, L"&Query Value" },
            { 2, KEY_SET_VALUE,                   0, L"&Set Value" },
            { 2, KEY_CREATE_SUB_KEY,              0, L"&Create Subkeys"},
            { 2, KEY_ENUMERATE_SUB_KEYS,          0, L"&Enumerate Subkeys" },
            { 2, KEY_NOTIFY,                      0, L"No&tify" },
            { 2, KEY_CREATE_LINK,                 0, L"Create &Link" },
            { 2, DELETE,                          0, L"&Delete" },
            { 2, WRITE_DAC,                       0, L"&Write DAC" },
            { 2, WRITE_OWNER,                     0, L"Write &Owner" },
            { 2, READ_CONTROL,                    0, L"&Read Control" },
            { 1, 0x2019,                          0, L"Read" },
            { 1, GENERIC_ALL,                     0, L"Full Control" },
};

Explorer Directory Settings

ACLEDITENTRY aclEditEntryDirectory[] = {
            { 2, GENERIC_READ,                    0, L"&Read (R)" },
            { 2, GENERIC_WRITE,                   0, L"&Write (W)" },
            { 2, GENERIC_EXECUTE,                 0, L"E&xecute (X)"},
            { 2, ACCESS_SYSTEM_SECURITY,          0, L"&View/Change Audits (A)" },
            { 2, DELETE,                          0, L"&Delete (D)" },
            { 2, WRITE_DAC,                       0, L"Change &Permissions (P)" },
            { 2, WRITE_OWNER,                     0, L"Take &Ownership (O)" },
            { 2, FILE_LIST_DIRECTORY,             0, L"&List (L)" },
            { 2, FILE_ADD_FILE,                   0, L"Add &Entry (N)" },
            { 2, READ_CONTROL,                    0, L"Read &Control (T)" },
            { 3, 0,                               0, L"No Access" },
            { 3, FILE_LIST_DIRECTORY|READ_CONTROL, (DWORD) -1, L"List" },
            { 3, GENERIC_READ|GENERIC_EXECUTE, 
                 GENERIC_READ|GENERIC_EXECUTE, L"Read" },
            { 3, GENERIC_WRITE|GENERIC_EXECUTE, (DWORD) -1, L"Add" },
            { 3, GENERIC_WRITE|GENERIC_READ|GENERIC_EXECUTE, 
                 GENERIC_READ|GENERIC_EXECUTE, L"Add Read" },
            { 3, GENERIC_WRITE|GENERIC_READ|GENERIC_EXECUTE|DELETE, 
                 GENERIC_WRITE|GENERIC_READ|
                 GENERIC_EXECUTE|DELETE, L"Change" },
            { 3, GENERIC_ALL, GENERIC_ALL, L"Full Control" },
            { 4, GENERIC_READ,                    0, L"Read" },
            { 4, GENERIC_WRITE,                   0, L"Write" },
            { 4, DELETE,                          0, L"Delete (D)"},
            { 4, WRITE_DAC,                       0, L"Change Permissions (P)" },
            { 4, WRITE_OWNER,                     0, L"Take Ownership (O)" },
};

Explorer File Settings

ACLEDITENTRY aclEditEntryFile[] = {
            { 2, GENERIC_READ,                    0, L"&Read (R)" },
            { 2, GENERIC_WRITE,                   0, L"&Write (W)" },
            { 2, GENERIC_EXECUTE,                 0, L"E&xecute (X)" },
            { 2, DELETE,                          0, L"&Delete (D)" },
            { 2, WRITE_DAC,                       0, L"Change &Permissions (P)" },
            { 2, WRITE_OWNER,                     0, L"Change &Owner (O)" },
            { 1, 0,                               0, L"No Access" },
            { 1, GENERIC_READ|GENERIC_EXECUTE,    0, L"Read" },
            { 1, GENERIC_READ|GENERIC_WRITE|GENERIC_EXECUTE,
                                                            0, L"Change" },
            { 1, GENERIC_ALL,                     0, L"Full Control" },
};

Explorer and Registry SACL Settings

The following is the entry used for the SedSystemAclEditor function:

ACLEDITENTRY saclEditEntry[] = {
    { 5, GENERIC_READ|ACCESS_SYSTEM_SECURITY, 0, L"&Read" },
    { 5, GENERIC_WRITE|ACCESS_SYSTEM_SECURITY, 0, L"&Write" },
    { 5, GENERIC_EXECUTE, 0, L"E&xecute"  },
    { 5, DELETE, 0, L"&Delete" },
    { 5, WRITE_DAC, 0, L"Change &Permissions" },
    { 5, WRITE_OWNER, 0, L"&Take Ownership" },
};

ACLHELPCONTROL

The ACLHELPCONTROL structure specifies the help item that will be displayed when a user presses the Help button in one of the security editor dialog boxes.

typedef struct {
    PWCHAR    HelpFile;
    DWORD     MainDialogTopic;
    DWORD     ACLEditorDialogTopic;
    DWORD     Reserved1;
    DWORD     AddEntryDialogTopic;
    DWORD     Reserved2;
    DWORD     Reserved3;
    DWORD     AccountDialogTopic;
} ACLHELPCONTROL, *PACLHELPCONTROL;

Members

HelpFile

Specifies the name of the help file that will be accessed (e.g. "Application.hlp".

Topic

Specifies the topic ID in the help file that will be displayed, if appropriate.

SubTopic

Specifies the subtopic ID if appropriate.

ACLCHANGE

An ACLCHANGE function is a callback function called by a security editor dialog box when the user indicates that they want to change a security descriptor. The function is invoked if the user presses the Okay button.

typedef DWORD CALLBACK (*ACLCHANGE )( 
    HWND Owner, 
    HANDLE Instance, 
    PVOID CallbackContext, 
    PSECURITY_DESCRIPTOR NewSD,
    PSECURITY_DESCRIPTOR NewObjectSD,
    BOOLEAN ApplyToSubContainers,
    BOOLEAN ApplyToSubObjects,
    PDWORD ChangeContextStatus
);

Parameters

Owner

Handle to dialog box owner window.

Instance

This is the instance handle of the application.

CallbackContext

The unchanged context parameter that was passed to the dialog function.

NewSD

The modified security descriptor. It is up to the callback function to apply this new security descriptor to the object if appropriate.

NewObjectSD

The security descriptor that should be applied to the new object if the dialog is for new object creation.

ApplyToSubContainers

Indicates that permissions should be applied to subcontainers.

ApplyToSubObjects

Indicates that permissions should be applied to subobjects.

ChangeContextStatus

A status that can be returned to the caller of the original dialog box function. The security editor dialog function does not look at this value.

Returns

The function should return a non-zero value to indicate failure


Back to Top