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;
PACLHELPCONTROLHelpInfo;
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