13-Aug-1991
Generic Graphical Security Editor API
=====================================
This document describes the data structures and APIs for access to the
Generic Graphical Secuirty Editor (GGSED). These APIs will allow
a consistent way to edit access and audit permissions for NT ACLs on
any type of resource.
Most of the text is taken directly from the notes by JimK in a meeting
between JimK, JohnL and ChuckC when the initial design was proposed.
The GGSED API is a private API and will not be exposed for external use
(i.e., outside of MS). The APIs will be available on both Win16 and
Win32 in a dll called NTNET.DRV (this will also be the "winnet" driver for
Lanman).
Note: The UI for the Security Editor is still in the design process, thus
the APIs may change.
Please flag any areas of functionality that you need that are not provided
or if too much functionality is provided by sending mail to JohnL.
Executive Summary:
The client passes information that contains the following:
Strings for object specific titles
Flag indicating if the object is a container object or not
Localized names representing access masks
Callback function for applying the ACL
A context value which is passed back in the callback function
Security descriptor for object (this is manipulated by user)
The user will manipulate the permissions, when the user applies the
permissions, the callback that was passed will be called,
thus the client will receive the following information in the callback:
Context value the client passed in
Security descriptor containing the user modified DACL/SACL
Two flags indicating whether the security descriptor should be
applied to sub-containers and/or sub-objects. The callback
is responsible for traversing the objects etc. if
appropriate.
The client will then apply the security descriptor as appropriate
to the specified objects and return a status code indicating
whether all, some or none of the security descriptors were applied
successfully.
The same process is used whether the DACL is being editted, or the SACL
is being editted.
Note that due to the use of NT data structures under Win16, Large model
maybe a requirement (due to no FAR keywords in NT P* typedefs).
-----------------------------------------------------------------------
Major decisions:
1) Since this is no longer a FILE security editor, we must
ensure that the UI and API are applicable/tailorable to
any number of object types. The client applications and
object types we know about in the first release of NT
are:
File Browser (JohnL)
Directories (container)
Files (non-container)
Print Manager (DaveSn)
Print Queues (container)
Print Jobs (non-container)
Registry Browser (DaveGi & Jaimes)
keys (container)
2) The security editor must also support viewing/modifying
a default discretionary ACL (DACL). A DACL is comprised
entirely of generic and standard access types.
3) We want to support the concept of "Application Defined
Groupings" of access types into a name that makes sense
to a user of the particular application's object types.
For example, "Submit Print Jobs" might be an application
defined grouping of accesses that the print manager would
like to have displayed when security of print objects is
viewed.
4) In order for the user to have some way to relate what their
default DACL means when applied to an object type, displays
of security for an object type will also include displaying
generic and standard access types. For this reason, application
defined groupings may only include generic and standard access
types. Specific and other special access types will be ignored.
Since we need to support win16, the data structures are expressed in
standard windows types. Hungarian was omitted for clarity.
//
// This data type defines information related to a single class of object.
// For example, a FILE object, or PRINT_QUEUE object would have a structure
// like this defined.
//
typedef struct _SED_OBJECT_TYPE_DESCRIPTOR {
//
// Defines whether the object is a container or not.
// TRUE indicates the object may contain other objects.
//
BOOL IsContainer;
//
// A mask containing all valid access types for the object type.
// This mask may not contain any special access types (generic,
// MaximumAllowed, or AccessSystemSecurity).
//
ACCESS_MASK ValidAccessMask;
//
// The (localized) name of the object type.
// For example, "File" or "Print Job".
//
LPSTR ObjectTypeName;
//
// The (localized) title to display if protection can be displayed to
// sub-containers.
//
// This string will be presented with a checkbox before it.
// If checked when asked to apply the protection, the application will
// be called at it's callback entry point to apply the security to
// sub-containers.
//
// This field is ignored if the IsContainer field is FALSE.
//
// As an example of how this field is used, the file browser may
// specify the following string in the DIRECTORY object's
// descriptor:
//
// "Subdirectories"
//
LPSTR ApplyToSubContainerTitle;
//
// The (localized) title to display if protection can be displayed to
// sub-NONcontainers. For example, a FILE is a sub-NON-container of
// a DIRECTORY object.
//
// This string will be presented with a checkbox before it.
// If checked when asked to apply the protection, the application will
// be called at it's callback entry point to apply the security to
// sub-NONcontainers.
//
// This field is ignored if the IsContainer field is FALSE.
//
// As an example of how this field is used, the file browser may
// specify the following string in the DIRECTORY object's
// descriptor:
//
// "Files in Directory and Subdirectories"
//
LPSTR ApplyToSubObjectTitle;
//
// The (localized) title to display next to the check box that controls
// whether new subobjects created in this container object inherit the
// container object's permissions.
//
// This field is ignored if the IsContainer field is FALSE.
//
// For example, in the file browser, new files can inherit the directory
// permissions. The text in the file browser would be:
//
// "New Files Inherit Directory Permissions"
//
LPSTR NewObjInhContPerm;
//
// The generic mapping for the object type.
//
GENERIC_MAPPING GenericMapping;
//
// An array of 4 (localized) names. These names are the names of the
// generic access types, with entry N defining the name of the
// corresponding generic access type in the GenericMapping field.
//
// For example, for English this should contain:
//
// GenericName[0] = "Read"
// GenericName[1] = "Write"
// GenericName[2] = "Execute"
// GenericName[3] = "All"
//
LPSTR GenericNames[4];
//
// An array of 8 (localized) names. These names are the names of
// the standard access types. For English this should contain:
//
// StandardName[0] = "Delete"
// StandardName[1] = "Read Control"
// StandardName[2] = "Change Permissions"
// StandardName[3] = "Take Ownership"
// StandardName[4] = "Synchronize"
//
// If "Synchronize" is not supported by the object type, then it does
// not need to be passed and will not be referenced. This is indicated
// by the ValidAccessMask.
//
// Names 5, 6, and 7 are reserved for future use and should either be
// a NULL string or have no string passed at all.
LPSTR StandardNames[8];
} SED_OBJECT_TYPE_DESCRIPTOR, FAR * PSED_OBJECT_TYPE_DESCRIPTOR;
/*-------------------------------------------------------------------*/
//
// In some cases, it is desirable to display access names that are
// meaningful in the context of the type of object whose ACL
// is being worked on. For example, for a PRINT_QUEUE object type,
// it may be desirable to display an access type named "Submit Print Jobs".
// The following structures are used for defining these application defined
// access groupings.
//
typedef struct _SED_APPLICATION_ACCESS {
//
// An application defined access grouping consists of an access mask
// and a name by which that combination of access types is to be known.
// The access mask may only contain generic and standard access types.
// Specific access types and other Special access types are ignored.
//
ACCESS_MASK AccessMask;
LPSTR Name;
} SED_APPLICATION_ACCESS, FAR * PSED_APPLICATION_ACCESS;
typedef struct _SED_APPLICATION_ACCESSES {
//
// The count field indicates how many application defined access groupings
// are defined by this data structure. The AccessGroup[] array then
// contains that number of elements.
//
ULONG Count;
SED_APPLICATION_ACCESS AccessGroup[ANYSIZE_ARRAY];
}
/*-------------------------------------------------------------------*/
NTSTATUS
SedDiscretionaryAclEditor(
HWND hwndOwner,
SED_OBJECT_TYPE_DESCRIPTOR FAR * ObjectType,
SED_APPLICATION_ACCESSES FAR * ApplicationAccesses,
LPSTR ObjectName,
SED_APPLY_ACL_CALLBACK ApplySecurityCallbackRoutine,
DWORD CallbackContext,
SECURITY_DESCRIPTOR FAR * SecurityDescriptor,
BOOL CouldntReadDacl
)
/*++
Routine Description:
This routine invokes the graphical Discretionary ACL editor DLL. The
graphical DACL editor may be used to modify or create:
- A default Discretionary ACL
- A Discretionary ACL for a particular type of object.
- A Discretionary ACL for a particular named instance of an
object.
Additionally, in the case where the ACL is that of a named object
instance, and that object may contain other object instances, the
user will be presented with the opportunity to apply the protection
to the entire sub-tree of objects.
Parameters:
ObjectType - This optional parameter is used to specify information
about the type of object whose security is being edited. If the
security does not relate to an instance of an object (such as for
when default protection is being established), then NULL should be
passed.
ApplicationAccesses - This optional parameter may be used to specify
groupings of access types that are particularly useful when operating
on security for the specified object type. For example, it may be
useful to define an access type called "Submit Print Job" for a
PRINT_QUEUE class of object. This parameter is ignored if the
ObjectType parameter is not passed.
ObjectName - This optional parameter is used to pass the name of the
object whose security is being edited. If the security does not
relate to an instance of an object (such as for when default
protection is being established), then NULL should be passed.
This parameter is ignored if the ObjectType parameter is not passed.
ApplySecurityCallbackRoutine - This parameter is used to provide the
address of a routine to be called to apply security to either the
object specified, or, in the case that the object is a container,
to sub-containers or sub-non-containers of that object.
CallbackContext - This value is opaque to the DACL editor. Its only
purpose is so that a context value may be passed back to the
application via the ApplySecurityCallbackRoutine when that routine
is invoked. This may be used by the application to re-locate
context related to the edit session. For example, it may be a
handle to the object whose security is being edited.
SecurityDescriptor - This parameter points to a security descriptor
containing the current discretionary ACL of the object. This
security descriptor may, but does not have to, contain the owner
and group of that object as well. Note that the security descriptor's
DaclPresent flag may be FALSE, indicating either that the object
had no protection, or that the user couldn't read the protection.
CouldntReadDacl - This boolean flag may be used to indicate that the
user does not have read access to the target object's discretionary
acl. In this case, a warning
to the user will be presented along with the option to continue
or cancel.
Presumably the user does have write access to the DACL or
there is no point in activating the editor.
Return Status:
STATUS_MODIFIED - This (success) status code indicates the editor has
been exited and protection has successfully been modified.
STATUS_NOT_MODIFIED - This (success) status code indicates the editor
has been exited without attempting to modify the protection.
STATUS_NOT_ALL_MODIFIED - This (warning) status code indicates the user
requested the protection to be modified, but an attempt to do so
only partially succeeded. The user has been notified of this
situation.
STATUS_FAILED_TO_MODIFY - This (error) status code indicates the user
requested the protection to be modified, but an attempt to do so
has failed. The user has been notified of this situation.
--*/
/*-------------------------------------------------------------------*/
NTSTATUS
SedSystemAclEditor(
IN SED_OBJECT_TYPE_DESCRIPTOR FAR * ObjectType (OPTIONAL),
IN LPSTR ObjectName (OPTIONAL),
IN SED_APPLY_ACL_CALLBACK ApplySecurityCallbackRoutine,
IN ULONG CallbackContext,
IN SECURITY_DESCRIPTOR FAR * SecurityDescriptor,
IN BOOL CouldntReadSacl
)
/*++
Routine Description:
SedSystemAclEditor is nearly identical to SedDiscretionaryAclEditor
except for the following points:
1) Operations affect only the System ACL and not the Discretionary
ACL.
2) The generic and standard names in the SED_OBJECT_TYPE_DESCRIPTOR
now represent the attributes that can be auditted (which will
generally be the same as the permission strings). It is assumed
that each auditting string can be auditted for both success and
failure.
3) No application defined grouping is allowed since it doesn't
make sense for auditting, thus no ApplicationAccess parameter
is needed.
Parameters:
See SedSystemAclEditor for a description of each parameter.
--*/
/*-------------------------------------------------------------------*/
typedef
NTSTATUS (FAR *SED_APPLY_ACL_CALLBACK)(
IN ULONG CallbackContext,
IN SECURITY_DESCRIPTOR FAR * SecurityDescriptor,
BOOL ApplyToSubContainers,
BOOL ApplyToSubObjects
) ;
/*++
Routine Description:
This routine is provided by a caller of the graphical DACL editor.
It is called by the Graphical DACL editor to apply security to
target object(s) when requested by the user.
Parameters:
CallbackContext - This is the value passed as the CallbackContext argument
to the SedDiscretionaryAclEditor() api when the graphical editor
was invoked.
SecurityDescriptor - This parameter points to a security descriptor
containing a new discretionary ACL of either the object (and
optionally the object's sub-containers) or the object's sub-objects.
If the DaclPresent flag of this security descriptor is FALSE, then
security is to be removed from the target object(s).
ApplyToSubContainers - When TRUE, indicates that Dacl is to be applied to
sub-containers of the target object as well as the target object.
This will only be TRUE if the target object is a container object.
ApplyToSubObjects - When TRUE, indicates the Dacl is to be applied to
sub-objects of the target object, but not to the target object
itself or sub-containers of the object. This will only be TRUE if
the target object is a container object.
Return Status:
STATUS_MODIFIED - This (success) status code indicates the protection
has successfully been applied.
STATUS_NOT_ALL_MODIFIED - This (warning) status code indicates that
the protection could not be applied to all of the target objects.
STATUS_FAILED_TO_MODIFY - This (error) status code indicates the
protection could not be applied to any target objects.
--*/