able/windows-nt
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
windows-nt/Source/XPSP1/NT/admin/netui/acledit/h/sedapi.hxx

599 lines
22 KiB
C++
Raw Normal View History

Add source files
2020-09-26 03:20:57 -05:00
/**********************************************************************/
/** 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_
Reference in a new issue Copy permalink