NAME

Win32::Security::NamedObject - Security manipulation for named objects

SYNOPSIS

use Win32::Security::NamedObject;

my $noFoo = Win32::Security::NamedObject->('FILE', "C:\\Foo\\foo.txt");
my $dacl = $noFoo->dacl();
print Data::Dumper->Dump([$dacl->aces()]);

DESCRIPTION

This module provide an object-oriented interface for manipulating security information on named objects (i.e. files, registry keys, etc.). Note that, like the rest of Win32::Security, it currently only provides support for files. It has been architected to eventually support all object types supported by the GetNamedSecurityInfo Win32 API call. Also, it currently only supports access to the DACL and Owner information - SACL access will come later.

Installation instructions

This installs with MakeMaker as part of Win32::Security.

To install via MakeMaker, it's the usual procedure - download from CPAN, extract, type "perl Makefile.PL", "nmake" then "nmake install". Don't do an "nmake test" because the I haven't written a test suite yet.

It depends upon the other Win32::Security modules. The suite of Win32::Security modules depends upon:

Class::Prototyped 0.98 or later

Support for prototype-based programming in Perl. Win32::Security::ACE uses this to programmatically generate large number of classes that use multiple-inheritance. Win32::Security::ACL and Win32::Security::NamedObject use this to support programmatic generation of classes that interact with the Win32::Security::ACE classes. Win32::Security::Recursor uses this to allow for flexible behavior modification (since Win32::Security::Recursor objects are really behavioral, not stateful).

Data::BitMask 0.12 or later

Flexible support for manipulating masks and constants.

Win32::API

Support for making Win32 API calls from Perl. There is no C code anywhere in Win32::Security. Win32::API is why.

All of the above modules should be available on CPAN, and also via PPM.

Win32::Security MODULES

Win32::Security::SID

Win32::Security::SID provides a set of functions for doing SID manipulation (binary to text and vice-versa) as well as wrappers around Win32::LookupAccountName and Win32::LookupAccountSID that make them friendlier.

Win32::Security::Raw

Win32::Security::Raw provides a number of function wrappers around a number of Win32 API calls. Each wrapper wraps around a single Win32 API call and provides rudimentary data structure marshalling and parsing. This is the only module that uses Win32::API to make API calls - all of the other modules make their API calls through the wrappers provided by this module.

Win32::Security::ACE

Win32::Security::ACE provides an object-oriented interface for parsing, creating, and manipulating Access Control Entries (ACEs).

Win32::Security::ACL

Win32::Security::ACE provides an object-oriented interface for manipulating Access Control Lists (ACLs).

Win32::Security::NamedObject

Win32::Security::NamedObject provides support for accessing and modifying the security information attached to Named Objects.

Win32::Security::Recursor

Win32::Security::Recursor provides support for recursing through trees of Named Objects and inspecting and/or modifying the security settings for those objects.

Win32::Security SCRIPTS

Provided for your amusement and use are a few scripts that make use of the above modules. These scripts were the raison d'etre for the modules, and so it seemed justifiable to ship them with it. The scripts were located in the lib\\Win32\\Security directory so that they will be automatically installed as part of the package when deployed via PPM. The scripts have documentation, but here is a quick overview of them so that you don't overlook them.

PermDump.pl

This utility dumps permissions on files. It supports distinguishing between inherited and explicit permissions along with determining when there are problems with inherited permissions. It has a number of options, and it's designed to output in either TDF or CSV format for easy parsing and viewing.

I would personally strongly recommend that all system administrators set up a nightly task to dump all the permissions on server volumes to a text file. This makes it easy to recover should you make a mistake while doing permissions manipulation, and it also gives you a searchable file for looking for permissions without waiting for the script to dump permissions. While the script is very fast and generally scans several hundred files per second, if you have a volume with hundreds of thousands of files, it can still take a while to run.

PermFix.pl

This utility is designed to do one simple task: fix problems with inherited permissions. This utility will be released shortly - I still need to do more testing. Contact me directly for a pre-release version if you want it.

PermChg.pl

This utility is the counterpart to PermDump.pl. It allows you to change the permissions. Unlike X?CACLS.EXE, this utility properly understands and interacts with inherited permissions. It supports two modes for specifying permissions. The first allows you to specify permissions using the command line much like X?CACLS.EXE. The second allows you to pass the permissions in a text file using the same format as is outputted by PermDump.pl.

Say you get a call from an executive insisting that Jane be given access to everything that John has access to. The first step is to make Jane a member of all of the groups that John is in, but that doesn't address explicitly assigned permissions. To deal with that, dump all the permissions on the volume using PermDump.pl. Open the file up in Excel and sort on the Trustee. Copy the lines for John into another spreadsheet and replace the Trustee name with Jane's. Then pass that into PermChg.pl with the grant option and you're done!

This utility will be released shortly - I still need to do more development and testing. Contact me directly for a pre-release version if you want it.

ARCHITECTURE

Win32::Security::NamedObject uses the same class architecture as Win32::Security::ACL. Unlike Win32::Security::ACE and Win32::Security::ACL, it doesn't use the flyweight design pattern. (For obvious reasons - you're unlikely to create multiple Win32::Security::NamedObject objects for the same thing!)

Method Reference

