This is a live mirror of the Perl 5 development currently hosted at
Re: Inline PI function
[perl5.git] / pod / perlsec.pod
1=head1 NAME
3perlsec - Perl security
425e5e39 7Perl is designed to make it easy to program securely even when running
8with extra privileges, like setuid or setgid programs. Unlike most
9command-line shells, which are based on multiple substitution passes on
10each line of the script, Perl uses a more conventional evaluation scheme
11with fewer hidden snags. Additionally, because the language has more
12built-in functionality, it can rely less upon external (and possibly
13untrustworthy) programs to accomplish its purposes.
a0d0e21e 14
425e5e39 15Perl automatically enables a set of special security checks, called I<taint
16mode>, when it detects its program running with differing real and effective
17user or group IDs. The setuid bit in Unix permissions is mode 04000, the
18setgid bit mode 02000; either or both may be set. You can also enable taint
5f05dabc 19mode explicitly by using the B<-T> command line flag. This flag is
425e5e39 20I<strongly> suggested for server programs and any program run on behalf of
21someone else, such as a CGI script.
a0d0e21e 22
1e422769 23While in this mode, Perl takes special precautions called I<taint
24checks> to prevent both obvious and subtle traps. Some of these checks
25are reasonably simple, such as verifying that path directories aren't
26writable by others; careful programmers have always used checks like
27these. Other checks, however, are best supported by the language itself,
425e5e39 28and it is these checks especially that contribute to making a setuid Perl
29program more secure than the corresponding C program.
31You may not use data derived from outside your program to affect something
32else outside your program--at least, not by accident. All command-line
33arguments, environment variables, locale information (see L<perllocale>),
34and file input are marked as "tainted". Tainted data may not be used
35directly or indirectly in any command that invokes a sub-shell, nor in any
36command that modifies files, directories, or processes. Any variable set
37within an expression that has previously referenced a tainted value itself
38becomes tainted, even if it is logically impossible for the tainted value
39to influence the variable. Because taintedness is associated with each
40scalar value, some elements of an array can be tainted and others not.
a0d0e21e 41
42For example:
425e5e39 44 $arg = shift; # $arg is tainted
45 $hid = $arg, 'bar'; # $hid is also tainted
46 $line = <>; # Tainted
8ebc5c01 47 $line = <STDIN>; # Also tainted
48 open FOO, "/home/me/bar" or die $!;
49 $line = <FOO>; # Still tainted
a0d0e21e 50 $path = $ENV{'PATH'}; # Tainted, but see below
425e5e39 51 $data = 'abc'; # Not tainted
a0d0e21e 52
425e5e39 53 system "echo $arg"; # Insecure
54 system "/bin/echo", $arg; # Secure (doesn't use sh)
55 system "echo $hid"; # Insecure
56 system "echo $data"; # Insecure until PATH set
a0d0e21e 57
425e5e39 58 $path = $ENV{'PATH'}; # $path now tainted
a0d0e21e 59
425e5e39 60 $ENV{'PATH'} = '/bin:/usr/bin';
61 $ENV{'IFS'} = '' if $ENV{'IFS'} ne '';
a0d0e21e 62
425e5e39 63 $path = $ENV{'PATH'}; # $path now NOT tainted
64 system "echo $data"; # Is secure now!
a0d0e21e 65
425e5e39 66 open(FOO, "< $arg"); # OK - read-only file
67 open(FOO, "> $arg"); # Not OK - trying to write
a0d0e21e 68
425e5e39 69 open(FOO,"echo $arg|"); # Not OK, but...
70 open(FOO,"-|")
71 or exec 'echo', $arg; # OK
a0d0e21e 72
425e5e39 73 $shout = `echo $arg`; # Insecure, $shout now tainted
a0d0e21e 74
425e5e39 75 unlink $data, $arg; # Insecure
76 umask $arg; # Insecure
a0d0e21e 77
425e5e39 78 exec "echo $arg"; # Insecure
79 exec "echo", $arg; # Secure (doesn't use the shell)
80 exec "sh", '-c', $arg; # Considered secure, alas!
82If you try to do something insecure, you will get a fatal error saying
83something like "Insecure dependency" or "Insecure PATH". Note that you
425e5e39 84can still write an insecure B<system> or B<exec>, but only by explicitly
85doing something like the last example above.
87=head2 Laundering and Detecting Tainted Data
89To test whether a variable contains tainted data, and whose use would thus
90trigger an "Insecure dependency" message, you can use the following
91I<is_tainted()> function.
93 sub is_tainted {
94 return ! eval {
95 join('',@_), kill 0;
96 1;
97 };
98 }
100This function makes use of the fact that the presence of tainted data
101anywhere within an expression renders the entire expression tainted. It
102would be inefficient for every operator to test every argument for
103taintedness. Instead, the slightly more efficient and conservative
104approach is used that if any tainted value has been accessed within the
105same expression, the whole expression is considered tainted.
5f05dabc 107But testing for taintedness gets you only so far. Sometimes you have just
425e5e39 108to clear your data's taintedness. The only way to bypass the tainting
5f05dabc 109mechanism is by referencing sub-patterns from a regular expression match.
425e5e39 110Perl presumes that if you reference a substring using $1, $2, etc., that
111you knew what you were doing when you wrote the pattern. That means using
112a bit of thought--don't just blindly untaint anything, or you defeat the
113entire mechanism. It's better to verify that the variable has only good
114characters (for certain values of "good") rather than checking whether it
115has any bad characters. That's because it's far too easy to miss bad
116characters that you never thought of.
425e5e39 117
118Here's a test to make sure that the data contains nothing but "word"
119characters (alphabetics, numerics, and underscores), a hyphen, an at sign,
120or a dot.
122 if ($data =~ /^([-\@\w.]+)$/) {
123 $data = $1; # $data now untainted
124 } else {
125 die "Bad data in $data"; # log this somewhere
126 }
5f05dabc 128This is fairly secure because C</\w+/> doesn't normally match shell
425e5e39 129metacharacters, nor are dot, dash, or at going to mean something special
130to the shell. Use of C</.+/> would have been insecure in theory because
131it lets everything through, but Perl doesn't check for that. The lesson
132is that when untainting, you must be exceedingly careful with your patterns.
133Laundering data using regular expression is the I<ONLY> mechanism for
134untainting dirty data, unless you use the strategy detailed below to fork
135a child of lesser privilege.
137The example does not untaint $data if C<use locale> is in effect,
138because the characters matched by C<\w> are determined by the locale.
139Perl considers that locale definitions are untrustworthy because they
140contain data from outside the program. If you are writing a
141locale-aware program, and want to launder data with a regular expression
142containing C<\w>, put C<no locale> ahead of the expression in the same
143block. See L<perllocale/SECURITY> for further discussion and examples.
145=head2 Switches On the "#!" Line
147When you make a script executable, in order to make it usable as a
148command, the system will pass switches to perl from the script's #!
149line. Perl checks that any command-line switches given to a setuid
150(or setgid) script actually match the ones set on the #! line. Some
151UNIX and UNIX-like environments impose a one-switch limit on the #!
152line, so you may need to use something like C<-wU> instead of C<-w -U>
153under such systems. (This issue should arise only in UNIX or
154UNIX-like environments that support #! and setuid or setgid scripts.)
425e5e39 156=head2 Cleaning Up Your Path
1fef88e7 158For "Insecure C<$ENV{PATH}>" messages, you need to set C<$ENV{'PATH'}> to a
1e422769 159known value, and each directory in the path must be non-writable by others
160than its owner and group. You may be surprised to get this message even
161if the pathname to your executable is fully qualified. This is I<not>
162generated because you didn't supply a full path to the program; instead,
163it's generated because you never set your PATH environment variable, or
164you didn't set it to something that was safe. Because Perl can't
165guarantee that the executable in question isn't itself going to turn
166around and execute some other program that is dependent on your PATH, it
167makes sure you set the PATH.
169It's also possible to get into trouble with other operations that don't
170care whether they use tainted values. Make judicious use of the file
171tests in dealing with any user-supplied filenames. When possible, do
172opens and such after setting C<$E<gt> = $E<lt>>. (Remember group IDs,
425e5e39 173too!) Perl doesn't prevent you from opening tainted filenames for reading,
174so be careful what you print out. The tainting mechanism is intended to
175prevent stupid mistakes, not to remove the need for thought.
425e5e39 177Perl does not call the shell to expand wild cards when you pass B<system>
178and B<exec> explicit parameter lists instead of strings with possible shell
179wildcards in them. Unfortunately, the B<open>, B<glob>, and
5f05dabc 180back-tick functions provide no such alternate calling convention, so more
425e5e39 181subterfuge will be required.
183Perl provides a reasonably safe way to open a file or pipe from a setuid
184or setgid program: just create a child process with reduced privilege who
185does the dirty work for you. First, fork a child using the special
186B<open> syntax that connects the parent and child by a pipe. Now the
187child resets its ID set and any other per-process attributes, like
188environment variables, umasks, current working directories, back to the
189originals or known safe values. Then the child process, which no longer
190has any special permissions, does the B<open> or other system call.
191Finally, the child passes the data it managed to access back to the
5f05dabc 192parent. Because the file or pipe was opened in the child while running
425e5e39 193under less privilege than the parent, it's not apt to be tricked into
194doing something it shouldn't.
5f05dabc 196Here's a way to do back-ticks reasonably safely. Notice how the B<exec> is
425e5e39 197not called with a string that the shell could expand. This is by far the
198best way to call something that might be subjected to shell escapes: just
199never call the shell at all. By the time we get to the B<exec>, tainting
200is turned off, however, so be careful what you call and what you pass it.
cb1a09d0 201
425e5e39 202 use English;
203 die unless defined $pid = open(KID, "-|");
204 if ($pid) { # parent
205 while (<KID>) {
206 # do something
425e5e39 207 }
208 close KID;
209 } else {
425e5e39 210 $EUID = $UID;
211 $EGID = $GID; # XXX: initgroups() not called
212 $ENV{PATH} = "/bin:/usr/bin";
213 exec 'myprog', 'arg1', 'arg2';
214 die "can't exec myprog: $!";
215 }
217A similar strategy would work for wildcard expansion via C<glob>.
219Taint checking is most useful when although you trust yourself not to have
220written a program to give away the farm, you don't necessarily trust those
221who end up using it not to try to trick it into doing something bad. This
222is the kind of security checking that's useful for setuid programs and
223programs launched on someone else's behalf, like CGI programs.
225This is quite different, however, from not even trusting the writer of the
226code not to try to do something evil. That's the kind of trust needed
227when someone hands you a program you've never seen before and says, "Here,
228run this." For that kind of safety, check out the Safe module,
229included standard in the Perl distribution. This module allows the
230programmer to set up special compartments in which all system operations
231are trapped and namespace access is carefully controlled.
233=head2 Security Bugs
235Beyond the obvious problems that stem from giving special privileges to
236systems as flexible as scripts, on many versions of Unix, setuid scripts
237are inherently insecure right from the start. The problem is a race
238condition in the kernel. Between the time the kernel opens the file to
239see which interpreter to run and when the (now-setuid) interpreter turns
240around and reopens the file to interpret it, the file in question may have
241changed, especially if you have symbolic links on your system.
243Fortunately, sometimes this kernel "feature" can be disabled.
244Unfortunately, there are two ways to disable it. The system can simply
245outlaw scripts with the setuid bit set, which doesn't help much.
246Alternately, it can simply ignore the setuid bit on scripts. If the
247latter is true, Perl can emulate the setuid and setgid mechanism when it
248notices the otherwise useless setuid/gid bits on Perl scripts. It does
249this via a special executable called B<suidperl> that is automatically
250invoked for you if it's needed.
252However, if the kernel setuid script feature isn't disabled, Perl will
253complain loudly that your setuid script is insecure. You'll need to
254either disable the kernel setuid script feature, or put a C wrapper around
255the script. A C wrapper is just a compiled program that does nothing
256except call your Perl program. Compiled programs are not subject to the
257kernel bug that plagues setuid scripts. Here's a simple wrapper, written
258in C:
260 #define REAL_PATH "/path/to/script"
261 main(ac, av)
262 char **av;
263 {
264 execv(REAL_PATH, av);
265 }
425e5e39 267Compile this wrapper into a binary executable and then make I<it> rather
268than your script setuid or setgid.
270See the program B<wrapsuid> in the F<eg> directory of your Perl
271distribution for a convenient way to do this automatically for all your
272setuid Perl programs. It moves setuid scripts into files with the same
273name plus a leading dot, and then compiles a wrapper like the one above
274for each of them.
276In recent years, vendors have begun to supply systems free of this
277inherent security bug. On such systems, when the kernel passes the name
278of the setuid script to open to the interpreter, rather than using a
279pathname subject to meddling, it instead passes I</dev/fd/3>. This is a
280special file already opened on the script, so that there can be no race
281condition for evil scripts to exploit. On these systems, Perl should be
282compiled with C<-DSETUID_SCRIPTS_ARE_SECURE_NOW>. The B<Configure>
283program that builds Perl tries to figure this out for itself, so you
284should never have to specify this yourself. Most modern releases of
285SysVr4 and BSD 4.4 use this approach to avoid the kernel race condition.
287Prior to release 5.003 of Perl, a bug in the code of B<suidperl> could
288introduce a security hole in systems compiled with strict POSIX