windows-xp/Source/XPSP1/NT/admin/netui/acledit/h/sedapi.hxx

/**********************************************************************/
/**			  Microsoft LAN Manager 		     **/
/**		Copyright(c) Microsoft Corp., 1990, 1991	     **/
/**********************************************************************/

/*
    SEDAPI.hxx

    This File contains the prototypes and descriptions for the interface to
    the generic security editor dialogs for NT objects.

    FILE HISTORY:
	Johnl	02-Aug-1991	Created
	Johnl	27-Dec-1991	Updated to reflect reality
	JohnL	25-Feb-1992	Nuked NewObjValidMask (new obj use generic/stan.
				only, Added GENERIC_MAPPING param.

*/

#ifndef _SEDAPI_HXX_
#define _SEDAPI_HXX_

//
// The following are status codes indicating the state of the permissions on
// the resource we are setting permissions for.
//
#define SED_STATUS_MODIFIED		(1)
#define SED_STATUS_NOT_MODIFIED 	(2)
#define SED_STATUS_NOT_ALL_MODIFIED	(3)
#define SED_STATUS_FAILED_TO_MODIFY	(4)

//
// Current Security editor revision level.
//
#define SED_REVISION	    (1)

#define SED_REVISION1	    (1)

//
// 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
{
    //
    // The current revision level being used by the client.  This is for
    // support in case structure definitions change.  It should contain
    // the current revision supported.
    //
    UCHAR			Revision ;

    //
    // Defines whether the object is a container or not.
    // TRUE indicates the object may contain other objects.  Means the
    // user can Tree apply the permissions if desired.
    //
    BOOLEAN			IsContainer;

    //
    // Defines whether "New Object" permissions can be assigned (i.e.,
    // a "New Object" is an object that will be created in the future).
    //
    // This field is ignored when editting Auditting permissions
    //
    BOOLEAN			AllowNewObjectPerms ;

    //
    // A mask containing all valid access types for the object type.
    // Note that this mask is used to identify and create Deny All
    // ACEs.
    //
    ACCESS_MASK                 ValidAccessMask;

    //
    // The generic mapping for the object type.
    //
    // This is used for mapping the specific permissions to the generic
    // flags.
    //
    PGENERIC_MAPPING		GenericMapping ;

    //
    // The (localized) name of the object type.
    // For example, "File",  "Print Job" or "Directory".
    //
    LPTSTR			ObjectTypeName;

    //
    // The (localized) title to display if protection/auditting can be applied
    // to sub-objects/sub-containers.  This is essentially the Tree apply
    // option title.
    //
    // This string will be presented with a checkbox before it.
    // If this box is checked, then the callback entry point
    // will be called once if New objects are not supported.  The
    // ApplyToSubContainers will be set to TRUE and ApplyToSubObjects
    // will be set to FALSE.  If New objects are supported, then the
    // callback entry point will be called twice, once as just described,
    // and once with the ApplyToSubObjects set to TRUE and
    // ApplyToSubContainers set to FALSE.  In each case, the security
    // descriptor will contain ACLs appropriate for the type of object
    // as determined by the SED_APPLICATION_ACCESSES defined by the client.
    //
    // 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:
    //
    //		"Replace Permissions on Existing Files/Subdirectories"
    //
    LPTSTR	       ApplyToSubContainerTitle;

    //
    // The (localized) text to display below the ApplyToSubContainerTitle
    // checkbox.  This is simply explanatory text describing what will
    // happen if the user doesn't check the box.
    //
    // For directories, this text would be:
    //
    //		"If this box is not checked, these permissions will apply
    //		 only to the directory and newly created
    //		 files/subdirectories."
    //
    LPTSTR	       ApplyToSubContainerHelpText ;

    //
    // The (localized) title to display in the "Type of Access" combo
    // that brings up the Special access dialog.  This same title is
    // used for the title of this dialog except the "..." is stripped
    // from the end.
    //
    // This field is ignored if the System Acl editor was invoked.
    //
    // As an example of how this field is used, the file browser may
    // specify the following string in the DIRECTORY object's
    // descriptor:
    //
    //		"Special Directory Access..."
    //
    LPTSTR	       SpecialObjectAccessTitle ;

    //
    // The (localized) title to display in the "Type of Access" combo
    // that brings up the Special new object access dialog.  This same title
    // is used for the title of this dialog except the "..." is stripped
    // from the end.
    //
    // This item is required if AllowNewObjectPerms is TRUE, it is ignored
    // if AllowNewObjectPerms is FALSE or we are editting a SACL.
    //
    // As an example of how this field is used, the file browser may
    // specify the following string in the DIRECTORY object's
    // descriptor:
    //
    //		"Special New File Access..."
    //
    LPTSTR	       SpecialNewObjectAccessTitle ;

} SED_OBJECT_TYPE_DESCRIPTOR, *PSED_OBJECT_TYPE_DESCRIPTOR;


