cvs: phpdoc /en/security magicquotes.xml

philip Tue Sep 7 13:20:21 2004 EDT Modified files: /phpdoc/en/security magicquotes.xml Log: Rewrote and expanded text, fixed build, implemented simplesect instead of sect1 (all this belongs one one page), and used itemized lists.

http://cvs.php.net/diff.php/phpdoc/en/security/magicquotes.xml?r1=1.2&r2=1.3&ty=u Index: phpdoc/en/security/magicquotes.xml diff -u phpdoc/en/security/magicquotes.xml:1.2 phpdoc/en/security/magicquotes.xml:1.3 --- phpdoc/en/security/magicquotes.xml:1.2 Tue Sep 7 11:11:46 2004 +++ phpdoc/en/security/magicquotes.xml Tue Sep 7 13:20:21 2004 @@ -1,80 +1,158 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.2 $ --> +<!-- $Revision: 1.3 $ --> <chapter id="security.magicquotes"> <title>Magic Quotes</title> <para> - Magic Quotes is a process which automatically escapes all incoming data to a PHP script. + Magic Quotes is a process that automagically escapes incoming data to the + PHP script. It's preferred to code with magic quotes off and to instead + escape the data at runtime, as needed. </para> - <warning> - <para> - You should NOT rely on this feature. It is strongly prefered to turn this off, and deal with - user input properly. - </para> - </warning> - <sect1 id="security.magicquotes.what"> + <simplesect id="security.magicquotes.what"> <title>What are Magic Quotes</title> <para> - When on, all <literal>'</literal> (single-quote), <literal>"</literal> (double quote), - <literal>\</literal> (backslash) and <literal>NULL</literal> characters are escaped with a - backslash automatically. - </para> - <para> - Magic Quotes has 3 Modes of operation. - </para> - <para> - <link linkend="ini.magic_quotes_gpc">magic_quotes_gpc</link>. This affects GET, POST and COOKIE - data. This information is populated by the end users of the script. - </para> - <para> - <link linkend="ini.magic_quotes_runtime">magic_quotes_runtime</link>. If enabled, most functions - that return data from any sort of external source including databases and text files will have - quotes escaped with a backslash. - </para> - <para> - <link linkend="ini.magic_quotes_sybase">magic_quotes_sybase</link>. If enabled, a single-quote - is escaped with a single-quote instead of a backslash. - </para> - <para> - This setting will completely override magic_quotes_gpc. Having both directives enabled means - only single quotes are escaped as <literal>''</literal>. Double quotes, backslashes and NULL's - will remain untouched and unescaped. - </para> - </sect1> + When on, all <literal>'</literal> (single-quote), <literal>"</literal> + (double quote), <literal>\</literal> (backslash) and <literal>NULL</literal> + characters are escaped with a backslash automatically. This is identical + to what <function>addslashes</function> does. + </para> + <para> + There are three magic quote directives: + </para> + <itemizedlist> + <listitem> + <simpara> + <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link> + </simpara> + <simpara> + Affects HTTP Request data (GET, POST, and COOKIE). Cannot be set at + runtime, and defaults to <emphasis>on</emphasis> in PHP. + </simpara> + <simpara> + See also <function>get_magic_quotes_gpc</function>. + </simpara> + </listitem> + <listitem> + <simpara> + <link linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link> + </simpara> + <simpara> + If enabled, most functions that return data from an external source, + including databases and text files, will have quotes escaped with a + backslash. Can be set at runtime, and defaults to <emphasis>on</emphasis> + in PHP. + </simpara> + <simpara> + See also <function>set_magic_quotes_runtime</function> and + <function>get_magic_quotes_runtime</function>. + </simpara> + </listitem> + <listitem> + <simpara> + <link linkend="ini.magic-quotes-sybase">magic_quotes_sybase</link> + </simpara> + <simpara> + If enabled, a single-quote is escaped with a single-quote instead of a + backslash. If on, it completely overrides + <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link>. Having + both directives enabled means only single quotes are escaped as + <literal>''</literal>. Double quotes, backslashes and NULL's will + remain untouched and unescaped. + </simpara> + <simpara> + See also <function>ini_get</function> for retrieving its value. + </simpara> + </listitem> + </itemizedlist> + </simplesect> - <sect1 id="security.magicquotes.why"> + <simplesect id="security.magicquotes.why"> <title>Why use Magic Quotes</title> - <para> - Magic-quotes were implemented in PHP to reduce code written by beginners from being dangerous. - </para> - <para> - Magic Quotes are enabled by default. - </para> - <para> - If you disable magic quotes, you must be very careful to protect yourself from - <link linkend="security.database.sql-injection">SQL Injection Attacks</link>. - </para> - </sect1> + <itemizedlist> + <listitem> + <simpara> + Useful for beginners + </simpara> + <simpara> + Magic quotes are implemented in PHP to help code written by beginners + from being dangerous. Although + <link linkend="security.database.sql-injection">SQL Injection</link> + is still possible with magic quotes on, the risk is reduced. + </simpara> + </listitem> + <listitem> + <simpara> + Convenience + </simpara> + <simpara> + For inserting data into a database, magic quotes essentially runs + <function>addslashes</function> on all Get, Post, and Cookie data, + and does so automagically. + </simpara> + </listitem> + </itemizedlist> + </simplesect> - <sect1 id="security.magicquotes.whynot"> + <simplesect id="security.magicquotes.whynot"> <title>Why not to use Magic Quotes</title> - <para> - Portability, performance, etc. - </para> - </sect1> + <itemizedlist> + <listitem> + <simpara> + Portability + </simpara> + <simpara> + Assuming it to be on, or off, affects portability. Use + <function>get_magic_quotes_gpc</function> to check for this, and code + accordingly. + </simpara> + </listitem> + <listitem> + <simpara> + Performance + </simpara> + <simpara> + Because not every piece of escaped data is inserted into a + database, there is a performance loss for escaping all this data. + Simply calling on the escaping functions (like + <function>addslashes</function>) at runtime is more efficient. + </simpara> + <simpara> + Although <filename>php.ini-dist</filename> enables these directives + by default, <filename>php.ini-recommended</filename> disables it. + This recommendation is mainly due to performance reasons. + </simpara> + </listitem> + <listitem> + <simpara> + Inconvenience + </simpara> + <simpara> + Because not all data needs escaping, it's often annoying to see escaped + data where it shouldn't be. For example, emailing from a form, and + seeing a bunch of \' within the email. To fix, this may require + excessive use of <function>stripslashes</function>. + </simpara> + </listitem> + </itemizedlist> + </simplesect> - <sect1 id="security.magicquotes.disabling"> + <simplesect id="security.magicquotes.disabling"> <title>Disabling Magic Quotes</title> <para> - Optimally, Magic Quotes should be disabled server side. + The <link linkend="ini.magic_quotes_gpc">magic_quotes_gpc</link> + directive may only be disabled at the system level, and not at + runtime. In otherwords, use of <function>ini_set</function> is not + an option. </para> <para> <example> <title>Disabling magic quotes server side</title> <para> - Set the value of magic_quotes_gpc and magic_quotes_runtime to Off in the - php.ini. + An example that sets the value of these directives to + <literal>Off</literal> in &php.ini;. For additional details, read the + manual section titled <link linkend="configuration.changes">How to + change configuration settings</link>. </para> <screen> <![CDATA[ @@ -92,21 +170,22 @@ ]]> </screen> <para> - If you do not have access to the server config, you can put this - line in a ".htaccess" file. This will disable magic_quotes. + If access to the server configuration is unavilable, use of + <filename>.htaccess</filename> is also an option. For example: </para> <screen> <![CDATA[ -php_value magic_quotes_gpc Off +php_flag magic_quotes_gpc Off ]]> </screen> </example> </para> <para> - In the interests of writing portable code (code that works - in any environment), or, if you do not have access to change - php.ini, you may wish to disable the effects of magic quotes - on a per-script basis. + In the interest of writing portable code (code that works in any + environment), like if setting at the server level is not possible, + here's an example to disable <link linkend="ini.magic-quotes-gpc"> + magic_quotes_gpc</link> at runtime. This method is inefficient so + it's preferred to instead set the appropriate directives elsewhere. </para> <para> <example> @@ -133,8 +212,7 @@ </programlisting> </example> </para> - - </sect1> + </simplesect> </chapter>