cvs: phpdoc-he /features safe-mode.xml

Index: phpdoc-he/features/safe-mode.xml
+++ phpdoc-he/features/safe-mode.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- EN-Revision: 0 Maintainer: doron Status: translation -->

 <chapter id="features.safe-mode">
  <title>Safe Mode</title>

  <para>
   The PHP safe mode is an attempt to solve the shared-server security
   problem. It is architecturally incorrect to try to solve this
   problem at the PHP level, but since the alternatives at the web
   server and OS levels aren't very realistic, many people,
   especially ISP's, use safe mode for now. 
  </para>
  <para>
   <table>
    <title>Configuration directives controlling safe mode are:</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Directive</entry>
       <entry>Default value</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>
        <link linkend="ini.safe-mode">safe_mode</link>
       </entry>
       <entry><literal>Off</literal></entry>
      </row>
      <row>
       <entry>
        <link linkend="ini.safe-mode-gid">safe_mode_gid</link>
       </entry>
       <entry><literal>0</literal></entry>
      </row>
      <row>
       <entry>
        <link linkend="ini.safe-mode-include-dir">safe_mode_include_dir</link>
       </entry>
       <entry><literal>""</literal></entry>
      </row>
      <row>
       <entry>
        <link linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>
       </entry>
       <entry><literal>1</literal></entry>
      </row>
      <row>
       <entry>
        <link linkend="ini.open-basedir">open_basedir</link>
       </entry>
       <entry><literal>""</literal></entry>
      </row>
      <row>
       <entry>
        <literal>safe_mode_allowed_env_vars</literal>
       </entry>
       <entry><literal>PHP_</literal></entry>
      </row>
      <row>
       <entry>
        <literal>safe_mode_protected_env_vars</literal>
       </entry>
       <entry><literal>LD_LIBRARY_PATH</literal></entry>
      </row>
      <row>
       <entry>
        <literal>disable_functions</literal>
       </entry>
       <entry><literal>""</literal></entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <para>
   When <link linkend="ini.safe-mode">safe_mode</link> is on, PHP checks to see 
   if the owner of the current script matches the owner of the file to be 
   operated on by a file function. For example: 
   <programlisting role="ls">
<![CDATA[
-rw-rw-r--    1 rasmus   rasmus       33 Jul  1 19:20 script.php 
-rw-r--r--    1 root     root       1116 May 26 18:01 /etc/passwd 
]]>
   </programlisting>
   Running this script.php 
   <programlisting role="php">
<![CDATA[
<?php
 readfile('/etc/passwd'); 
?>
]]>
   </programlisting>
   results in this error when safe mode is enabled: 
   <screen>
<![CDATA[
Warning: SAFE MODE Restriction in effect. The script whose uid is 500 is not 
allowed to access /etc/passwd owned by uid 0 in /docroot/script.php on line 2
]]>
   </screen>
  </para>
  <para>
   However, there may be environments where a strict <literal>UID</literal>
   check is not appropriate and a relaxed <literal>GID</literal> check is
   sufficient.  This is supported by means of the <link
   linkend="ini.safe-mode-gid">safe_mode_gid</link> switch. Setting it to
   <literal>On</literal> performs the relaxed <literal>GID</literal> checking,
   setting it to <literal>Off</literal> (the default) performs
   <literal>UID</literal> checking.
  </para>
  <para>
   If instead of <link linkend="ini.safe-mode">safe_mode</link>, you set an 
   <link linkend="ini.open-basedir">open_basedir</link> directory then all
   file operations will be limited to files under the specified directory
   For example (Apache httpd.conf example): 
   <programlisting role="ini">
<![CDATA[
<Directory /docroot>
  php_admin_value open_basedir /docroot 
</Directory>
]]>
   </programlisting>
   If you run the same script.php with this
   <link linkend="ini.open-basedir">open_basedir</link> setting
   then this is the result: 
   <screen>
