wntAccessMod

Modifies the Discretionary Access Control List [DACL] inheritance flags. The DACL is what is commonly referred to as the "permissions" on an object.

Syntax:

wntAccessMod(server-name, resource, object-type, request, flags)

Parameters:

(s) server-name Name of a network file server or empty string ("") to indicate the current machine.

(s) resource-name Identifies the object to be modified.

(i) object-type Identifies the type of the 'resource/share-name' object. See below.

(i) request Identifies the particular action that is being requested to be performed on the specified object type. See below.

(i) flags Controls behavior of the function. See below.

Returns:

(i) 1 [@TRUE] or 0 [@FALSE]. See below.

Server-Name

All attempts to work with permissions or auditing settings on remote computers will require that those remote computers have the "Server" service running.

Object-Type

Object-type	Resource-name description
300	Directory or file in a NTFS partition. This can be either a UNC folder/file specification [e.g. "\\server-name\share-name\some-folder\some-file"], or it can be a reference to a folder/file on a drive letter. If the referenced folder/file is on a drive letter that is mapped to a remote server, or it is a UNC specification for a folder/file on a remote server, then the "server-name" parameter's value must specify the name of the remote server [with a pair of leading backslash "\\" characters].
400	Registry key. This should be the handle of an open registry key (opened with the RegOpenKey() function), or a predefined registry handle. (Registration Functions are listed in the WIL help file under "Registration Database Operations".)
500	Window station Use extreme caution when altering the security of a window station or desktop object. Improperly manipulating the security of a window station or desktop object may result in making your system unusable and may require a hard-reset of the system in order to regain access to the system console [e.g. the keyboard, mouse and monitor]
501	Desktop Use extreme caution when altering the security of a window station or desktop object. Improperly manipulating the security of a window station or desktop object may result in making your system unusable and may require a hard-reset of the system in order to regain access to the system console [e.g. the keyboard, mouse and monitor]
600	Service Display Name Manipulates the security settings on NT services.
601	Service Key Name Manipulates the security settings on NT services.

Request

The different request #'s that can be passed in cause different types of actions to be performed on the specified object. The valid request #'s are listed here. Also, please note that some of the flag bits have different meanings depending on which particular request # has been specified.

Request #

Meaning

For WinNT, remove all explicit ACEs from all child objects [e.g subfolders & files or subkeys] and then re-propagate all inheritable access ACEs from the specified folder or key to all child objects under the specified folder or key. In effect, this resets the security on a tree of folders & files or subkeys and makes it consistent with the DACL settings of the parent folder at the root of that branch of the folder hierarchy on a volume or branch of the registry.

For Win2K, re-enable DACL inheritance on all child objects, remove all explicitly assigned access ACEs on all child objects then re-propagate all inheritable access ACEs to all child objects.

There are no request-specific flag bits for request #1.

For Win2K only, disable DACL inheritance on the specified object. All child objects will have their DACLs updated as necessary to reflect the possible changes in their parent object's DACL with respect to inheritable ACE changes.

Flag bit value

Flag bit meaning

When clear/disabled all inherited ACEs in the DACL to be retained & converted into explicitly assigned ACEs in the DACL when ACL inheritance is being disabled.

When set/enabled, all inherited ACEs in the DACL of the specified object will be removed from the DACL when ACL inheritance is being disabled.

WARNING: When using Request #2 with flag set/enabled, signifying that inherited ACEs are to be deleted from the DACL, be sure to first use wntAccessAdd() to explicitly grant administrative on the specified folder or file.

Failing to do so will result in cutting off all access to the specified folder, which in turn will cause wntAccessMod() to be unable to properly propagate any changes in inherited ACEs throughout the DACLs of all child subfolders & files beneath the folder which just had its ACL inheritance disabled.

The function wntAccessMod() will no longer return error 575 [Function failed] when this happens; instead, it will simply return a value of zero [0] to indicate that ACL inheritance was successfully disabled on the specified folder but it was unable to perform ACL inheritance propagation to the folder's children. A follow-up call to wntAccessAdd() can re-grant adminsitrative access to the specified folder and also has the side-effect of re-propagating inheritable ACEs to the child objects of the specified folder.

The same caveat applies when using Request #2 with flag bit #0 clear/disabled. Disabling ACL inheritance and converting inherited ACEs into explicitly assigned ACEs is less hazardous but can still cause problems if wntAccessDel() is used indiscriminantly afterwards. Improper use of wntAccessDel() after wntAccessMod() [Request #2, Flags =0] can also result in cutting off all access to the specified folder. Again, be sure to use wntAccessAdd(), if necessary, to insure that continuity is maintained in administrative access to the specified folder.

For Win2K only, re-enable DACL inheritance on the specified object. All child objects will have their DACLs updated as necessary to reflect the possible changes in their parent object's DACL w/respect to inheritable ACE changes.