new This creates a new Win32::Security::NamedObject object.

The various calling forms are:

• Win32::Security::NamedObject->new($objectType, $objectName)

• "Win32::Security::NamedObject::$objectType"->new($objectName)

Note that when using $objectType in the package name, the value needs to be canonicalized (i.e. SE_FILE_OBJECT, not the shortcut FILE). If the $objectType has already been canonicalized, improved performance can be realized by making the call on the fully-qualified package name and thus avoiding the call to redo the canonicalization. Aliases are permitted when $objectName is passed as a parameter.

The currently permitted objectName formats (text copied from http://msdn.microsoft.com/library/default.asp?url=/library/en-us/security/security/se_object_type.asp ) are:

SE_FILE_OBJECT

Indicates a file or directory. The name string that identifies a file or directory object can be:

• A relative path, such as "abc.dat" or "..\\abc.dat"

• An absolute path, such as "\\abc.dat", "c:\\dir1\\abc.dat", or "g:\\remote_dir\\abc.dat"

• A UNC name, such as "\\\\computer_name\\share_name\\abc.dat"

• A local file system root, such as "\\\\\\\\.\\\\c:". Security set on a file system root does not persist when the system is restarted

SE_REGISTRY_KEY

Indicates a registry key. A registry key object can be in the local registry, such as "CLASSES_ROOT\\some_path"; or in a remote registry, such as "\\\\computer_name\\CLASSES_ROOT\\some_path". The names of registry keys must use the following literal strings to identify the predefined registry keys: "CLASSES_ROOT", "CURRENT_USER", "MACHINE", and "USERS".

In addition, the following literal strings will be mapped to the legal literals:

• HKEY_CLASSES_ROOT -> CLASSES_ROOT

• HKEY_CURRENT_USER -> CURRENT_USER

• HKEY_LOCAL_MACHINE -> MACHINE

• HKEY_USERS -> USERS

dbmObjectType

Returns the Data::BitMask object for interacting with Object Types

See Win32::Security::ACE-dbmObjectType()> for more explanation.

objectType

Returns the type of object to which the ACE is or should be attached.

objectName

Returns the name of the object.

dacl

Gets or sets the DACL for the object. If no parameters are passed, it reads the DACL for the object and returns a Win32::Security::ACL class object. To set the DACL, pass the desired Win32::Security::ACL for the object and an optional SECURITY_INFORMATION mask for specifying the bits UNPROTECTED_DACL_SECURITY_INFORMATION or PROTECTED_DACL_SECURITY_INFORMATION. If the UNPROTECTED_DACL_SECURITY_INFORMATION is set, then permissions are inherited. If PROTECTED_DACL_SECURITY_INFORMATION is set, then permissions are NOT inherited (i.e. inheritance is blocked). If neither is set, then the existing setting is maintained.

Be forewarned that when setting the DACL, under Windows 2000 and more recent OSes, the call to SetNamedSecurityInfo results in the automatic propagation of inheritable ACEs to existing child object (see http://msdn.microsoft.com/library/default.asp?url=/library/en-us/security/security/setnamedsecurityinfo.asp for more information). This does not happen under Windows NT, and if you need propagation of inheritable permissions under Windows NT, you need to write your own code to implement that. Under OSes that support automatic propagation, the call to set a DACL can take a very long time to return! Finally, any errors in the inherited DACLs buried in the tree will be automatically fixed by this call.

When setting the DACL under Windows 2000 and more recent OSes, if UNPROTECTED_DACL_SECURITY_INFORMATION is specified, or if the SECURITY_INFORMATION mask is unspecified and the object is currently inheriting permissions, then any ACEs in the passed DACL that have the INHERITED_ACE bit set in aceFlags are automatically ignored. The OS will automatically propagate the inheritable ACEs and will only explicitly set those ACEs in the passed DACL that do not have the INHERITED_ACE bit set in aceFlags.

If PROTECTED_DACL_SECURITY_INFORMATION is specified, or if the SECURITY_INFORMATION mask is unspeciied and the object is currently blocking inherited permissions, than the INHERITED_ACE bit in aceFlags for all ACEs in the passed DACL is automatically cleared. That is to say, all passed ACEs are treated as explicit, independent of the INHERITED_ACE bit in aceFlags.

ownerTrustee

Gets or sets the Trustee for the Owner of the object. If no parameters are passed, it reads the Owner for the object and returns a Trustee name. To set the Owner, pass the desired Trustee. It calls ownerSid, so see that method for information on SeRestorePrivilege.

ownerSid

Gets or sets the binary SID for the Owner of the object. If no parameters are passed, it reads the Owner for the object and returns a binary SID. To set the Owner, pass the desired binary SID. The first time this is called in set mode, it will attempt to enable the SeRestorePrivilege, which permits setting the Owner of an object to anyone.

control

Returns the Data::BitMask::break_mask form of the Security Descript Control (i.e. a hash containing all matching constants for the control mask of the SD).

fixDacl

Fixes the inherited ACEs in the DACL. See the caveats concerning setting DACLS using dacl for further information.

AUTHOR

Toby Ovod-Everett, tovod-everett@alascom.att.com

cpanm Win32::Security::SID

perl -MCPAN -e shell
install Win32::Security::SID