summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Win32/FileSecurity.pm
blob: 6c6e586533606d03ca73d36066284d154c78b7ce (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
package Win32::FileSecurity;

#
# FileSecurity.pm
# By Monte Mitzelfelt, monte@conchas.nm.org
# Larry Wall's Artistic License applies to all related Perl
#  and C code for this module
# Thanks to the guys at ActiveWare!
# ver 0.67 ALPHA 1997.07.07
#

require Exporter;
require DynaLoader;
use Carp ;

$VERSION = '1.04';

require Win32 unless defined &Win32::IsWinNT;
croak "The Win32::FileSecurity module works only on Windows NT" unless Win32::IsWinNT();

@ISA= qw( Exporter DynaLoader );

require Exporter ;
require DynaLoader ;

@ISA = qw(Exporter DynaLoader) ;
@EXPORT_OK = qw(
	Get
	Set
	EnumerateRights
	MakeMask
	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
	A
	ADD
	       ) ;

sub AUTOLOAD {
    local($constname);
    ($constname = $AUTOLOAD) =~ s/.*:://;
    #reset $! to zero to reset any current errors.
    local $! = 0;
    $val = constant($constname);
    if($! != 0) {
	if($! =~ /Invalid/) {
	    $AutoLoader::AUTOLOAD = $AUTOLOAD;
	    goto &AutoLoader::AUTOLOAD;
	}
	else {
	    ($pack,$file,$line) = caller;
	    die "Your vendor has not defined Win32::FileSecurity macro "
	       ."$constname, used in $file at line $line.";
	}
    }
    eval "sub $AUTOLOAD { $val }";
    goto &$AUTOLOAD;
}

bootstrap Win32::FileSecurity;

1;

__END__

=head1 NAME

Win32::FileSecurity - manage FileSecurity Discretionary Access Control Lists in perl

=head1 SYNOPSIS

	use Win32::FileSecurity;

=head1 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.

=head1 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

=head1 FUNCTIONS

=head2 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.

=over 10

=item constant( $name, $set )

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

=item Get( $filename, \%permisshash )

Gets the DACLs of a file or directory.

=item Set( $filename, \%permisshash )

Sets the DACL for a file or directory.

=item EnumerateRights( $mask, \@rightslist )

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

=item MakeMask( qw( DELETE READ_CONTROL ) )

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

=back

=head2 %permisshash

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

=head1 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( $! ), ": $!" ) ;
	}
    }

=head1 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 ) ;
    }

=head1 COMMON MASKS FROM CACLS AND WINFILE

=head2 READ

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

=head2 CHANGE

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

=head2 ADD & READ

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

=head2 FULL

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

=head1 RESOURCES

From Microsoft: check_sd
	http://premium.microsoft.com/download/msdn/samples/2760.exe

(thanks to Guert Schimmel at Sybase for turning me on to this one)

=head1 VERSION

1.03 ALPHA	97-12-14

=head1 REVISION NOTES

=over 10

=item 1.03 ALPHA 1998.01.11

Imported diffs from 0.67 (parent) version

=item 1.02 ALPHA 1997.12.14

Pod fixes, @EXPORT list additions <gsar@activestate.com>

Fix unitialized vars on unknown ACLs <jmk@exc.bybyte.de>

=item 1.01 ALPHA 1997.04.25

CORE Win32 version imported from 0.66 <gsar@activestate.com>

=item 0.67 ALPHA 1997.07.07

Kludged bug in mapping bits to separate ACE's.  Notably, this screwed
up CHANGE access by leaving out a delete bit in the
C<INHERIT_ONLY_ACE | OBJECT_INHERIT_ACE> Access Control Entry.

May need to rethink...

=item 0.66 ALPHA 1997.03.13

Fixed bug in memory allocation check

=item 0.65 ALPHA 1997.02.25

Tested with 5.003 build 303

Added ISA exporter, and @EXPORT_OK

Added F, FULL, R, READ, C, CHANGE as composite pre-built mask names.

Added server\ to keys returned in hash from Get

Made constants and MakeMask case insensitive (I don't know why I did that)

Fixed mask comparison in ListDacl and Enumerate Rights from simple & mask
to exact bit match ! ( ( x & y ) ^ x ) makes sure all bits in x
are set in y

Fixed some "wild" pointers

=item 0.60 ALPHA 1996.07.31

Now suitable for file and directory permissions

Included ListDacl.exe in bundle for debugging

Added "intuitive" inheritance for directories, basically functions like FM
triggered by presence of GENERIC_ rights this may need to change

see EXAMPLE2

Changed from AddAccessAllowedAce to AddAce for control over inheritance

=item 0.51 ALPHA 1996.07.20

Fixed memory allocation bug

=item 0.50 ALPHA 1996.07.29

Base functionality

Using AddAccessAllowedAce

Suitable for file permissions

=back

=head1 KNOWN ISSUES / BUGS

=over 10

=item 1

May not work on remote drives.

=item 2

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

=cut