home *** CD-ROM | disk | FTP | other *** search
/ Total Network Tools 2002 / NextStepPublishing-TotalNetworkTools2002-Win95.iso / Archive / Web Server / Savant.exe / disk1 / data1.cab / Perl5 / perl5 / lib / Win32 / filesecurity.pm < prev    next >
Encoding:
Perl POD Document  |  2001-02-23  |  6.6 KB  |  251 lines
  1. package Win32::FileSecurity;
  2.  
  3. #
  4. # FileSecurity.pm
  5. # By Monte Mitzelfelt, monte@conchas.nm.org
  6. # Larry Wall's Artistic License applies to all related Perl
  7. #  and C code for this module
  8. # Thanks to the guys at ActiveWare!
  9. # ver 0.67 ALPHA 1997.07.07
  10. #
  11.  
  12. require Exporter;
  13. require DynaLoader;
  14. use Carp ;
  15.  
  16. croak "The Win32::FileSecurity module works only on Windows NT" if (!Win32::IsWinNT()) ;
  17.  
  18. @ISA= qw( Exporter DynaLoader );
  19. # Items to export into callers namespace by default. Note: do not export
  20. # names by default without a very good reason. Use EXPORT_OK instead.
  21. # Do not simply export all your public functions/methods/constants.
  22.  
  23. require Exporter ;
  24. require DynaLoader ;
  25.  
  26. @ISA = qw(Exporter DynaLoader) ;
  27. @EXPORT_OK = qw( Get Set EnumerateRights MakeMask ) ;
  28.  
  29. sub AUTOLOAD
  30. {
  31.     # This AUTOLOAD is used to 'autoload' constants from the constant()
  32.     # XS function.  If a constant is not found then control is passed
  33.     # to the AUTOLOAD in AutoLoader.
  34.  
  35.     local($constname);
  36.     ($constname = $AUTOLOAD) =~ s/.*:://;
  37.     #reset $! to zero to reset any current errors.
  38.     $!=0;
  39.     $val = constant($constname, @_ ? $_[0] : 0);
  40.     if($! != 0)
  41.     {
  42.         if($! =~ /Invalid/)
  43.         {
  44.             $AutoLoader::AUTOLOAD = $AUTOLOAD;
  45.             goto &AutoLoader::AUTOLOAD;
  46.         }
  47.         else
  48.         {
  49.             ($pack,$file,$line) = caller;
  50.             die "Your vendor has not defined Win32::FileSecurity macro $constname, used in $file at line $line.";
  51.         }
  52.     }
  53.     eval "sub $AUTOLOAD { $val }";
  54.     goto &$AUTOLOAD;
  55. }
  56.  
  57. bootstrap Win32::FileSecurity;
  58.  
  59. # Preloaded methods go here.
  60.  
  61. # Autoload methods go after __END__, and are processed by the autosplit program.
  62.  
  63. 1;
  64.  
  65. __END__
  66.  
  67. =head1 NAME
  68.  
  69. Win32::FileSecurity - manage FileSecurity Discretionary Access Control Lists in perl
  70.  
  71. =head1 SYNOPSIS
  72.  
  73.     use Win32::FileSecurity;
  74.  
  75. =head1 DESCRIPTION
  76.  
  77. This module offers control over the administration of system FileSecurity DACLs.  
  78. You may want to use Get and EnumerateRights to get an idea of what mask values
  79. correspond to what rights as viewed from File Manager.
  80.  
  81. =head1 CONSTANTS
  82.  
  83.   DELETE, READ_CONTROL, WRITE_DAC, WRITE_OWNER,
  84.   SYNCHRONIZE, STANDARD_RIGHTS_REQUIRED, 
  85.   STANDARD_RIGHTS_READ, STANDARD_RIGHTS_WRITE,
  86.   STANDARD_RIGHTS_EXECUTE, STANDARD_RIGHTS_ALL,
  87.   SPECIFIC_RIGHTS_ALL, ACCESS_SYSTEM_SECURITY, 
  88.   MAXIMUM_ALLOWED, GENERIC_READ, GENERIC_WRITE,
  89.   GENERIC_EXECUTE, GENERIC_ALL, F, FULL, R, READ,
  90.   C, CHANGE, A, ADD
  91.  
  92. =head1 FUNCTIONS
  93.  
  94. =head2 NOTE:
  95.  
  96. All of the functions return FALSE (0) if they fail, unless otherwise noted.  Errors returned
  97. via $! containing both Win32 GetLastError() and a text message indicating Win32 function that 
  98. failed.
  99.  
  100. =over 10
  101.  
  102. =item constant( $name, $set )
  103.     Stores the value of named constant $name into $set.
  104.     Alternatively, $set = Win32::FileSecurity::NAME_OF_CONSTANT() ;
  105.  
  106. =item Get( $filename, \%permisshash )
  107.     Gets the DACLs of a file or directory
  108.  
  109. =item Set( $filename, \%permisshash )
  110.     Sets the DACL for a file or directory
  111.  
  112. =item EnumerateRights( $mask, \@rightslist )
  113.     Turns the bitmask in $mask into a list of strings in @rightslist
  114.  
  115. =item MakeMask( qw( DELETE READ_CONTROL ) )
  116.     Takes a list of strings representing constants and returns a bitmasked integer value.
  117.  
  118. =back
  119.  
  120. =head2 %permisshash
  121.  
  122. Entries take the form $permisshash{USERNAME} = $mask ;
  123.  
  124. =head1 EXAMPLE1
  125.  
  126. # Gets the rights for all files listed on the command line.
  127. use Win32::FileSecurity ;
  128.  
  129. foreach( @ARGV ) {
  130.     next unless -e $_ ;
  131.     
  132.     if ( Win32::FileSecurity::Get( $_, \%hash ) ) {
  133.         while( ($name, $mask) = each %hash ) {
  134.             print "$name:\n\t"; 
  135.             Win32::FileSecurity::EnumerateRights( $mask, \@happy ) ;
  136.             print join( "\n\t", @happy ), "\n";
  137.         }
  138.     } else {
  139.         print( "Error #", int( $! ), ": $!" ) ;
  140.     }
  141. }
  142.  
  143. =head1 EXAMPLE2
  144.  
  145. # Gets existing DACL and modifies Administrator rights
  146. use Win32::FileSecurity ;
  147.  
  148. # These masks show up as Full Control in File Manager
  149. $file = Win32::FileSecurity::MakeMask( qw( FULL ) );
  150.  
  151. $dir = Win32::FileSecurity::MakeMask( qw(
  152.     FULL
  153.     GENERIC_ALL
  154. ) );
  155.  
  156.  
  157. foreach( @ARGV ) {
  158.     s/\\$//;
  159.     next unless -e;
  160.     
  161.     Win32::FileSecurity::Get( $_, \%hash ) ;
  162.     $hash{Administrator} = ( -d ) ? $dir : $file ;
  163.     Win32::FileSecurity::Set( $_, \%hash ) ;
  164. }
  165.  
  166. =head1 COMMON MASKS FROM CACLS AND WINFILE
  167.  
  168. =head2 READ
  169.  
  170.     Win32::FileSecurity::MakeMask( qw( FULL ) ); # for files
  171.     Win32::FileSecurity::MakeMask( qw( READ GENERIC_READ GENERIC_EXECUTE ) ); # for directories
  172.  
  173. =head2 CHANGE
  174.  
  175.     Win32::FileSecurity::MakeMask( qw( CHANGE ) ); # for files
  176.     Win32::FileSecurity::MakeMask( qw( CHANGE GENERIC_WRITE GENERIC_READ GENERIC_EXECUTE ) ); # for directories
  177.  
  178. =head2 ADD & READ
  179.  
  180.     Win32::FileSecurity::MakeMask( qw( ADD GENERIC_READ GENERIC_EXECUTE ) ); # for directories only!
  181.  
  182. =head2 FULL
  183.  
  184.     Win32::FileSecurity::MakeMask( qw( FULL ) ); # for files
  185.     Win32::FileSecurity::MakeMask( qw( FULL  GENERIC_ALL ) ); # for directories
  186.  
  187. =head1 RESOURCES
  188.  
  189. From Microsoft: check_sd
  190.     http://premium.microsoft.com/download/msdn/samples/2760.exe
  191.  
  192. (thanks to Guert Schimmel at Sybase for turning me on to this one)
  193.  
  194. =head1 VERSION
  195.  
  196. 0.67 ALPHA 1997.07.07
  197.  
  198. =head1 REVISION NOTES
  199.  
  200. =over 10
  201.  
  202. =item 0.67 ALPHA 1997.07.07
  203.     Kludged bug in mapping bits to separate ACE's
  204.     Notably, this screwed up CHANGE access by leaving
  205.     out a delete bit in the INHERIT_ONLY_ACE |
  206.     OBJECT_INHERIT_ACE Access Control Entry.
  207.     May need to rethink...
  208.  
  209. =item 0.66 ALPHA 1997.03.13
  210.     Fixed bug in memory allocation check
  211.  
  212. =item 0.65 ALPHA 1997.02.25
  213.     Tested with 5.003 build 303
  214.     Added ISA exporter, and @EXPORT_OK
  215.     Added F, FULL, R, READ, C, CHANGE as composite pre-built mask names.
  216.     Added server\ to keys returned in hash from Get
  217.     Made constants and MakeMask case insensitive (I don't know why I did that)
  218.     Fixed mask comparison in ListDacl and Enumerate Rights from simple & mask
  219.         to exact bit match ! ( ( x & y ) ^ x ) makes sure all bits in x
  220.         are set in y
  221.     Fixed some "wild" pointers
  222.  
  223. =item 0.60 ALPHA 1996.07.31
  224.     Now suitable for file and directory permissions
  225.     Included ListDacl.exe in bundle for debugging
  226.     Added "intuitive" inheritance for directories, basically functions like FM
  227.         triggered by presence of GENERIC_ rights this may need to change
  228.         see EXAMPLE2
  229.     Changed from AddAccessAllowedAce to AddAce for control over inheritance
  230.     
  231. =item 0.51 ALPHA 1996.07.20
  232.     Fixed memory allocation bug
  233.  
  234. =item 0.50 ALPHA 1996.07.29
  235.     Base functionality
  236.     Using AddAccessAllowedAce
  237.     Suitable for file permissions
  238. =back
  239.  
  240. =head1 KNOWN ISSUES / BUGS
  241.  
  242. =over 10
  243.  
  244. =item 1
  245.     May not work on remote drives.
  246.  
  247. =item 2
  248.     Errors croak, don't return via $! as documented.
  249.  
  250. =cut
  251.