1PERLSEC(1)             Perl Programmers Reference Guide             PERLSEC(1)
2
3
4

NAME

6       perlsec - Perl security
7

DESCRIPTION

9       Perl is designed to make it easy to program securely even when running
10       with extra privileges, like setuid or setgid programs.  Unlike most
11       command line shells, which are based on multiple substitution passes on
12       each line of the script, Perl uses a more conventional evaluation
13       scheme with fewer hidden snags.  Additionally, because the language has
14       more builtin functionality, it can rely less upon external (and
15       possibly untrustworthy) programs to accomplish its purposes.
16

SECURITY VULNERABILITY CONTACT INFORMATION

18       If you believe you have found a security vulnerability in Perl, please
19       email the details to perl5-security-report@perl.org. This creates a new
20       Request Tracker ticket in a special queue which isn't initially
21       publicly accessible. The email will also be copied to a closed
22       subscription unarchived mailing list which includes all the core
23       committers, who will be able to help assess the impact of issues,
24       figure out a resolution, and help co-ordinate the release of patches to
25       mitigate or fix the problem across all platforms on which Perl is
26       supported. Please only use this address for security issues in the Perl
27       core, not for modules independently distributed on CPAN.
28
29       When sending an initial request to the security email address, please
30       don't Cc any other parties, because if they reply to all, the reply
31       will generate yet another new ticket. Once you have received an initial
32       reply with a "[perl #NNNNNN]" ticket number in  the headline, it's okay
33       to Cc subsequent replies to third parties: all emails to the
34       perl5-security-report address with the ticket number in the subject
35       line will be added to the ticket; without it, a new ticket will be
36       created.
37

SECURITY MECHANISMS AND CONCERNS

