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/securit
    y/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/sec
        urity/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