//
// 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.
//

//
// The following are the different permission description types that the user
// will manipulate for setting permissions.
//
// SED_DESC_TYPE_RESOURCE - The SED_APPLICATION_ACCESS structure is describing
//	an object or container permission that will be displayed in the main
//	permissions listbox.  These should be the permissions that the
//	user will use all the time and will generally be a conglomeration
//	of permissions (for example, "Edit" which would include Read, Write
//	and maybe delete).
//
// SED_DESC_TYPE_RESOURCE_SPECIAL - The structure is describing an object
//	or container permissions that will be displayed in the Special
//	access dialog.	These are generally primitive permissions (such as
//	Read, Write, Execute, Set Permissions etc.).  The permission names
//	will appear next to checkboxes, thus they should have the "&"
//	accelerator next to the appropriate letter.
//
// SED_DESC_TYPE_CONT_AND_NEW_OBJECT - The structure is describing a container
//	and new object permission that will be shown in the main permissions
//	listbox.  The Container permission is contained in AccessMask1 and
//	the New Object resource is in AccessMask2.  When the permission name
//	is selected by the user, the container access permissions *and* the
//	new object access permissions will be set to the corresponding access
//	mask.  This is useful when inherittance can be used to set the New
//	Object Access permissions.
//
// SED_DESC_TYPE_NEW_OBJECT_SPECIAL - The structure is describing a new object
//	permission that will be shown in the Special New Object access
//	dialog.  This is used the same way the SED_DESC_TYPE_RESOURCE_SPECIAL
//	type is used, that is, the permissions should be the primitive, per
//	bit permissions.  The permission names
//	will appear next to checkboxes, thus they should have the "&"
//	accelerator next to the appropriate letter.
//
// SED_DESC_TYPE_AUDIT - The structure is describing an Audit access mask.
//	AccessMask1 contains the audit mask to be associated with the
//	permission title string.  The title string will appear next to
//	a checkbox, thus they should have the "&" accelerator next to
//	the appropriate letter in the title string.
//
// Note that they cannot be freely intermixed, use the following table
// as a guide for which ones to use where:
//
//  IsContainer  AllowNewObjectPerms
//     False	      False	     RESOURCE, RESOURCE_SPECIAL
//     True	      False	     RESOURCE, RESOURCE_SPECIAL
//     True	      True	     RESOURCE_SPECIAL, CONT_AND_NEW_OBJECT,
//				     NEW_OBJECT_SPECIAL
//     True	      False	     SED_DESC_TYPE_AUDIT
//
//  Note that in the third case (IsContainer && AllowNewObjectPerms) you
//  *cannot* use the RESOURCE permission description type, you must always
//  associate the permission on the resource with new object permissions.
//  If this is a problem, we can look at removing this obstacle.
//
#define SED_DESC_TYPE_RESOURCE			(1)
#define SED_DESC_TYPE_RESOURCE_SPECIAL		(2)

#define SED_DESC_TYPE_CONT_AND_NEW_OBJECT	(3)
#define SED_DESC_TYPE_NEW_OBJECT_SPECIAL	(4)

#define SED_DESC_TYPE_AUDIT			(5)


