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>