<![CDATA[
Warning: open_basedir restriction in effect. File is in wrong directory in 
/docroot/script.php on line 2 
]]>
   </screen>
  </para>
  <para>
   You can also disable individual functions. Note that the disable_functions 
   directive can not be used outside of the &php.ini; file which means that
   you cannot disable functions on a per-virtualhost or per-directory basis
   in your httpd.conf file.
   If we add this to our &php.ini; file: 
   <programlisting role="ini">
<![CDATA[
disable_functions readfile,system  
]]>
   </programlisting>
   Then we get this output: 
   <screen>
<![CDATA[
Warning: readfile() has been disabled for security reasons in 
/docroot/script.php on line 2 
]]>
   </screen>
  </para>

  <sect1 id="features.safe-mode.functions">
   <title>Functions restricted/disabled by safe mode</title>
   <para>
    This is a still probably incomplete and possibly incorrect listing
    of the functions limited by 
    <link linkend="features.safe-mode">safe mode</link>.
    <!-- TODO: add &note.sm.*; to the functions mentioned here.
    That entity should link to this section -->
    <table>
     <title>Safe mode limited functions</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>Function</entry>
        <entry>Limitations</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry><function>dbmopen</function></entry>
        <entry>&sm.uidcheck;</entry>
       </row>
       <row>
        <entry><function>dbase_open</function></entry>
        <entry>&sm.uidcheck;</entry>
       </row>
       <row>
        <entry><function>filepro</function></entry>
        <entry>&sm.uidcheck;</entry>
       </row>
       <row>
        <entry><function>filepro_rowcount</function></entry>
        <entry>&sm.uidcheck;</entry>
       </row>
       <row>
        <entry><function>filepro_retrieve</function></entry>
        <entry>&sm.uidcheck;</entry>
       </row>
       <row>
        <entry><function>ifx_*</function></entry>
        <entry>sql_safe_mode restrictions, (!= safe mode)</entry>
        <!-- TODO: more info on sql-safe-mode -->
       </row>
       <row>
        <entry><function>ingres_*</function></entry>
        <entry>sql_safe_mode restrictions, (!= safe mode)</entry>
        <!-- TODO: more info on sql-safe-mode -->
       </row>
       <row>
        <entry><function>mysql_*</function></entry>
        <entry>sql_safe_mode restrictions, (!= safe mode)</entry>
        <!-- TODO: more info on sql-safe-mode -->
       </row>
       <row>
        <entry><function>pg_loimport</function></entry>
        <entry>&sm.uidcheck;</entry>
        <!-- source TODO: there is no PHP-warning for that safe-mode-restriction -->
       </row>
       <row>
        <entry><function>posix_mkfifo</function></entry>
        <entry>&sm.uidcheck.dir;</entry>
       </row>
       <row>
        <entry><function>putenv</function></entry>
        <entry>Obeys the safe_mode_protected_env_vars and 
        safe_mode_allowed_env_vars ini-directives. See also the documentation
        on <function>putenv</function></entry>
        <!-- TODO: document those directives in chapters/config.xml -->
       </row>
       <row>
        <entry><function>move_uploaded_file</function></entry>
        <entry>&sm.uidcheck; <!-- TODO: check this --></entry>
       </row>

       <!-- TODO: from here on, add warning to the function itself -->

       <row>
        <entry><function>chdir</function></entry>
        <entry>&sm.uidcheck.dir;</entry>
       </row>
       <row>
        <entry><function>dl</function></entry>
        <entry>&sm.disabled;</entry>
       </row>
       <row>
        <entry><link linkend="language.operators.execution">backtick operator</link></entry>
        <entry>&sm.disabled;</entry>
       </row>
       <row>
        <entry><function>shell_exec</function> (functional equivalent 
        of backticks)</entry>
        <entry>&sm.disabled;</entry>
       </row>
       <row>
        <entry><function>exec</function></entry>
        <entry>You can only execute executables within the <link 
        linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>.
        For practical reasons it's currently not allowed to have
        <literal>..</literal> components in the path to the executable.</entry>
       </row>
       <row>
        <entry><function>system</function></entry>
        <entry>You can only execute executables within the <link 
        linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>.
        For practical reasons it's currently not allowed to have
        <literal>..</literal> components in the path to the executable.</entry>
       </row>
       <row>
        <entry><function>passthru</function></entry>
        <entry>You can only execute executables within the <link 
        linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>.
        For practical reasons it's currently not allowed to have
        <literal>..</literal> components in the path to the executable.</entry>
       </row>
       <row>
        <entry><function>popen</function></entry>
        <entry>You can only execute executables within the <link 
        linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>.
        For practical reasons it's currently not allowed to have
        <literal>..</literal> components in the path to the executable.</entry>
        <!-- TODO: not sure. popen uses a completely different implementation
        Don't know why, don't know whether it's behaving the same -->
       </row>
       <row>
        <entry><function>mkdir</function></entry>
        <entry>&sm.uidcheck.dir;</entry>
       </row>
       <row>
        <entry><function>rmdir</function></entry>
        <entry>&sm.uidcheck;</entry>
       </row>
       <row>
        <entry><function>rename</function></entry>
        <entry>&sm.uidcheck; &sm.uidcheck.dir;<!-- on the old name only, it seems. Is rename preventing moving files? --></entry>
       </row>
       <row>
        <entry><function>unlink</function></entry>
        <entry>&sm.uidcheck; &sm.uidcheck.dir;</entry>
       </row>
       <row>
        <entry><function>copy</function></entry>
        <entry>&sm.uidcheck; &sm.uidcheck.dir; (on 
        <parameter>source</parameter> and 
        <parameter>target</parameter>) </entry>
       </row>
       <row>
        <entry><function>chgrp</function></entry>
        <entry>&sm.uidcheck;</entry>
       </row>
       <row>
        <entry><function>chown</function></entry>
        <entry>&sm.uidcheck;</entry>
       </row>
       <row>
        <entry><function>chmod</function></entry>
        <entry>&sm.uidcheck; In addition, you cannot  
        set the SUID, SGID and sticky bits</entry>
       </row>
       <row>
        <entry><function>touch</function></entry>
        <entry>&sm.uidcheck; &sm.uidcheck.dir;</entry>
       </row>
       <row>
        <entry><function>symlink</function></entry>
        <entry>&sm.uidcheck; &sm.uidcheck.dir; (note: only the target is 
        checked)</entry>
       </row>
       <row>
        <entry><function>link</function></entry>
        <entry>&sm.uidcheck; &sm.uidcheck.dir; (note: only the target is 
        checked)</entry>
       </row>
       <row>
        <entry><function>getallheaders</function></entry>
        <entry>In safe mode, headers beginning with 'authorization' 
        (case-insensitive)
        will not be returned. Warning: this is broken with the aol-server
        implementation of <function>getallheaders</function>!</entry>
       </row>
        <row>
        <entry><function>header</function></entry>
        <entry>In safe mode, the uid of the script is added to the
        <literal>realm</literal> part of the
        <literal>WWW-Authenticate</literal> header if you set this
        header (used for HTTP Authentication).</entry>
       </row>
       <row>
        <entry>
         <function>highlight_file</function>,
         <function>show_source</function>
        </entry>
        <entry>
         &sm.uidcheck; &sm.uidcheck.dir; (note: only affected since PHP 4.2.1)
        </entry>
       </row>
       <row>
        <entry>
         <function>parse_ini_file</function>
        </entry>
        <entry>
         &sm.uidcheck; &sm.uidcheck.dir; (note: only affected since PHP 4.2.1)
        </entry>
       </row>
       <row>
        <entry>Any function that uses 
         <filename>php4/main/fopen_wrappers.c</filename>
        </entry>
        <entry>??</entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>
  </sect1>

 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->