This is a live mirror of the Perl 5 development currently hosted at
Missing 'require' in auto-generated .pm by h2xs
[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
54310121 9command line shells, which are based on multiple substitution passes on
425e5e39 10each line of the script, Perl uses a more conventional evaluation scheme
11with fewer hidden snags. Additionally, because the language has more
54310121 12builtin functionality, it can rely less upon external (and possibly
425e5e39 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
54310121 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
54310121 60 $ENV{'PATH'} = '/bin:/usr/bin';
c90c0ff4 61 delete @ENV{'IFS', 'CDPATH', 'ENV', 'BASH_ENV'};
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!
a0d0e21e 81
7bac28a0 82 @files = <*.c>; # Always insecure (uses csh)
83 @files = glob('*.c'); # Always insecure (uses csh)
85If you try to do something insecure, you will get a fatal error saying
86something like "Insecure dependency" or "Insecure PATH". Note that you
425e5e39 87can still write an insecure B<system> or B<exec>, but only by explicitly
54310121 88doing something like the last example above.
425e5e39 89
90=head2 Laundering and Detecting Tainted Data
92To test whether a variable contains tainted data, and whose use would thus
93trigger an "Insecure dependency" message, you can use the following
94I<is_tainted()> function.
96 sub is_tainted {
54310121 97 return ! eval {
98 join('',@_), kill 0;
99 1;
425e5e39 100 };
101 }
103This function makes use of the fact that the presence of tainted data
104anywhere within an expression renders the entire expression tainted. It
105would be inefficient for every operator to test every argument for
106taintedness. Instead, the slightly more efficient and conservative
107approach is used that if any tainted value has been accessed within the
108same expression, the whole expression is considered tainted.
5f05dabc 110But testing for taintedness gets you only so far. Sometimes you have just
425e5e39 111to clear your data's taintedness. The only way to bypass the tainting
54310121 112mechanism is by referencing subpatterns from a regular expression match.
425e5e39 113Perl presumes that if you reference a substring using $1, $2, etc., that
114you knew what you were doing when you wrote the pattern. That means using
115a bit of thought--don't just blindly untaint anything, or you defeat the
116entire mechanism. It's better to verify that the variable has only good
117characters (for certain values of "good") rather than checking whether it
118has any bad characters. That's because it's far too easy to miss bad
119characters that you never thought of.
425e5e39 120
121Here's a test to make sure that the data contains nothing but "word"
122characters (alphabetics, numerics, and underscores), a hyphen, an at sign,
123or a dot.
54310121 125 if ($data =~ /^([-\@\w.]+)$/) {
425e5e39 126 $data = $1; # $data now untainted
127 } else {
128 die "Bad data in $data"; # log this somewhere
129 }
5f05dabc 131This is fairly secure because C</\w+/> doesn't normally match shell
425e5e39 132metacharacters, nor are dot, dash, or at going to mean something special
133to the shell. Use of C</.+/> would have been insecure in theory because
134it lets everything through, but Perl doesn't check for that. The lesson
135is that when untainting, you must be exceedingly careful with your patterns.
136Laundering data using regular expression is the I<ONLY> mechanism for
137untainting dirty data, unless you use the strategy detailed below to fork
138a child of lesser privilege.
140The example does not untaint $data if C<use locale> is in effect,
141because the characters matched by C<\w> are determined by the locale.
142Perl considers that locale definitions are untrustworthy because they
143contain data from outside the program. If you are writing a
144locale-aware program, and want to launder data with a regular expression
145containing C<\w>, put C<no locale> ahead of the expression in the same
146block. See L<perllocale/SECURITY> for further discussion and examples.
148=head2 Switches On the "#!" Line
150When you make a script executable, in order to make it usable as a
151command, the system will pass switches to perl from the script's #!
54310121 152line. Perl checks that any command line switches given to a setuid
3a52c276 153(or setgid) script actually match the ones set on the #! line. Some
54310121 154Unix and Unix-like environments impose a one-switch limit on the #!
3a52c276 155line, so you may need to use something like C<-wU> instead of C<-w -U>
54310121 156under such systems. (This issue should arise only in Unix or
157Unix-like environments that support #! and setuid or setgid scripts.)
3a52c276 158
425e5e39 159=head2 Cleaning Up Your Path
1fef88e7 161For "Insecure C<$ENV{PATH}>" messages, you need to set C<$ENV{'PATH'}> to a
1e422769 162known value, and each directory in the path must be non-writable by others
163than its owner and group. You may be surprised to get this message even
164if the pathname to your executable is fully qualified. This is I<not>
165generated because you didn't supply a full path to the program; instead,
166it's generated because you never set your PATH environment variable, or
167you didn't set it to something that was safe. Because Perl can't
168guarantee that the executable in question isn't itself going to turn
169around and execute some other program that is dependent on your PATH, it
54310121 170makes sure you set the PATH.
172It's also possible to get into trouble with other operations that don't
173care whether they use tainted values. Make judicious use of the file
174tests in dealing with any user-supplied filenames. When possible, do
175opens and such after setting C<$E<gt> = $E<lt>>. (Remember group IDs,
425e5e39 176too!) Perl doesn't prevent you from opening tainted filenames for reading,
177so be careful what you print out. The tainting mechanism is intended to
178prevent stupid mistakes, not to remove the need for thought.
425e5e39 180Perl does not call the shell to expand wild cards when you pass B<system>
181and B<exec> explicit parameter lists instead of strings with possible shell
182wildcards in them. Unfortunately, the B<open>, B<glob>, and
54310121 183backtick functions provide no such alternate calling convention, so more
184subterfuge will be required.
425e5e39 185
186Perl provides a reasonably safe way to open a file or pipe from a setuid
187or setgid program: just create a child process with reduced privilege who
188does the dirty work for you. First, fork a child using the special
189B<open> syntax that connects the parent and child by a pipe. Now the
190child resets its ID set and any other per-process attributes, like
191environment variables, umasks, current working directories, back to the
192originals or known safe values. Then the child process, which no longer
193has any special permissions, does the B<open> or other system call.
194Finally, the child passes the data it managed to access back to the
5f05dabc 195parent. Because the file or pipe was opened in the child while running
425e5e39 196under less privilege than the parent, it's not apt to be tricked into
197doing something it shouldn't.
54310121 199Here's a way to do backticks reasonably safely. Notice how the B<exec> is
425e5e39 200not called with a string that the shell could expand. This is by far the
201best way to call something that might be subjected to shell escapes: just
202never call the shell at all. By the time we get to the B<exec>, tainting
203is turned off, however, so be careful what you call and what you pass it.
cb1a09d0 204
54310121 205 use English;
206 die unless defined $pid = open(KID, "-|");
207 if ($pid) { # parent
208 while (<KID>) {
209 # do something
425e5e39 210 }
211 close KID;
212 } else {
425e5e39 213 $EUID = $UID;
214 $EGID = $GID; # XXX: initgroups() not called
215 $ENV{PATH} = "/bin:/usr/bin";
216 exec 'myprog', 'arg1', 'arg2';
217 die "can't exec myprog: $!";
218 }
220A similar strategy would work for wildcard expansion via C<glob>.
222Taint checking is most useful when although you trust yourself not to have
223written a program to give away the farm, you don't necessarily trust those
224who end up using it not to try to trick it into doing something bad. This
225is the kind of security checking that's useful for setuid programs and
226programs launched on someone else's behalf, like CGI programs.
228This is quite different, however, from not even trusting the writer of the
229code not to try to do something evil. That's the kind of trust needed
230when someone hands you a program you've never seen before and says, "Here,
231run this." For that kind of safety, check out the Safe module,
232included standard in the Perl distribution. This module allows the
233programmer to set up special compartments in which all system operations
234are trapped and namespace access is carefully controlled.
236=head2 Security Bugs
238Beyond the obvious problems that stem from giving special privileges to
239systems as flexible as scripts, on many versions of Unix, setuid scripts
240are inherently insecure right from the start. The problem is a race
241condition in the kernel. Between the time the kernel opens the file to
242see which interpreter to run and when the (now-setuid) interpreter turns
243around and reopens the file to interpret it, the file in question may have
244changed, especially if you have symbolic links on your system.
246Fortunately, sometimes this kernel "feature" can be disabled.
247Unfortunately, there are two ways to disable it. The system can simply
248outlaw scripts with the setuid bit set, which doesn't help much.
249Alternately, it can simply ignore the setuid bit on scripts. If the
250latter is true, Perl can emulate the setuid and setgid mechanism when it
251notices the otherwise useless setuid/gid bits on Perl scripts. It does
252this via a special executable called B<suidperl> that is automatically
54310121 253invoked for you if it's needed.
425e5e39 254
255However, if the kernel setuid script feature isn't disabled, Perl will
256complain loudly that your setuid script is insecure. You'll need to
257either disable the kernel setuid script feature, or put a C wrapper around
258the script. A C wrapper is just a compiled program that does nothing
259except call your Perl program. Compiled programs are not subject to the
260kernel bug that plagues setuid scripts. Here's a simple wrapper, written
261in C:
263 #define REAL_PATH "/path/to/script"
54310121 264 main(ac, av)
425e5e39 265 char **av;
266 {
267 execv(REAL_PATH, av);
54310121 268 }
cb1a09d0 269
54310121 270Compile this wrapper into a binary executable and then make I<it> rather
271than your script setuid or setgid.
425e5e39 272
273See the program B<wrapsuid> in the F<eg> directory of your Perl
274distribution for a convenient way to do this automatically for all your
275setuid Perl programs. It moves setuid scripts into files with the same
276name plus a leading dot, and then compiles a wrapper like the one above
277for each of them.
279In recent years, vendors have begun to supply systems free of this
280inherent security bug. On such systems, when the kernel passes the name
281of the setuid script to open to the interpreter, rather than using a
282pathname subject to meddling, it instead passes I</dev/fd/3>. This is a
283special file already opened on the script, so that there can be no race
284condition for evil scripts to exploit. On these systems, Perl should be
285compiled with C<-DSETUID_SCRIPTS_ARE_SECURE_NOW>. The B<Configure>
286program that builds Perl tries to figure this out for itself, so you
287should never have to specify this yourself. Most modern releases of
288SysVr4 and BSD 4.4 use this approach to avoid the kernel race condition.
290Prior to release 5.003 of Perl, a bug in the code of B<suidperl> could
291introduce a security hole in systems compiled with strict POSIX
68dc0745 293
294=head2 Protecting Your Programs
296There are a number of ways to hide the source to your Perl programs,
297with varying levels of "security".
299First of all, however, you I<can't> take away read permission, because
300the source code has to be readable in order to be compiled and
301interpreted. (That doesn't mean that a CGI script's source is
302readable by people on the web, though.) So you have to leave the
303permissions at the socially friendly 0755 level.
305Some people regard this as a security problem. If your program does
306insecure things, and relies on people not knowing how to exploit those
307insecurities, it is not secure. It is often possible for someone to
308determine the insecure things and exploit them without viewing the
309source. Security through obscurity, the name for hiding your bugs
310instead of fixing them, is little security indeed.
312You can try using encryption via source filters (Filter::* from CPAN).
313But crackers might be able to decrypt it. You can try using the
54310121 314byte code compiler and interpreter described below, but crackers might
68dc0745 315be able to de-compile it. You can try using the native-code compiler
316described below, but crackers might be able to disassemble it. These
317pose varying degrees of difficulty to people wanting to get at your
318code, but none can definitively conceal it (this is true of every
319language, not just Perl).
321If you're concerned about people profiting from your code, then the
322bottom line is that nothing but a restrictive licence will give you
323legal security. License your software and pepper it with threatening
324statements like "This is unpublished proprietary software of XYZ Corp.
325Your access to it does not give you permission to use it blah blah
326blah." You should see a lawyer to be sure your licence's wording will
327stand up in court.