1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297028 $ -->
<refentry xml:id="function.mysql-real-escape-string" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>mysql_real_escape_string</refname>
<refpurpose>Escapes special characters in a string for use in a SQL statement</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>mysql_real_escape_string</methodname>
<methodparam><type>string</type><parameter>unescaped_string</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>link_identifier</parameter></methodparam>
</methodsynopsis>
<para>
Escapes special characters in the <parameter>unescaped_string</parameter>,
taking into account the current character set of the connection so that it
is safe to place it in a <function>mysql_query</function>. If binary data
is to be inserted, this function must be used.
</para>
<para>
<function>mysql_real_escape_string</function> calls MySQL's library function
mysql_real_escape_string, which prepends backslashes to the following characters:
<literal>\x00</literal>, <literal>\n</literal>,
<literal>\r</literal>, <literal>\</literal>, <literal>'</literal>,
<literal>"</literal> and <literal>\x1a</literal>.
</para>
<para>
This function must always (with few exceptions) be used to make data
safe before sending a query to MySQL.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>unescaped_string</parameter></term>
<listitem>
<para>
The string that is to be escaped.
</para>
</listitem>
</varlistentry>
&mysql.linkid.description;
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the escaped string, or &false; on error.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Simple <function>mysql_real_escape_string</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
// Connect
$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
OR die(mysql_error());
// Query
$query = sprintf("SELECT * FROM users WHERE user='%s' AND password='%s'",
mysql_real_escape_string($user),
mysql_real_escape_string($password));
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>An example SQL Injection Attack</title>
<programlisting role="php">
<![CDATA[
<?php
// Query database to check if there are any matching users
$query = "SELECT * FROM users WHERE user='{$_POST['username']}' AND password='{$_POST['password']}'";
mysql_query($query);
// We didn't check $_POST['password'], it could be anything the user wanted! For example:
$_POST['username'] = 'aidan';
$_POST['password'] = "' OR ''='";
// This means the query sent to MySQL would be:
echo $query;
?>
]]>
</programlisting>
<para>
The query sent to MySQL:
</para>
<screen>
<![CDATA[
SELECT * FROM users WHERE user='aidan' AND password='' OR ''=''
]]>
</screen>
<para>
This would allow anyone to log in without a valid password.
</para>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
A MySQL connection is required before using
<function>mysql_real_escape_string</function> otherwise an error of
level <constant>E_WARNING</constant> is generated, and &false; is
returned. If <parameter>link_identifier</parameter> isn't defined, the
last MySQL connection is used.
</para>
</note>
<note>
<para>
If <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link> is enabled,
first apply <function>stripslashes</function> to the data. Using this function
on data which has already been escaped will escape the data twice.
</para>
</note>
<note>
<para>
If this function is not used to escape data, the query is vulnerable to
<link linkend="security.database.sql-injection">SQL Injection Attacks</link>.
</para>
</note>
<note>
<simpara>
<function>mysql_real_escape_string</function> does not escape
<literal>%</literal> and <literal>_</literal>. These are wildcards in
MySQL if combined with <literal>LIKE</literal>, <literal>GRANT</literal>,
or <literal>REVOKE</literal>.
</simpara>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>mysql_client_encoding</function></member>
<member><function>addslashes</function></member>
<member><function>stripslashes</function></member>
<member>The <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link> directive</member>
<member>The <link linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link> directive</member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- 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:"~/.phpdoc/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
-->
|