39   Taint mode
40       Perl automatically enables a set of special security checks, called
41       taint mode, when it detects its program running with differing real and
42       effective user or group IDs.  The setuid bit in Unix permissions is
43       mode 04000, the setgid bit mode 02000; either or both may be set.  You
44       can also enable taint mode explicitly by using the -T command line
45       flag.  This flag is strongly suggested for server programs and any
46       program run on behalf of someone else, such as a CGI script.  Once
47       taint mode is on, it's on for the remainder of your script.
48
49       While in this mode, Perl takes special precautions called taint checks
50       to prevent both obvious and subtle traps.  Some of these checks are
51       reasonably simple, such as verifying that path directories aren't
52       writable by others; careful programmers have always used checks like
53       these.  Other checks, however, are best supported by the language
54       itself, and it is these checks especially that contribute to making a
55       set-id Perl program more secure than the corresponding C program.
56
57       You may not use data derived from outside your program to affect
58       something else outside your program--at least, not by accident.  All
59       command line arguments, environment variables, locale information (see
60       perllocale), results of certain system calls ("readdir()",
61       "readlink()", the variable of "shmread()", the messages returned by
62       "msgrcv()", the password, gcos and shell fields returned by the
63       "getpwxxx()" calls), and all file input are marked as "tainted".
64       Tainted data may not be used directly or indirectly in any command that
65       invokes a sub-shell, nor in any command that modifies files,
66       directories, or processes, with the following exceptions:
67
68       ·   Arguments to "print" and "syswrite" are not checked for
69           taintedness.
70
71       ·   Symbolic methods
72
73               $obj->$method(@args);
74
75           and symbolic sub references
76
77               &{$foo}(@args);
78               $foo->(@args);
79
80           are not checked for taintedness.  This requires extra carefulness
81           unless you want external data to affect your control flow.  Unless
82           you carefully limit what these symbolic values are, people are able
83           to call functions outside your Perl code, such as POSIX::system, in
84           which case they are able to run arbitrary external code.
85
86       ·   Hash keys are never tainted.
87
88       For efficiency reasons, Perl takes a conservative view of whether data
89       is tainted.  If an expression contains tainted data, any subexpression
90       may be considered tainted, even if the value of the subexpression is
91       not itself affected by the tainted data.
92
93       Because taintedness is associated with each scalar value, some elements
94       of an array or hash can be tainted and others not.  The keys of a hash
95       are never tainted.
96
97       For example:
98
99           $arg = shift;               # $arg is tainted
100           $hid = $arg . 'bar';        # $hid is also tainted
101           $line = <>;                 # Tainted
102           $line = <STDIN>;            # Also tainted
103           open FOO, "/home/me/bar" or die $!;
104           $line = <FOO>;              # Still tainted
105           $path = $ENV{'PATH'};       # Tainted, but see below
106           $data = 'abc';              # Not tainted
107
108           system "echo $arg";         # Insecure
109           system "/bin/echo", $arg;   # Considered insecure
110                                       # (Perl doesn't know about /bin/echo)
111           system "echo $hid";         # Insecure
112           system "echo $data";        # Insecure until PATH set
113
114           $path = $ENV{'PATH'};       # $path now tainted
115
116           $ENV{'PATH'} = '/bin:/usr/bin';
117           delete @ENV{'IFS', 'CDPATH', 'ENV', 'BASH_ENV'};
118
119           $path = $ENV{'PATH'};       # $path now NOT tainted
120           system "echo $data";        # Is secure now!
121
122           open(FOO, "< $arg");        # OK - read-only file
123           open(FOO, "> $arg");        # Not OK - trying to write
124
125           open(FOO,"echo $arg|");     # Not OK
126           open(FOO,"-|")
127               or exec 'echo', $arg;   # Also not OK
128
129           $shout = `echo $arg`;       # Insecure, $shout now tainted
130
131           unlink $data, $arg;         # Insecure
132           umask $arg;                 # Insecure
133
134           exec "echo $arg";           # Insecure
135           exec "echo", $arg;          # Insecure
136           exec "sh", '-c', $arg;      # Very insecure!
137
138           @files = <*.c>;             # insecure (uses readdir() or similar)
139           @files = glob('*.c');       # insecure (uses readdir() or similar)
140
141           # In either case, the results of glob are tainted, since the list of
142           # filenames comes from outside of the program.
143
144           $bad = ($arg, 23);          # $bad will be tainted
145           $arg, `true`;               # Insecure (although it isn't really)
146
147       If you try to do something insecure, you will get a fatal error saying
148       something like "Insecure dependency" or "Insecure $ENV{PATH}".
149
150       The exception to the principle of "one tainted value taints the whole
151       expression" is with the ternary conditional operator "?:".  Since code
152       with a ternary conditional
153
154           $result = $tainted_value ? "Untainted" : "Also untainted";
155
156       is effectively
157
158           if ( $tainted_value ) {
159               $result = "Untainted";
160           } else {
161               $result = "Also untainted";
162           }
163
164       it doesn't make sense for $result to be tainted.
165
166   Laundering and Detecting Tainted Data
167       To test whether a variable contains tainted data, and whose use would
168       thus trigger an "Insecure dependency" message, you can use the
169       "tainted()" function of the Scalar::Util module, available in your
170       nearby CPAN mirror, and included in Perl starting from the release
171       5.8.0.  Or you may be able to use the following "is_tainted()"
172       function.
173
174           sub is_tainted {
175               local $@;   # Don't pollute caller's value.
176               return ! eval { eval("#" . substr(join("", @_), 0, 0)); 1 };
177           }
178
179       This function makes use of the fact that the presence of tainted data
180       anywhere within an expression renders the entire expression tainted.
181       It would be inefficient for every operator to test every argument for
182       taintedness.  Instead, the slightly more efficient and conservative
183       approach is used that if any tainted value has been accessed within the
184       same expression, the whole expression is considered tainted.
185
186       But testing for taintedness gets you only so far.  Sometimes you have
187       just to clear your data's taintedness.  Values may be untainted by
188       using them as keys in a hash; otherwise the only way to bypass the
189       tainting mechanism is by referencing subpatterns from a regular
190       expression match.  Perl presumes that if you reference a substring
191       using $1, $2, etc. in a non-tainting pattern, that you knew what you
192       were doing when you wrote that pattern.  That means using a bit of
193       thought--don't just blindly untaint anything, or you defeat the entire
194       mechanism.  It's better to verify that the variable has only good
195       characters (for certain values of "good") rather than checking whether
196       it has any bad characters.  That's because it's far too easy to miss
197       bad characters that you never thought of.
198
199       Here's a test to make sure that the data contains nothing but "word"
200       characters (alphabetics, numerics, and underscores), a hyphen, an at
201       sign, or a dot.
202
203           if ($data =~ /^([-\@\w.]+)$/) {
204               $data = $1;                     # $data now untainted
205           } else {
206               die "Bad data in '$data'";      # log this somewhere
207           }
208
209       This is fairly secure because "/\w+/" doesn't normally match shell
210       metacharacters, nor are dot, dash, or at going to mean something
211       special to the shell.  Use of "/.+/" would have been insecure in theory
212       because it lets everything through, but Perl doesn't check for that.
213       The lesson is that when untainting, you must be exceedingly careful
214       with your patterns.  Laundering data using regular expression is the
215       only mechanism for untainting dirty data, unless you use the strategy
216       detailed below to fork a child of lesser privilege.
217
218       The example does not untaint $data if "use locale" is in effect,
219       because the characters matched by "\w" are determined by the locale.
220       Perl considers that locale definitions are untrustworthy because they
221       contain data from outside the program.  If you are writing a locale-
222       aware program, and want to launder data with a regular expression
223       containing "\w", put "no locale" ahead of the expression in the same
224       block.  See "SECURITY" in perllocale for further discussion and
225       examples.
226
227   Switches On the "#!" Line
228       When you make a script executable, in order to make it usable as a
229       command, the system will pass switches to perl from the script's #!
230       line.  Perl checks that any command line switches given to a setuid (or
231       setgid) script actually match the ones set on the #! line.  Some Unix
232       and Unix-like environments impose a one-switch limit on the #!  line,
233       so you may need to use something like "-wU" instead of "-w -U" under
234       such systems.  (This issue should arise only in Unix or Unix-like
235       environments that support #! and setuid or setgid scripts.)
236
237   Taint mode and @INC
238       When the taint mode ("-T") is in effect, the "." directory is removed
239       from @INC, and the environment variables "PERL5LIB" and "PERLLIB" are
240       ignored by Perl.  You can still adjust @INC from outside the program by
241       using the "-I" command line option as explained in perlrun.  The two
242       environment variables are ignored because they are obscured, and a user
243       running a program could be unaware that they are set, whereas the "-I"
244       option is clearly visible and therefore permitted.
245
246       Another way to modify @INC without modifying the program, is to use the
247       "lib" pragma, e.g.:
248
249         perl -Mlib=/foo program
250
251       The benefit of using "-Mlib=/foo" over "-I/foo", is that the former
252       will automagically remove any duplicated directories, while the latter
253       will not.
254
255       Note that if a tainted string is added to @INC, the following problem
256       will be reported:
257
258         Insecure dependency in require while running with -T switch
259
260   Cleaning Up Your Path
261       For "Insecure $ENV{PATH}" messages, you need to set $ENV{'PATH'} to a
262       known value, and each directory in the path must be absolute and non-
263       writable by others than its owner and group.  You may be surprised to
264       get this message even if the pathname to your executable is fully
265       qualified.  This is not generated because you didn't supply a full path
266       to the program; instead, it's generated because you never set your PATH
267       environment variable, or you didn't set it to something that was safe.
268       Because Perl can't guarantee that the executable in question isn't
269       itself going to turn around and execute some other program that is
270       dependent on your PATH, it makes sure you set the PATH.
271
272       The PATH isn't the only environment variable which can cause problems.
273       Because some shells may use the variables IFS, CDPATH, ENV, and
274       BASH_ENV, Perl checks that those are either empty or untainted when
275       starting subprocesses.  You may wish to add something like this to your
276       setid and taint-checking scripts.
277
278           delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};   # Make %ENV safer
279
280       It's also possible to get into trouble with other operations that don't
281       care whether they use tainted values.  Make judicious use of the file
282       tests in dealing with any user-supplied filenames.  When possible, do
283       opens and such after properly dropping any special user (or group!)
284       privileges.  Perl doesn't prevent you from opening tainted filenames
285       for reading, so be careful what you print out.  The tainting mechanism
286       is intended to prevent stupid mistakes, not to remove the need for
287       thought.
288
289       Perl does not call the shell to expand wild cards when you pass
290       "system" and "exec" explicit parameter lists instead of strings with
291       possible shell wildcards in them.  Unfortunately, the "open", "glob",
292       and backtick functions provide no such alternate calling convention, so
293       more subterfuge will be required.
294
295       Perl provides a reasonably safe way to open a file or pipe from a
296       setuid or setgid program: just create a child process with reduced
297       privilege who does the dirty work for you.  First, fork a child using
298       the special "open" syntax that connects the parent and child by a pipe.
299       Now the child resets its ID set and any other per-process attributes,
300       like environment variables, umasks, current working directories, back
301       to the originals or known safe values.  Then the child process, which
302       no longer has any special permissions, does the "open" or other system
303       call.  Finally, the child passes the data it managed to access back to
304       the parent.  Because the file or pipe was opened in the child while
305       running under less privilege than the parent, it's not apt to be
306       tricked into doing something it shouldn't.
307
308       Here's a way to do backticks reasonably safely.  Notice how the "exec"
309       is not called with a string that the shell could expand.  This is by
310       far the best way to call something that might be subjected to shell
311       escapes: just never call the shell at all.
312
313               use English;
314               die "Can't fork: $!" unless defined($pid = open(KID, "-|"));
315               if ($pid) {           # parent
316                   while (<KID>) {
317                       # do something
318                   }
319                   close KID;
320               } else {
321                   my @temp     = ($EUID, $EGID);
322                   my $orig_uid = $UID;
323                   my $orig_gid = $GID;
324                   $EUID = $UID;
325                   $EGID = $GID;
326                   # Drop privileges
327                   $UID  = $orig_uid;
328                   $GID  = $orig_gid;
329                   # Make sure privs are really gone
330                   ($EUID, $EGID) = @temp;
331                   die "Can't drop privileges"
332                       unless $UID == $EUID  && $GID eq $EGID;
333                   $ENV{PATH} = "/bin:/usr/bin"; # Minimal PATH.
334                   # Consider sanitizing the environment even more.
335                   exec 'myprog', 'arg1', 'arg2'
336                       or die "can't exec myprog: $!";
337               }
338
339       A similar strategy would work for wildcard expansion via "glob",
340       although you can use "readdir" instead.
341
342       Taint checking is most useful when although you trust yourself not to
343       have written a program to give away the farm, you don't necessarily
344       trust those who end up using it not to try to trick it into doing
345       something bad.  This is the kind of security checking that's useful for
346       set-id programs and programs launched on someone else's behalf, like
347       CGI programs.
348
349       This is quite different, however, from not even trusting the writer of
350       the code not to try to do something evil.  That's the kind of trust
351       needed when someone hands you a program you've never seen before and
352       says, "Here, run this."  For that kind of safety, you might want to
353       check out the Safe module, included standard in the Perl distribution.
354       This module allows the programmer to set up special compartments in
355       which all system operations are trapped and namespace access is
356       carefully controlled.  Safe should not be considered bullet-proof,
357       though: it will not prevent the foreign code to set up infinite loops,
358       allocate gigabytes of memory, or even abusing perl bugs to make the
359       host interpreter crash or behave in unpredictable ways.  In any case
360       it's better avoided completely if you're really concerned about
361       security.
362
363   Security Bugs
364       Beyond the obvious problems that stem from giving special privileges to
365       systems as flexible as scripts, on many versions of Unix, set-id
366       scripts are inherently insecure right from the start.  The problem is a
367       race condition in the kernel.  Between the time the kernel opens the
368       file to see which interpreter to run and when the (now-set-id)
369       interpreter turns around and reopens the file to interpret it, the file
370       in question may have changed, especially if you have symbolic links on
371       your system.
372
373       Fortunately, sometimes this kernel "feature" can be disabled.
374       Unfortunately, there are two ways to disable it.  The system can simply
375       outlaw scripts with any set-id bit set, which doesn't help much.
376       Alternately, it can simply ignore the set-id bits on scripts.
377
378       However, if the kernel set-id script feature isn't disabled, Perl will
379       complain loudly that your set-id script is insecure.  You'll need to
380       either disable the kernel set-id script feature, or put a C wrapper
381       around the script.  A C wrapper is just a compiled program that does
382       nothing except call your Perl program.   Compiled programs are not
383       subject to the kernel bug that plagues set-id scripts.  Here's a simple
384       wrapper, written in C:
385
386           #include <unistd.h>
387           #include <stdio.h>
388           #include <string.h>
389           #include <errno.h>
390
391           #define REAL_PATH "/path/to/script"
392
393           int main(int argc, char **argv)
394           {
395               execv(REAL_PATH, argv);
396               fprintf(stderr, "%s: %s: %s\n",
397                               argv[0], REAL_PATH, strerror(errno));
398               return 127;
399           }
400
401       Compile this wrapper into a binary executable and then make it rather
402       than your script setuid or setgid.
403
404       In recent years, vendors have begun to supply systems free of this
405       inherent security bug.  On such systems, when the kernel passes the
406       name of the set-id script to open to the interpreter, rather than using
407       a pathname subject to meddling, it instead passes /dev/fd/3.  This is a
408       special file already opened on the script, so that there can be no race
409       condition for evil scripts to exploit.  On these systems, Perl should
410       be compiled with "-DSETUID_SCRIPTS_ARE_SECURE_NOW".  The Configure
411       program that builds Perl tries to figure this out for itself, so you
412       should never have to specify this yourself.  Most modern releases of
413       SysVr4 and BSD 4.4 use this approach to avoid the kernel race
414       condition.
415
416   Protecting Your Programs
417       There are a number of ways to hide the source to your Perl programs,
418       with varying levels of "security".
419
420       First of all, however, you can't take away read permission, because the
421       source code has to be readable in order to be compiled and interpreted.
422       (That doesn't mean that a CGI script's source is readable by people on
423       the web, though.)  So you have to leave the permissions at the socially
424       friendly 0755 level.  This lets people on your local system only see
425       your source.
426
427       Some people mistakenly regard this as a security problem.  If your
428       program does insecure things, and relies on people not knowing how to
429       exploit those insecurities, it is not secure.  It is often possible for
430       someone to determine the insecure things and exploit them without
431       viewing the source.  Security through obscurity, the name for hiding
432       your bugs instead of fixing them, is little security indeed.
433
434       You can try using encryption via source filters (Filter::* from CPAN,
435       or Filter::Util::Call and Filter::Simple since Perl 5.8).  But crackers
436       might be able to decrypt it.  You can try using the byte code compiler
437       and interpreter described below, but crackers might be able to de-
438       compile it.  You can try using the native-code compiler described
439       below, but crackers might be able to disassemble it.  These pose
440       varying degrees of difficulty to people wanting to get at your code,
441       but none can definitively conceal it (this is true of every language,
442       not just Perl).
443
444       If you're concerned about people profiting from your code, then the
445       bottom line is that nothing but a restrictive license will give you
446       legal security.  License your software and pepper it with threatening
447       statements like "This is unpublished proprietary software of XYZ Corp.
448       Your access to it does not give you permission to use it blah blah
449       blah."  You should see a lawyer to be sure your license's wording will
450       stand up in court.
451
452   Unicode
453       Unicode is a new and complex technology and one may easily overlook
454       certain security pitfalls.  See perluniintro for an overview and
455       perlunicode for details, and "Security Implications of Unicode" in
456       perlunicode for security implications in particular.
457
458   Algorithmic Complexity Attacks
459       Certain internal algorithms used in the implementation of Perl can be
460       attacked by choosing the input carefully to consume large amounts of
461       either time or space or both.  This can lead into the so-called Denial
462       of Service (DoS) attacks.
463
464       ·   Hash Algorithm - Hash algorithms like the one used in Perl are well
465           known to be vulnerable to collision attacks on their hash function.
466           Such attacks involve constructing a set of keys which collide into
467           the same bucket producing inefficient behavior.  Such attacks often
468           depend on discovering the seed of the hash function used to map the
469           keys to buckets.  That seed is then used to brute-force a key set
470           which can be used to mount a denial of service attack.  In Perl
471           5.8.1 changes were introduced to harden Perl to such attacks, and
472           then later in Perl 5.18.0 these features were enhanced and
473           additional protections added.
474
475           At the time of this writing, Perl 5.18.0 is considered to be well-
476           hardened against algorithmic complexity attacks on its hash
477           implementation.  This is largely owed to the following measures
478           mitigate attacks:
479
480           Hash Seed Randomization
481               In order to make it impossible to know what seed to generate an
482               attack key set for, this seed is randomly initialized at
483               process start.  This may be overridden by using the
484               PERL_HASH_SEED environment variable, see "PERL_HASH_SEED" in
485               perlrun.  This environment variable controls how items are
486               actually stored, not how they are presented via "keys",
487               "values" and "each".
488
489           Hash Traversal Randomization
490               Independent of which seed is used in the hash function, "keys",
491               "values", and "each" return items in a per-hash randomized
492               order.  Modifying a hash by insertion will change the iteration
493               order of that hash.  This behavior can be overridden by using
494               "hash_traversal_mask()" from Hash::Util or by using the
495               PERL_PERTURB_KEYS environment variable, see "PERL_PERTURB_KEYS"
496               in perlrun.  Note that this feature controls the "visible"
497               order of the keys, and not the actual order they are stored in.
498
499           Bucket Order Perturbance
500               When items collide into a given hash bucket the order they are
501               stored in the chain is no longer predictable in Perl 5.18.
502               This has the intention to make it harder to observe a
503               collision.  This behavior can be overridden by using the
504               PERL_PERTURB_KEYS environment variable, see "PERL_PERTURB_KEYS"
505               in perlrun.
506
507           New Default Hash Function
508               The default hash function has been modified with the intention
509               of making it harder to infer the hash seed.
510
511           Alternative Hash Functions
512               The source code includes multiple hash algorithms to choose
513               from.  While we believe that the default perl hash is robust to
514               attack, we have included the hash function Siphash as a fall-
515               back option.  At the time of release of Perl 5.18.0 Siphash is
516               believed to be of cryptographic strength.  This is not the
517               default as it is much slower than the default hash.
518
519           Without compiling a special Perl, there is no way to get the exact
520           same behavior of any versions prior to Perl 5.18.0.  The closest
521           one can get is by setting PERL_PERTURB_KEYS to 0 and setting the
522           PERL_HASH_SEED to a known value.  We do not advise those settings
523           for production use due to the above security considerations.
524
525           Perl has never guaranteed any ordering of the hash keys, and the
526           ordering has already changed several times during the lifetime of
527           Perl 5.  Also, the ordering of hash keys has always been, and
528           continues to be, affected by the insertion order and the history of
529           changes made to the hash over its lifetime.
530
531           Also note that while the order of the hash elements might be
532           randomized, this "pseudo-ordering" should not be used for
533           applications like shuffling a list randomly (use
534           "List::Util::shuffle()" for that, see List::Util, a standard core
535           module since Perl 5.8.0; or the CPAN module
536           "Algorithm::Numerical::Shuffle"), or for generating permutations
537           (use e.g. the CPAN modules "Algorithm::Permute" or
538           "Algorithm::FastPermute"), or for any cryptographic applications.
539
540           Tied hashes may have their own ordering and algorithmic complexity
541           attacks.
542
543       ·   Regular expressions - Perl's regular expression engine is so called
544           NFA (Non-deterministic Finite Automaton), which among other things
545           means that it can rather easily consume large amounts of both time
546           and space if the regular expression may match in several ways.
547           Careful crafting of the regular expressions can help but quite
548           often there really isn't much one can do (the book "Mastering
549           Regular Expressions" is required reading, see perlfaq2).  Running
550           out of space manifests itself by Perl running out of memory.
551
552       ·   Sorting - the quicksort algorithm used in Perls before 5.8.0 to
553           implement the sort() function is very easy to trick into
554           misbehaving so that it consumes a lot of time.  Starting from Perl
555           5.8.0 a different sorting algorithm, mergesort, is used by default.
556           Mergesort cannot misbehave on any input.
557
558       See
559       <https://www.usenix.org/legacy/events/sec03/tech/full_papers/crosby/crosby.pdf>
560       for more information, and any computer science textbook on algorithmic
561       complexity.
562

SEE ALSO

564       perlrun for its description of cleaning up environment variables.
565
566
567
568perl v5.26.3                      2018-03-23                        PERLSEC(1)
Impressum