This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Distinguish between "identifier" and full variable name
[perl5.git] / pod / perlsec.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perlsec - Perl security
4
5=head1 DESCRIPTION
6
7Perl is designed to make it easy to write secure setuid and setgid
8scripts. Unlike shells, which are based on multiple substitution
9passes on each line of the script, Perl uses a more conventional
10evaluation scheme with fewer hidden "gotchas". Additionally, since the
11language has more built-in functionality, it has to rely less upon
12external (and possibly untrustworthy) programs to accomplish its
13purposes.
14
15Beyond the obvious problems that stem from giving special privileges to
16such flexible systems as scripts, on many operating systems, setuid
17scripts are inherently insecure right from the start. This is because
18that between the time that the kernel opens up the file to see what to
19run, and when the now setuid interpreter it ran turns around and reopens
20the file so it can interpret it, things may have changed, especially if
21you have symbolic links on your system.
22
23Fortunately, sometimes this kernel "feature" can be disabled.
24Unfortunately, there are two ways to disable it. The system can simply
25outlaw scripts with the setuid bit set, which doesn't help much.
26Alternately, it can simply ignore the setuid bit on scripts. If the
27latter is true, Perl can emulate the setuid and setgid mechanism when it
28notices the otherwise useless setuid/gid bits on Perl scripts. It does
29this via a special executable called B<suidperl> that is automatically
30invoked for you if it's needed.
31
32If, however, the kernel setuid script feature isn't disabled, Perl will
33complain loudly that your setuid script is insecure. You'll need to
34either disable the kernel setuid script feature, or put a C wrapper around
35the script. See the program B<wrapsuid> in the F<eg> directory of your
36Perl distribution for how to go about doing this.
37
38There are some systems on which setuid scripts are free of this inherent
39security bug. For example, recent releases of Solaris are like this. On
40such systems, when the kernel passes the name of the setuid script to open
41to the interpreter, rather than using a pathname subject to mettling, it
42instead passes /dev/fd/3. This is a special file already opened on the
43script, so that there can be no race condition for evil scripts to
44exploit. On these systems, Perl should be compiled with
45C<-DSETUID_SCRIPTS_ARE_SECURE_NOW>. The B<Configure> program that builds
46Perl tries to figure this out for itself.
47
cb1a09d0
AD
48When executing a setuid script, or when you have turned on taint checking
49explicitly using the B<-T> flag, Perl takes special precautions to
a0d0e21e
LW
50prevent you from falling into any obvious traps. (In some ways, a Perl
51script is more secure than the corresponding C program.) Any command line
52argument, environment variable, or input is marked as "tainted", and may
53not be used, directly or indirectly, in any command that invokes a
54subshell, or in any command that modifies files, directories, or
55processes. Any variable that is set within an expression that has
56previously referenced a tainted value also becomes tainted (even if it is
57logically impossible for the tainted value to influence the variable).
58For example:
59
60 $foo = shift; # $foo is tainted
61 $bar = $foo,'bar'; # $bar is also tainted
62 $xxx = <>; # Tainted
63 $path = $ENV{'PATH'}; # Tainted, but see below
64 $abc = 'abc'; # Not tainted
65
66 system "echo $foo"; # Insecure
67 system "/bin/echo", $foo; # Secure (doesn't use sh)
68 system "echo $bar"; # Insecure
69 system "echo $abc"; # Insecure until PATH set
70
71 $ENV{'PATH'} = '/bin:/usr/bin';
72 $ENV{'IFS'} = '' if $ENV{'IFS'} ne '';
73
74 $path = $ENV{'PATH'}; # Not tainted
75 system "echo $abc"; # Is secure now!
76
77 open(FOO,"$foo"); # OK
78 open(FOO,">$foo"); # Not OK
79
80 open(FOO,"echo $foo|"); # Not OK, but...
81 open(FOO,"-|") || exec 'echo', $foo; # OK
82
83 $zzz = `echo $foo`; # Insecure, zzz tainted
84
85 unlink $abc,$foo; # Insecure
86 umask $foo; # Insecure
87
88 exec "echo $foo"; # Insecure
89 exec "echo", $foo; # Secure (doesn't use sh)
90 exec "sh", '-c', $foo; # Considered secure, alas
91
92The taintedness is associated with each scalar value, so some elements
93of an array can be tainted, and others not.
94
95If you try to do something insecure, you will get a fatal error saying
96something like "Insecure dependency" or "Insecure PATH". Note that you
97can still write an insecure system call or exec, but only by explicitly
98doing something like the last example above. You can also bypass the
99tainting mechanism by referencing subpatterns--Perl presumes that if
100you reference a substring using $1, $2, etc, you knew what you were
101doing when you wrote the pattern:
102
103 $ARGV[0] =~ /^-P(\w+)$/;
104 $printer = $1; # Not tainted
105
106This is fairly secure since C<\w+> doesn't match shell metacharacters.
107Use of C</.+/> would have been insecure, but Perl doesn't check for that,
108so you must be careful with your patterns. This is the I<ONLY> mechanism
109for untainting user supplied filenames if you want to do file operations
110on them (unless you make C<$E<gt>> equal to C<$E<lt>> ).
111
748a9306 112For "Insecure $ENV{PATH}" messages, you need to set C<$ENV{'PATH'}> to a known
a0d0e21e
LW
113value, and each directory in the path must be non-writable by the world.
114A frequently voiced gripe is that you can get this message even
115if the pathname to an executable is fully qualified. But Perl can't
116know that the executable in question isn't going to execute some other
117program depending on the PATH.
118
119It's also possible to get into trouble with other operations that don't
120care whether they use tainted values. Make judicious use of the file
121tests in dealing with any user-supplied filenames. When possible, do
122opens and such after setting C<$E<gt> = $E<lt>>. (Remember group IDs,
123too!) Perl doesn't prevent you from opening tainted filenames for reading,
124so be careful what you print out. The tainting mechanism is intended to
125prevent stupid mistakes, not to remove the need for thought.
126
cb1a09d0
AD
127This gives us a reasonably safe way to open a file or pipe: just reset the
128id set to the original IDs. Here's a way to do backticks reasonably
129safely. Notice how the exec() is not called with a string that the shell
130could expand. By the time we get to the exec(), tainting is turned off,
131however, so be careful what you call and what you pass it.
132
133 die unless defined $pid = open(KID, "-|");
134 if ($pid) { # parent
135 while (<KID>) {
136 # do something
137 }
138 close KID;
139 } else {
140 $> = $<;
141 $) = $(; # BUG: initgroups() not called
142 exec 'program', 'arg1', 'arg2';
143 die "can't exec program: $!";
144 }
145
146For those even more concerned about safety, see the I<Safe> and I<Safe CGI>
147modules at a CPAN site near you. See L<perlmod> for a list of CPAN sites.