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