//
// To describe the permissions to the ACL Editor, build an array consisting
// of SED_APPLICATION_ACCESS structures.  The use of each field is as follows:
//
// Type - Contains one of the SED_DESC_TYPE_* manifests, determines what the
//	rest of the fields in this structure mean.  Specifically, if Type
//	equals:
//
//				    AccessMask1   AccessMask2	PermissionTitle
//				   ============================================
//SED_DESC_TYPE_RESOURCE	       Perm	   Not Used    Name of this Perm
//SED_DESC_TYPE_RESOURCE_SPECIAL    Special Perm   Not Used    Name of this Perm
//SED_DESC_TYPE_CONT_AND_NEW_OBJECT    Perm	  Special Perm Name of this Perm
//SED_DESC_TYPE_NEW_OBJECT_SPECIAL  Special Perm   Not Used    Name of this Perm
//SED_DESC_TYPE_AUDIT		     Audit Mask    Not Used    Name of this Audit mask
//
// AccessMask1 - Access mask to be associated with the PermissionTitle string,
//	see the table under Type for what this field contains.
//
// AccessMask2 - Either used for Special permissions or ignored.
//
// PermissionTitle - Title string this permission set is being associated with.
typedef struct _SED_APPLICATION_ACCESS
{
    UINT			Type ;
    ACCESS_MASK 		AccessMask1 ;
    ACCESS_MASK 		AccessMask2 ;
    LPTSTR			PermissionTitle ;

} SED_APPLICATION_ACCESS, *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;
    PSED_APPLICATION_ACCESS	AccessGroup ;

} SED_APPLICATION_ACCESSES, *PSED_APPLICATION_ACCESSES ;

/*++

Routine Description:

    This routine is provided by a caller of the graphical ACL editor.

    It is called by the ACL editor to apply security/auditting info to
    target object(s) when requested by the user.

Parameters:


    CallbackContext - This is the value passed as the CallbackContext argument
	to the SedDiscretionaryAclEditor() or SedSystemAclEditor api when
	the graphical editor was invoked.

    SecDesc - This parameter points to a security descriptor
	that should be applied to this object/container and optionally
	sub-containers if the user selects the apply to tree option.

    SecDescNewObjects - This parameter is used only when operating on a
	resource that is a container and supports new objects (for
	example, directories).	If the user chooses the apply to tree option,
	then this security descriptor will have all of the "New Object"
	permission ACEs contained in the primary container and the inherit
	bits will be set appropriately.

    ApplyToSubContainers - When TRUE, indicates that Dacl/Sacl is to be applied
	to sub-containers of the target container as well as the target container.
        This will only be TRUE if the target object is a container object.

    ApplyToSubObjects - When TRUE, indicates the Dacl/Sacl is to be applied to
	sub-objects of the target object. This will only be TRUE if
	the target object is a container object and supports new objects.
	The SecDescNewObjects should be used for applying the permissions
	in this instance.

    StatusReturn - This status flag indicates what condition the
	resources permissions were left in after an error occurred.

	    SED_STATUS_MODIFIED - This (success) status code indicates the
		protection has successfully been modified.

	    SED_STATUS_NOT_ALL_MODIFIED - This (warning) status code
		indicates an attempt to modify the resource permissions
		has only partially succeeded.

	    SED_STATUS_FAILED_TO_MODIFY - This (error) status code indicates
		an attempt to modify the permissions has failed completely.

Return Status:

    The return code is a standard Win32 error code or Lan Manager Network
    error code if a failure occurred, 0 if successful.

--*/
typedef DWORD (*PSED_FUNC_APPLY_SEC_CALLBACK)(
				       ULONG_PTR   CallbackContext,
				       PSECURITY_DESCRIPTOR SecDesc,
				       PSECURITY_DESCRIPTOR SecDescNewObjects,
				       BOOLEAN	ApplyToSubContainers,
				       BOOLEAN	ApplyToSubObjects,
				       LPDWORD	StatusReturn
					     ) ;

/*++

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.

    If an error occurs, the user will be properly notified by the ACL
    editor.


Parameters:

    Owner - Handle of the owner window the security editor should use for
	dialog creation and error messages.  This will lock down the passed
	window.

    Server - The server name in the form "\\server" that the resource resides
	on.  This is used for adding users, groups and aliases to the
	DACL and SACL.	NULL indicates the local machine.

    ObjectType - This 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 parameter is used to specify
	groupings of access types 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.

    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.
	This security descriptor will not be modified by the ACL editor.

    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.

    SEDStatusReturn - This status flag indicates what condition the
	resources permissions were left in after the ACL editor was
	dismissed.  It may be one of:

	    SED_STATUS_MODIFIED - This (success) status code indicates the
		editor has been exited and protection has successfully been
		modified.

	    SED_STATUS_NOT_MODIFIED -  This (success) status code indicates
		the editor has been exited without attempting to modify the
		protection.

	    SED_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.

	    SED_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.

Return Code:

    A standard windows error return such as ERROR_NOT_ENOUGH_MEMORY.  This
    means the ACL editor was never displayed.  The user will be notified
    of the error before this procedure returns.

--*/