Flag bit value

Flag bit meaning

When clear/disabled, all explicitly assigned ACEs in the DACL of the specified object will be kept when ACL inheritance is being re-enabled.

When set/enabled, all explicitly assigned ACEs in the DACL of the specified object will be removed when ACL inheritance is being re-enabled.

Please note that Request #3 cannot be used with the root folder of a network drive letter that is connected to a share that does not share out the root of a physical drive letter. The reason for this is that it is impossible to get the DACL from the specified folder's parent in order to determine if the specified folder should inherit any inheritable ACEs from the parent folder's DACL. This same problem will occur if a UNC specification is passed in and the UNC spec only contains the server and share information [e.g. no subfolder information] and the share does not share the root of a physical disk drive on the server. Attempting to re-enable the ACL inheritance for the DACL of a folder whose parent folder cannot be accessed will result in an error being generated. For example, we have a workstation computer named WS1 and server named SRV1. Server SRV1 has a local drive named D: and there is a user share named JOHN_DOE that shares out the directory D:\HOME\JOHN_DOE. If the user "johndoe" logs in on WS1 and connects the drive letter H: to the share \\SRV1\JOHN_DOE and then tries to use wntAccessMod() with request #3 and passes in "H:\" as the value for "resource" then the function will return an error. The reason for this is that it is impossible for wntAccessMod() [being executed in a script on WS1] to get the DACL of the folder "D:\HOME" on SRV1. If the DACL of "D:\HOME" on SRV1 is not obtainable then wntAccessMod() cannot determine if there any ACEs in the DACL of "D:\HOME" on SRV1 that are inheritable by "D:\HOME\JOHN_DOE" and thus need to be propagated to the DACL of "D:\HOME\JOHN_DOE". This same problem would occur if the value of "resource" had been specified as "\\SRV1\JOHN_DOE" [as opposed to something like "H:\FOLDER1" or "\\SRV1\JOHN_DOE\FOLDER1", both of which would be OK because the parent of "FOLDER1" could be accessed to find inheritable ACEs to add to the DACL of "FOLDER1"].

Flags

The flags value is an integer bit mask value. The values of different flag bits may be bit-wise OR'd together if multiple flag bits are to be "set" [e.g. enabled] at the same time. The following flag bits are valid:

Please note that these flag bits have the same meaning for all of the request #'s. Other flag bits may vary based on the particular request # that has been specified and those flag bits are documented under each specific request #.

Flag bit value when set/enabled	Flag bit meaning
32	Display a progress dialog box while manipulating access records.
64	Force a 1 second delay between updates to the progress dialog box. Note: this flag slows down the processing to be able to see what was going on in the progress dialog
128	If folders or files are being handled [e.g. object type 300, 301, 302 or 303], then display long names instead of short 8.3 names.

Return Value

The return value of wntAccessMod() will be 1 [@TRUE] if it successfully processes all of the resources that were specified.

Certain object types, namely folders & files and registry keys, can have recursive processing performed to add or remove an ACE to/from the DACL of multiple objects, such as when an entire subdirectory tree is processed or when a branch of the registry is processed. Also, on Win2K, ACL inheritance may cause recursive processing to happen even though only a single folder or registry key has had its DACL modified. If recursive processing is done and one or more child objects cannot have their DACLs properly accessed/modified, then wntAccessMod() will return a value of 0 [@FALSE]. The wntLastErrMsg() function should be called with an error code of "-1" specified to get the list of objects that could not be properly processed.

Please note that it is possible for wntAccessMod() to return a zero value and not cause the script to abort with an error. The only time that wntAccessMod() will raise an error that needs to be trapped with the use of ErrorMode(@OFF) is when the specific resource/share-name that has been specified cannot have its DACL modified properly. Any other errors that occur during recursive processing of child objects simply result in wntAccessMod() returning a zero value [@FALSE]. It is the programmer's responsibility to check the return value of wntAccessMod() and then execute any error handling code should a zero value be returned.

Note: It is not possible for WinNT v3.51/v4.0 to properly manage the permissions on a remote Win2K [or newer] systems. Attempting to use the wnt[Access|Audit]*() functions on WinNT v3.51/v4.0 to view/modify the permissions on a remote Win2K [or newer] system will result in error 716 [Win2K or newer required] being raised.

Example:

; Load Appropriate Extender
AddExtender('wwwnt34i.dll',0,'wwwnt64i.dll')


; This example simply does a reset of the security on a subfolders and
; files within/underneath a specified folder on a NTFS volume.
;
ErrorMode(@OFF)
Result = wntAccessMod("","C:\SOMEFOLDER",300,1,0)
RC = LastError()
ErrorMode(@CANCEL)
Message("wntAccessMod()",StrCat("Result = ",Result,"; LastError() = ",RC))
Exit

wntAccessMod

Syntax:

Parameters:

Returns:

Example:

See Also: