This is a live mirror of the Perl 5 development currently hosted at
Don't encourage using Safe in perlsec
[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
17If you believe you have found a security vulnerability in Perl, please email with details. This points to a closed
19subscription, unarchived mailing list. Please only use this address for
20security issues in the Perl core, not for modules independently distributed on
25=head2 Taint mode
425e5e39 27Perl automatically enables a set of special security checks, called I<taint
28mode>, when it detects its program running with differing real and effective
29user or group IDs. The setuid bit in Unix permissions is mode 04000, the
30setgid bit mode 02000; either or both may be set. You can also enable taint
5f05dabc 31mode explicitly by using the B<-T> command line flag. This flag is
425e5e39 32I<strongly> suggested for server programs and any program run on behalf of
fb73857a 33someone else, such as a CGI script. Once taint mode is on, it's on for
34the remainder of your script.
a0d0e21e 35
1e422769 36While in this mode, Perl takes special precautions called I<taint
37checks> to prevent both obvious and subtle traps. Some of these checks
38are reasonably simple, such as verifying that path directories aren't
39writable by others; careful programmers have always used checks like
40these. Other checks, however, are best supported by the language itself,
fb73857a 41and it is these checks especially that contribute to making a set-id Perl
425e5e39 42program more secure than the corresponding C program.
fb73857a 44You may not use data derived from outside your program to affect
45something else outside your program--at least, not by accident. All
46command line arguments, environment variables, locale information (see
47L<perllocale>), results of certain system calls (C<readdir()>,
48C<readlink()>, the variable of C<shmread()>, the messages returned by
49C<msgrcv()>, the password, gcos and shell fields returned by the
50C<getpwxxx()> calls), and all file input are marked as "tainted".
51Tainted data may not be used directly or indirectly in any command
52that invokes a sub-shell, nor in any command that modifies files,
53directories, or processes, B<with the following exceptions>:
55=over 4
57=item *
59Arguments to C<print> and C<syswrite> are B<not> checked for taintedness.
61=item *
63Symbolic methods
65 $obj->$method(@args);
67and symbolic sub references
69 &{$foo}(@args);
70 $foo->(@args);
72are not checked for taintedness. This requires extra carefulness
73unless you want external data to affect your control flow. Unless
74you carefully limit what these symbolic values are, people are able
75to call functions B<outside> your Perl code, such as POSIX::system,
76in which case they are able to run arbitrary external code.
78=item *
80Hash keys are B<never> tainted.
84For efficiency reasons, Perl takes a conservative view of
85whether data is tainted. If an expression contains tainted data,
86any subexpression may be considered tainted, even if the value
87of the subexpression is not itself affected by the tainted data.
ee556d55 88
d929ce6f 89Because taintedness is associated with each scalar value, some
595bde10 90elements of an array or hash can be tainted and others not.
8ea1447c 91The keys of a hash are B<never> tainted.
a0d0e21e 92
93For example:
425e5e39 95 $arg = shift; # $arg is tainted
96 $hid = $arg, 'bar'; # $hid is also tainted
97 $line = <>; # Tainted
8ebc5c01 98 $line = <STDIN>; # Also tainted
99 open FOO, "/home/me/bar" or die $!;
100 $line = <FOO>; # Still tainted
a0d0e21e 101 $path = $ENV{'PATH'}; # Tainted, but see below
425e5e39 102 $data = 'abc'; # Not tainted
a0d0e21e 103
425e5e39 104 system "echo $arg"; # Insecure
7de90c4d 105 system "/bin/echo", $arg; # Considered insecure
bbd7eb8a 106 # (Perl doesn't know about /bin/echo)
425e5e39 107 system "echo $hid"; # Insecure
108 system "echo $data"; # Insecure until PATH set
a0d0e21e 109
425e5e39 110 $path = $ENV{'PATH'}; # $path now tainted
a0d0e21e 111
54310121 112 $ENV{'PATH'} = '/bin:/usr/bin';
c90c0ff4 113 delete @ENV{'IFS', 'CDPATH', 'ENV', 'BASH_ENV'};
a0d0e21e 114
425e5e39 115 $path = $ENV{'PATH'}; # $path now NOT tainted
116 system "echo $data"; # Is secure now!
a0d0e21e 117
425e5e39 118 open(FOO, "< $arg"); # OK - read-only file
119 open(FOO, "> $arg"); # Not OK - trying to write
a0d0e21e 120
bbd7eb8a 121 open(FOO,"echo $arg|"); # Not OK
425e5e39 122 open(FOO,"-|")
7de90c4d 123 or exec 'echo', $arg; # Also not OK
a0d0e21e 124
425e5e39 125 $shout = `echo $arg`; # Insecure, $shout now tainted
a0d0e21e 126
425e5e39 127 unlink $data, $arg; # Insecure
128 umask $arg; # Insecure
a0d0e21e 129
bbd7eb8a 130 exec "echo $arg"; # Insecure
131 exec "echo", $arg; # Insecure
132 exec "sh", '-c', $arg; # Very insecure!
a0d0e21e 133
134 @files = <*.c>; # insecure (uses readdir() or similar)
135 @files = glob('*.c'); # insecure (uses readdir() or similar)
7bac28a0 136
137 # In Perl releases older than 5.6.0 the <*.c> and glob('*.c') would
138 # have used an external program to do the filename expansion; but in
139 # either case the result is tainted since the list of filenames comes
140 # from outside of the program.
142 $bad = ($arg, 23); # $bad will be tainted
143 $arg, `true`; # Insecure (although it isn't really)
a0d0e21e 145If you try to do something insecure, you will get a fatal error saying
7de90c4d 146something like "Insecure dependency" or "Insecure $ENV{PATH}".
425e5e39 147
148The exception to the principle of "one tainted value taints the whole
149expression" is with the ternary conditional operator C<?:>. Since code
150with a ternary conditional
152 $result = $tainted_value ? "Untainted" : "Also untainted";
154is effectively
156 if ( $tainted_value ) {
157 $result = "Untainted";
158 } else {
159 $result = "Also untainted";
160 }
162it doesn't make sense for C<$result> to be tainted.
425e5e39 164=head2 Laundering and Detecting Tainted Data
166To test whether a variable contains tainted data, and whose use would
167thus trigger an "Insecure dependency" message, you can use the
23634c10 168C<tainted()> function of the Scalar::Util module, available in your
3f7d42d8 169nearby CPAN mirror, and included in Perl starting from the release 5.8.0.
595bde10 170Or you may be able to use the following C<is_tainted()> function.
425e5e39 171
172 sub is_tainted {
61890e45 173 return ! eval { eval("#" . substr(join("", @_), 0, 0)); 1 };
425e5e39 174 }
176This function makes use of the fact that the presence of tainted data
177anywhere within an expression renders the entire expression tainted. It
178would be inefficient for every operator to test every argument for
179taintedness. Instead, the slightly more efficient and conservative
180approach is used that if any tainted value has been accessed within the
181same expression, the whole expression is considered tainted.
5f05dabc 183But testing for taintedness gets you only so far. Sometimes you have just
184to clear your data's taintedness. Values may be untainted by using them
185as keys in a hash; otherwise the only way to bypass the tainting
54310121 186mechanism is by referencing subpatterns from a regular expression match.
425e5e39 187Perl presumes that if you reference a substring using $1, $2, etc., that
188you knew what you were doing when you wrote the pattern. That means using
189a bit of thought--don't just blindly untaint anything, or you defeat the
190entire mechanism. It's better to verify that the variable has only good
191characters (for certain values of "good") rather than checking whether it
192has any bad characters. That's because it's far too easy to miss bad
193characters that you never thought of.
425e5e39 194
195Here's a test to make sure that the data contains nothing but "word"
196characters (alphabetics, numerics, and underscores), a hyphen, an at sign,
197or a dot.
54310121 199 if ($data =~ /^([-\@\w.]+)$/) {
425e5e39 200 $data = $1; # $data now untainted
201 } else {
3a2263fe 202 die "Bad data in '$data'"; # log this somewhere
425e5e39 203 }
5f05dabc 205This is fairly secure because C</\w+/> doesn't normally match shell
425e5e39 206metacharacters, nor are dot, dash, or at going to mean something special
207to the shell. Use of C</.+/> would have been insecure in theory because
208it lets everything through, but Perl doesn't check for that. The lesson
209is that when untainting, you must be exceedingly careful with your patterns.
19799a22 210Laundering data using regular expression is the I<only> mechanism for
425e5e39 211untainting dirty data, unless you use the strategy detailed below to fork
212a child of lesser privilege.
23634c10 214The example does not untaint C<$data> if C<use locale> is in effect,
215because the characters matched by C<\w> are determined by the locale.
216Perl considers that locale definitions are untrustworthy because they
217contain data from outside the program. If you are writing a
218locale-aware program, and want to launder data with a regular expression
219containing C<\w>, put C<no locale> ahead of the expression in the same
220block. See L<perllocale/SECURITY> for further discussion and examples.
222=head2 Switches On the "#!" Line
224When you make a script executable, in order to make it usable as a
225command, the system will pass switches to perl from the script's #!
54310121 226line. Perl checks that any command line switches given to a setuid
3a52c276 227(or setgid) script actually match the ones set on the #! line. Some
54310121 228Unix and Unix-like environments impose a one-switch limit on the #!
3a52c276 229line, so you may need to use something like C<-wU> instead of C<-w -U>
54310121 230under such systems. (This issue should arise only in Unix or
231Unix-like environments that support #! and setuid or setgid scripts.)
3a52c276 232
233=head2 Taint mode and @INC
235When the taint mode (C<-T>) is in effect, the "." directory is removed
236from C<@INC>, and the environment variables C<PERL5LIB> and C<PERLLIB>
237are ignored by Perl. You can still adjust C<@INC> from outside the
238program by using the C<-I> command line option as explained in
239L<perlrun>. The two environment variables are ignored because
240they are obscured, and a user running a program could be unaware that
241they are set, whereas the C<-I> option is clearly visible and
242therefore permitted.
244Another way to modify C<@INC> without modifying the program, is to use
245the C<lib> pragma, e.g.:
247 perl -Mlib=/foo program
249The benefit of using C<-Mlib=/foo> over C<-I/foo>, is that the former
250will automagically remove any duplicated directories, while the later
251will not.
253Note that if a tainted string is added to C<@INC>, the following
254problem will be reported:
256 Insecure dependency in require while running with -T switch
425e5e39 258=head2 Cleaning Up Your Path
260For "Insecure C<$ENV{PATH}>" messages, you need to set C<$ENV{'PATH'}> to
261a known value, and each directory in the path must be absolute and
262non-writable by others than its owner and group. You may be surprised to
263get this message even if the pathname to your executable is fully
264qualified. This is I<not> generated because you didn't supply a full path
265to the program; instead, it's generated because you never set your PATH
266environment variable, or you didn't set it to something that was safe.
267Because Perl can't guarantee that the executable in question isn't itself
268going to turn around and execute some other program that is dependent on
269your PATH, it makes sure you set the PATH.
a0d0e21e 270
271The PATH isn't the only environment variable which can cause problems.
272Because some shells may use the variables IFS, CDPATH, ENV, and
273BASH_ENV, Perl checks that those are either empty or untainted when
274starting subprocesses. You may wish to add something like this to your
275setid and taint-checking scripts.
277 delete @ENV{qw(IFS CDPATH ENV BASH_ENV)}; # Make %ENV safer
279It's also possible to get into trouble with other operations that don't
280care whether they use tainted values. Make judicious use of the file
281tests in dealing with any user-supplied filenames. When possible, do
fb73857a 282opens and such B<after> properly dropping any special user (or group!)
283privileges. Perl doesn't prevent you from opening tainted filenames for reading,
284so be careful what you print out. The tainting mechanism is intended to
285prevent stupid mistakes, not to remove the need for thought.
287Perl does not call the shell to expand wild cards when you pass C<system>
288and C<exec> explicit parameter lists instead of strings with possible shell
289wildcards in them. Unfortunately, the C<open>, C<glob>, and
54310121 290backtick functions provide no such alternate calling convention, so more
291subterfuge will be required.
425e5e39 292
293Perl provides a reasonably safe way to open a file or pipe from a setuid
294or setgid program: just create a child process with reduced privilege who
295does the dirty work for you. First, fork a child using the special
23634c10 296C<open> syntax that connects the parent and child by a pipe. Now the
425e5e39 297child resets its ID set and any other per-process attributes, like
298environment variables, umasks, current working directories, back to the
299originals or known safe values. Then the child process, which no longer
23634c10 300has any special permissions, does the C<open> or other system call.
425e5e39 301Finally, the child passes the data it managed to access back to the
5f05dabc 302parent. Because the file or pipe was opened in the child while running
425e5e39 303under less privilege than the parent, it's not apt to be tricked into
304doing something it shouldn't.
23634c10 306Here's a way to do backticks reasonably safely. Notice how the C<exec> is
425e5e39 307not called with a string that the shell could expand. This is by far the
308best way to call something that might be subjected to shell escapes: just
fb73857a 309never call the shell at all.
cb1a09d0 310
a1ce9542 311 use English '-no_match_vars';
312 die "Can't fork: $!" unless defined($pid = open(KID, "-|"));
313 if ($pid) { # parent
314 while (<KID>) {
315 # do something
316 }
317 close KID;
318 } else {
319 my @temp = ($EUID, $EGID);
320 my $orig_uid = $UID;
321 my $orig_gid = $GID;
322 $EUID = $UID;
323 $EGID = $GID;
324 # Drop privileges
325 $UID = $orig_uid;
326 $GID = $orig_gid;
327 # Make sure privs are really gone
328 ($EUID, $EGID) = @temp;
329 die "Can't drop privileges"
330 unless $UID == $EUID && $GID eq $EGID;
331 $ENV{PATH} = "/bin:/usr/bin"; # Minimal PATH.
332 # Consider sanitizing the environment even more.
333 exec 'myprog', 'arg1', 'arg2'
334 or die "can't exec myprog: $!";
335 }
425e5e39 336
fb73857a 337A similar strategy would work for wildcard expansion via C<glob>, although
338you can use C<readdir> instead.
425e5e39 339
340Taint checking is most useful when although you trust yourself not to have
341written a program to give away the farm, you don't necessarily trust those
342who end up using it not to try to trick it into doing something bad. This
fb73857a 343is the kind of security checking that's useful for set-id programs and
425e5e39 344programs launched on someone else's behalf, like CGI programs.
346This is quite different, however, from not even trusting the writer of the
347code not to try to do something evil. That's the kind of trust needed
348when someone hands you a program you've never seen before and says, "Here,
349run this." For that kind of safety, you might want to check out the Safe
350module, included standard in the Perl distribution. This module allows the
425e5e39 351programmer to set up special compartments in which all system operations
352are trapped and namespace access is carefully controlled. Safe should
353not be considered bullet-proof, though: it will not prevent the foreign
354code to set up infinite loops, allocate gigabytes of memory, or even
355abusing perl bugs to make the host interpreter crash or behave in
356unpredictable ways. In any case it's better avoided completely if you're
357really concerned about security.
425e5e39 358
359=head2 Security Bugs
361Beyond the obvious problems that stem from giving special privileges to
fb73857a 362systems as flexible as scripts, on many versions of Unix, set-id scripts
425e5e39 363are inherently insecure right from the start. The problem is a race
364condition in the kernel. Between the time the kernel opens the file to
fb73857a 365see which interpreter to run and when the (now-set-id) interpreter turns
425e5e39 366around and reopens the file to interpret it, the file in question may have
367changed, especially if you have symbolic links on your system.
369Fortunately, sometimes this kernel "feature" can be disabled.
370Unfortunately, there are two ways to disable it. The system can simply
fb73857a 371outlaw scripts with any set-id bit set, which doesn't help much.
cc69b689 372Alternately, it can simply ignore the set-id bits on scripts.
425e5e39 373
fb73857a 374However, if the kernel set-id script feature isn't disabled, Perl will
375complain loudly that your set-id script is insecure. You'll need to
376either disable the kernel set-id script feature, or put a C wrapper around
425e5e39 377the script. A C wrapper is just a compiled program that does nothing
378except call your Perl program. Compiled programs are not subject to the
fb73857a 379kernel bug that plagues set-id scripts. Here's a simple wrapper, written
425e5e39 380in C:
382 #define REAL_PATH "/path/to/script"
54310121 383 main(ac, av)
425e5e39 384 char **av;
385 {
386 execv(REAL_PATH, av);
54310121 387 }
cb1a09d0 388
54310121 389Compile this wrapper into a binary executable and then make I<it> rather
390than your script setuid or setgid.
425e5e39 391
425e5e39 392In recent years, vendors have begun to supply systems free of this
393inherent security bug. On such systems, when the kernel passes the name
fb73857a 394of the set-id script to open to the interpreter, rather than using a
425e5e39 395pathname subject to meddling, it instead passes I</dev/fd/3>. This is a
396special file already opened on the script, so that there can be no race
397condition for evil scripts to exploit. On these systems, Perl should be
23634c10 398compiled with C<-DSETUID_SCRIPTS_ARE_SECURE_NOW>. The F<Configure>
425e5e39 399program that builds Perl tries to figure this out for itself, so you
400should never have to specify this yourself. Most modern releases of
401SysVr4 and BSD 4.4 use this approach to avoid the kernel race condition.
68dc0745 403=head2 Protecting Your Programs
405There are a number of ways to hide the source to your Perl programs,
406with varying levels of "security".
408First of all, however, you I<can't> take away read permission, because
409the source code has to be readable in order to be compiled and
410interpreted. (That doesn't mean that a CGI script's source is
411readable by people on the web, though.) So you have to leave the
412permissions at the socially friendly 0755 level. This lets
413people on your local system only see your source.
68dc0745 414
5a964f20 415Some people mistakenly regard this as a security problem. If your program does
68dc0745 416insecure things, and relies on people not knowing how to exploit those
417insecurities, it is not secure. It is often possible for someone to
418determine the insecure things and exploit them without viewing the
419source. Security through obscurity, the name for hiding your bugs
420instead of fixing them, is little security indeed.
422You can try using encryption via source filters (Filter::* from CPAN,
423or Filter::Util::Call and Filter::Simple since Perl 5.8).
424But crackers might be able to decrypt it. You can try using the byte
425code compiler and interpreter described below, but crackers might be
426able to de-compile it. You can try using the native-code compiler
68dc0745 427described below, but crackers might be able to disassemble it. These
428pose varying degrees of difficulty to people wanting to get at your
429code, but none can definitively conceal it (this is true of every
430language, not just Perl).
432If you're concerned about people profiting from your code, then the
3462340b 433bottom line is that nothing but a restrictive license will give you
68dc0745 434legal security. License your software and pepper it with threatening
435statements like "This is unpublished proprietary software of XYZ Corp.
436Your access to it does not give you permission to use it blah blah
3462340b 437blah." You should see a lawyer to be sure your license's wording will
68dc0745 438stand up in court.
5a964f20 439
440=head2 Unicode
442Unicode is a new and complex technology and one may easily overlook
443certain security pitfalls. See L<perluniintro> for an overview and
444L<perlunicode> for details, and L<perlunicode/"Security Implications
445of Unicode"> for security implications in particular.
447=head2 Algorithmic Complexity Attacks
449Certain internal algorithms used in the implementation of Perl can
450be attacked by choosing the input carefully to consume large amounts
451of either time or space or both. This can lead into the so-called
452I<Denial of Service> (DoS) attacks.
454=over 4
456=item *
458Hash Function - the algorithm used to "order" hash elements has been
459changed several times during the development of Perl, mainly to be
460reasonably fast. In Perl 5.8.1 also the security aspect was taken
461into account.
463In Perls before 5.8.1 one could rather easily generate data that as
464hash keys would cause Perl to consume large amounts of time because
465internal structure of hashes would badly degenerate. In Perl 5.8.1
466the hash function is randomly perturbed by a pseudorandom seed which
467makes generating such naughty hash keys harder.
468See L<perlrun/PERL_HASH_SEED> for more information.
470In Perl 5.8.1 the random perturbation was done by default, but as of
4715.8.2 it is only used on individual hashes if the internals detect the
472insertion of pathological data. If one wants for some reason emulate the
473old behaviour (and expose oneself to DoS attacks) one can set the
474environment variable PERL_HASH_SEED to zero to disable the protection
475(or any other integer to force a known perturbation, rather than random).
476One possible reason for wanting to emulate the old behaviour is that in the
477new behaviour consecutive runs of Perl will order hash keys differently,
478which may confuse some applications (like Data::Dumper: the outputs of two
479different runs are no longer identical).
504f80c1 480
481B<Perl has never guaranteed any ordering of the hash keys>, and the
482ordering has already changed several times during the lifetime of
483Perl 5. Also, the ordering of hash keys has always been, and
484continues to be, affected by the insertion order.
486Also note that while the order of the hash elements might be
487randomised, this "pseudoordering" should B<not> be used for
488applications like shuffling a list randomly (use List::Util::shuffle()
489for that, see L<List::Util>, a standard core module since Perl 5.8.0;
490or the CPAN module Algorithm::Numerical::Shuffle), or for generating
491permutations (use e.g. the CPAN modules Algorithm::Permute or
492Algorithm::FastPermute), or for any cryptographic applications.
494=item *
496Regular expressions - Perl's regular expression engine is so called NFA
497(Non-deterministic Finite Automaton), which among other things means that
498it can rather easily consume large amounts of both time and space if the
499regular expression may match in several ways. Careful crafting of the
500regular expressions can help but quite often there really isn't much
501one can do (the book "Mastering Regular Expressions" is required
502reading, see L<perlfaq2>). Running out of space manifests itself by
503Perl running out of memory.
505=item *
507Sorting - the quicksort algorithm used in Perls before 5.8.0 to
508implement the sort() function is very easy to trick into misbehaving
509so that it consumes a lot of time. Starting from Perl 5.8.0 a different
510sorting algorithm, mergesort, is used by default. Mergesort cannot
511misbehave on any input.
515See L<> for more information,
3462340b 516and any computer science textbook on algorithmic complexity.
504f80c1 517
518=head1 SEE ALSO
520L<perlrun> for its description of cleaning up environment variables.