DWORD
SedDiscretionaryAclEditor(
	HWND			     Owner,
	LPTSTR			     Server,
	PSED_OBJECT_TYPE_DESCRIPTOR  ObjectType,
	PSED_APPLICATION_ACCESSES    ApplicationAccesses,
	LPTSTR			     ObjectName,
	PSED_FUNC_APPLY_SEC_CALLBACK ApplySecurityCallbackRoutine,
	ULONG_PTR			     CallbackContext,
	PSECURITY_DESCRIPTOR	     SecurityDescriptor,
	BOOLEAN 		     CouldntReadDacl,
	LPDWORD 		     SEDStatusReturn
	) ;

//
// The parameters for the SACL editor are exactly the same except where
// noted as that of the SedDiscretionaryAclEditor.
//

DWORD
SedSystemAclEditor(
	HWND			     Owner,
	LPTSTR			     Server,
	PSED_OBJECT_TYPE_DESCRIPTOR  ObjectType,
	PSED_APPLICATION_ACCESSES    ApplicationAccesses,
	LPTSTR			     ObjectName,
	PSED_FUNC_APPLY_SEC_CALLBACK ApplySecurityCallbackRoutine,
	ULONG_PTR			     CallbackContext,
	PSECURITY_DESCRIPTOR	     SecurityDescriptor,
	BOOLEAN 		     CouldntReadSacl,
	LPDWORD 		     SEDStatusReturn
	) ;

/*++

Routine Description:

    This routine invokes the take ownership dialog which is used
    to view and/or set the owner of a security descriptor.  The current owner
    is displayed along with an optional button for the currently logged
    on user to take ownership.

    If an error occurs, the user will be properly notified by the API.

Parameters:

    Owner - Handle of the owner window the security editor should use for
	dialog creation and error messages.  This will lock down the passed
	window.

    Server - The server name in the form "\\server" that the resource resides
	on.  This may eventually be used for setting the owner to
	external groups. NULL indicates the local machine.  This parameter
	is not currently used.

    ObjectTypeName - NT Resource type of object the user wants to look
	at the owner of.
	Examples for this parameter would be "File", "Directory"
	or "Files/Directories".

    ObjectName - This parameter is used to pass the name of the
	object whose security is being edited.	This might be
	"C:\status.doc" or some other qualified name.

    CountOfObjects - The number of objects the user wants to change permissions
	on.  If this number is greater then one, then the ObjectName is
	ignored and a message of the form "%d ObjectTypeName Selected".

    ApplySecurityCallbackRoutine - This parameter is used to provide the
	address of a routine to be called to apply the new security
	descriptor.  The flags in the PSED_FUNC_APPLY_SEC_CALLBACK
	type are not used.

    CallbackContext - This value is opaque to this API.  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 owner.  May be NULL if CountOfObjects is
	greater then one because the Current Owner field is not displayed
	if CountOfObjects is greater then one.

    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 owner or
	there is no point in activating the editor.

    SEDStatusReturn - This status flag indicates what condition the
	resources security descriptor were left in after the take ownership
	dialog was dismissed.  It may be one of:

	    SED_STATUS_MODIFIED - This (success) status code indicates the
		dialog has been exited and the new owner has successfully been
		modified.

	    SED_STATUS_NOT_MODIFIED -  This (success) status code indicates
		the dialog has been exited without attempting to modify the
		owner.

	    SED_STATUS_NOT_ALL_MODIFIED - This (warning) status code indicates
		the user requested the owner to be modified, but an attempt
		to do so only partially succeeded.  The user has been notified
		of this situation.

	    SED_STATUS_FAILED_TO_MODIFY - This (error) status code indicates
		the user requested the owner to be modified, but an
		attempt to do so has failed.  The user has been notified of
		this situation.

Return Code:

    A standard windows error return such as ERROR_NOT_ENOUGH_MEMORY.  This
    means the dialog was never displayed.  The user will be notified
    of the error before this procedure returns.

--*/

DWORD
SedTakeOwnership(
	HWND			     Owner,
	LPTSTR			     Server,
	LPTSTR			     ObjectTypeName,
	LPTSTR			     ObjectName,
	UINT			     CountOfObjects,
	PSED_FUNC_APPLY_SEC_CALLBACK ApplySecurityCallbackRoutine,
	ULONG_PTR			     CallbackContext,
	PSECURITY_DESCRIPTOR	     SecurityDescriptor,
	BOOLEAN 		     CouldntReadOwner,
	LPDWORD 		     SEDStatusReturn
	) ;


#endif //_SEDAPI_HXX_