windows-xp/Source/XPSP1/NT/admin/netui/shell/doc/ggsed.txt

								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.


--*/