NAME

Win32::FileSecurity - Manage FileSecurity Discretionary Access Control Lists in Perl

SYNOPSIS

    use Win32::FileSecurity;

DESCRIPTION

This module offers control over the administration of system FileSecurity DACLs. You may want to use Get and EnumerateRights to get an idea of what mask values correspond to what rights as viewed from File Manager.

CONSTANTS

  DELETE, READ_CONTROL, WRITE_DAC, WRITE_OWNER,
  SYNCHRONIZE, STANDARD_RIGHTS_REQUIRED,
  STANDARD_RIGHTS_READ, STANDARD_RIGHTS_WRITE,
  STANDARD_RIGHTS_EXECUTE, STANDARD_RIGHTS_ALL,
  SPECIFIC_RIGHTS_ALL, ACCESS_SYSTEM_SECURITY,
  MAXIMUM_ALLOWED, GENERIC_READ, GENERIC_WRITE,
  GENERIC_EXECUTE, GENERIC_ALL, F, FULL, R, READ,
  C, CHANGE

FUNCTIONS

constant( $name, $set )

Stores the value of named constant $name into $set. Same as $set = Win32::FileSecurity::NAME_OF_CONSTANT();.

Get( $filename, \%permisshash )

Gets the DACLs of a file or directory.

Set( $filename, \%permisshash )

Sets the DACL for a file or directory.

EnumerateRights( $mask, \@rightslist )

Turns the bitmask in $mask into a list of strings in @rightslist.

MakeMask( qw( DELETE READ_CONTROL ) )

Takes a list of strings representing constants and returns a bitmasked integer value.

Note: All of the functions return false if they fail, unless otherwise noted. Errors returned via $! containing both Win32 GetLastError() and a text message indicating Win32 function that failed.

%permisshash

Entries take the form $permisshash{USERNAME} = $mask ;

Get() may return a SID or the string "<Unknown>" when the account name cannot be determined.

EXAMPLE1

    # Gets the rights for all files listed on the command line.
    use Win32::FileSecurity qw(Get EnumerateRights);

    foreach( @ARGV ) {
        next unless -e $_ ;
        if ( Get( $_, \%hash ) ) {
            while( ($name, $mask) = each %hash ) {
                print "$name:\n\t";
                EnumerateRights( $mask, \@happy ) ;
                print join( "\n\t", @happy ), "\n";
            }
        }
        else {
            print( "Error #", int( $! ), ": $!" ) ;
        }
    }

EXAMPLE2

    # Gets existing DACL and modifies Administrator rights
    use Win32::FileSecurity qw(MakeMask Get Set);

    # These masks show up as Full Control in File Manager
    $file = MakeMask( qw( FULL ) );

    $dir = MakeMask( qw(
        FULL
        GENERIC_ALL
    ) );

    foreach( @ARGV ) {
        s/\\$//;
        next unless -e;
        Get( $_, \%hash ) ;
        $hash{Administrator} = ( -d ) ? $dir : $file ;
        Set( $_, \%hash ) ;
    }

COMMON MASKS FROM CACLS AND WINFILE

READ

    MakeMask( qw( FULL ) ); # for files
    MakeMask( qw( READ GENERIC_READ GENERIC_EXECUTE ) ); # for directories

CHANGE

    MakeMask( qw( CHANGE ) ); # for files
    MakeMask( qw( CHANGE GENERIC_WRITE GENERIC_READ GENERIC_EXECUTE ) ); # for directories

ADD & READ

    MakeMask( qw( ADD GENERIC_READ GENERIC_EXECUTE ) ); # for directories only!

FULL

    MakeMask( qw( FULL ) ); # for files
    MakeMask( qw( FULL  GENERIC_ALL ) ); # for directories

LIMITATIONS

• The module currently only supports ALLOW ACLs; DENY ACLs are not being reported by Get() and cannot be Set() either.

• The Get() function may return an SID when the account cannot be found, but the Set() function doesn't allow the use of SIDs for setting ACLs.

KNOWN ISSUES / BUGS

• May not work on remote drives.

• Errors croak, don't return via $! as documented.

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Win32::FileSecurity

perl -MCPAN -e shell
install Win32::FileSecurity