Hello PHP EN Documentation team, There are contributions within the online editor queue for this language. Please review, then commit or delete these patches.
Patches for review : ----------------------- Modified: en/reference/filter/functions/filter-var.xml By: Dejan Marjanovic on 2012-12-17 03:54:03 =================================================================== --- en/reference/filter/functions/filter-var.xml +++ en/reference/filter/functions/filter-var.xml @@ -14,7 +14,7 @@ <methodparam choice="opt"><type>int</type><parameter>filter</parameter><initializer>FILTER_DEFAULT</initializer></methodparam> <methodparam choice="opt"><type>mixed</type><parameter>options</parameter></methodparam> </methodsynopsis> - + </refsect1> <refsect1 role="parameters"> &reftitle.parameters; @@ -49,7 +49,7 @@ </para> <para> <programlisting role="php"> - <![CDATA[ +<![CDATA[ <?php // for filters that accept options, use this format $options = array( @@ -99,7 +99,7 @@ Returns the filtered data, or &false; if the filter fails. </para> </refsect1> - + <refsect1 role="examples"> &reftitle.examples; <para> @@ -122,8 +122,28 @@ </screen> </example> </para> + <para> + <example> + <title>Validate email using syntax check and host MX record check</title> + <programlisting role="php"> +<![CDATA[ +<?php +$email = 'de...@php.net'; +if (filter_var($email, FILTER_VALIDATE_EMAIL) !== false && checkdnsrr(explode('@', $email)[1])) { + echo 'Email and host are valid.'; +} else { + echo 'Email or host is not valid.'; +} +?> +]]> + </programlisting> + <para> + Note: Even if the email is syntactically valid and MX record exists, only way to check authenticity is to send confirmation mail. + </para> + </example> + </para> </refsect1> - + <refsect1 role="seealso"> &reftitle.seealso; <para> @@ -136,7 +156,7 @@ </simplelist> </para> </refsect1> - + </refentry> <!-- Keep this comment at the end of the file => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=43983 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=43983 ------------------------------------------------------------------ Modified: en/reference/ctype/functions/ctype-digit.xml By: Dejan Marjanovic on 2012-12-17 05:54:11 =================================================================== --- en/reference/ctype/functions/ctype-digit.xml +++ en/reference/ctype/functions/ctype-digit.xml @@ -6,7 +6,7 @@ <refname>ctype_digit</refname> <refpurpose>Check for numeric character(s)</refpurpose> </refnamediv> - + <refsect1 role="description"> &reftitle.description; <methodsynopsis> @@ -18,7 +18,7 @@ <parameter>text</parameter>, are numerical. </para> </refsect1> - + <refsect1 role="parameters"> &reftitle.parameters; <para> @@ -34,15 +34,18 @@ </variablelist> </para> </refsect1> - + <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> Returns &true; if every character in the string <parameter>text</parameter> is a decimal digit, &false; otherwise. </para> + <para> + Returns &true; if integer <parameter>text</parameter> is in range 48-57 (ASCII symbols for 0-9). + </para> </refsect1> - + <refsect1 role="changelog"> &reftitle.changelog; <para> @@ -67,7 +70,7 @@ </informaltable> </para> </refsect1> - + <refsect1 role="examples"> &reftitle.examples; <para> @@ -117,8 +120,33 @@ </programlisting> </example> </para> - </refsect1> + <para> + <example> + <title>A <function>ctype_digit</function> gotcha</title> + <programlisting role="php"> +<![CDATA[ +<?php + +/* Returns true as expected */ +ctype_digit('49'); # true + +/** + * Returns true even if false is expected. + * As noted, -128 to 255 integers are casted to ASCII char, not string. + * ASCII 49 is character 1 (number one) which is a digit. + */ +ctype_digit(49); # true +/* If you are not sure input is a string, always cast it to be safe. */ +ctype_digit( (string) 49); # true + +?> +]]> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="notes"> &reftitle.notes; <note> @@ -131,7 +159,7 @@ </note> ¬e.ctype.parameter.integer; </refsect1> - + <refsect1 role="seealso"> &reftitle.seealso; <para> => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=43985 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=43985 ------------------------------------------------------------------ Modified: en/security/database.xml By: Dejan Marjanovic on 2012-12-17 06:01:21 =================================================================== --- en/security/database.xml +++ en/security/database.xml @@ -1,121 +1,121 @@ <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 325889 $ --> <!-- splitted from ./index.xml, last change in rev 1.66 --> - <chapter xml:id="security.database" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> - <title>Database Security</title> - - <simpara> - Nowadays, databases are cardinal components of any web based application by - enabling websites to provide varying dynamic content. Since very sensitive - or secret information can be stored in a database, you should strongly - consider protecting your databases. - </simpara> - <simpara> - To retrieve or to store any information you need to connect to the database, - send a legitimate query, fetch the result, and close the connection. - Nowadays, the commonly used query language in this interaction is the - Structured Query Language (SQL). See how an attacker can <link - linkend="security.database.sql-injection">tamper with an SQL query</link>. - </simpara> - <simpara> - As you can surmise, <acronym>PHP</acronym> cannot protect your database by itself. The - following sections aim to be an introduction into the very basics of how to - access and manipulate databases within <acronym>PHP</acronym> scripts. - </simpara> - <simpara> - Keep in mind this simple rule: defense in depth. The more places you - take action to increase the protection of your database, the less - probability of an attacker succeeding in exposing or abusing any stored - information. Good design of the database schema and the application - deals with your greatest fears. - </simpara> - - <sect1 xml:id="security.database.design"> - <title>Designing Databases</title> - <simpara> - The first step is always to create the database, unless you want to use - one from a third party. When a database is created, it is - assigned to an owner, who executed the creation statement. Usually, only - the owner (or a superuser) can do anything with the objects in that - database, and in order to allow other users to use it, privileges must be - granted. - </simpara> - <simpara> - Applications should never connect to the database as its owner or a - superuser, because these users can execute any query at will, for - example, modifying the schema (e.g. dropping tables) or deleting its - entire content. - </simpara> - <simpara> - You may create different database users for every aspect of your - application with very limited rights to database objects. The most - required privileges should be granted only, and avoid that the same user - can interact with the database in different use cases. This means that if - intruders gain access to your database using your applications credentials, - they can only effect as many changes as your application can. - </simpara> - <simpara> - You are encouraged not to implement all the business logic in the web - application (i.e. your script), instead do it in the database schema - using views, triggers or rules. If the system evolves, new ports will be - intended to open to the database, and you have to re-implement the logic - in each separate database client. Over and above, triggers can be used - to transparently and automatically handle fields, which often provides - insight when debugging problems with your application or tracing back - transactions. - </simpara> - </sect1> - - <sect1 xml:id="security.database.connection"> - <title>Connecting to Database</title> - <simpara> - You may want to establish the connections over SSL to encrypt - client/server communications for increased security, or you can use ssh - to encrypt the network connection between clients and the database server. - If either of these is used, then monitoring your traffic and gaining - information about your database will be difficult for a would-be attacker. - </simpara> - <!--simpara> +<chapter xml:id="security.database" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>Database Security</title> + + <simpara> + Nowadays, databases are cardinal components of any web based application by + enabling websites to provide varying dynamic content. Since very sensitive + or secret information can be stored in a database, you should strongly + consider protecting your databases. + </simpara> + <simpara> + To retrieve or to store any information you need to connect to the database, + send a legitimate query, fetch the result, and close the connection. + Nowadays, the commonly used query language in this interaction is the + Structured Query Language (SQL). See how an attacker can <link + linkend="security.database.sql-injection">tamper with an SQL query</link>. + </simpara> + <simpara> + As you can surmise, <acronym>PHP</acronym> cannot protect your database by itself. The + following sections aim to be an introduction into the very basics of how to + access and manipulate databases within <acronym>PHP</acronym> scripts. + </simpara> + <simpara> + Keep in mind this simple rule: defense in depth. The more places you + take action to increase the protection of your database, the less + probability of an attacker succeeding in exposing or abusing any stored + information. Good design of the database schema and the application + deals with your greatest fears. + </simpara> + + <sect1 xml:id="security.database.design"> + <title>Designing Databases</title> + <simpara> + The first step is always to create the database, unless you want to use + one from a third party. When a database is created, it is + assigned to an owner, who executed the creation statement. Usually, only + the owner (or a superuser) can do anything with the objects in that + database, and in order to allow other users to use it, privileges must be + granted. + </simpara> + <simpara> + Applications should never connect to the database as its owner or a + superuser, because these users can execute any query at will, for + example, modifying the schema (e.g. dropping tables) or deleting its + entire content. + </simpara> + <simpara> + You may create different database users for every aspect of your + application with very limited rights to database objects. The most + required privileges should be granted only, and avoid that the same user + can interact with the database in different use cases. This means that if + intruders gain access to your database using your applications credentials, + they can only effect as many changes as your application can. + </simpara> + <simpara> + You are encouraged not to implement all the business logic in the web + application (i.e. your script), instead do it in the database schema + using views, triggers or rules. If the system evolves, new ports will be + intended to open to the database, and you have to re-implement the logic + in each separate database client. Over and above, triggers can be used + to transparently and automatically handle fields, which often provides + insight when debugging problems with your application or tracing back + transactions. + </simpara> + </sect1> + + <sect1 xml:id="security.database.connection"> + <title>Connecting to Database</title> + <simpara> + You may want to establish the connections over SSL to encrypt + client/server communications for increased security, or you can use ssh + to encrypt the network connection between clients and the database server. + If either of these is used, then monitoring your traffic and gaining + information about your database will be difficult for a would-be attacker. + </simpara> + <!--simpara> If your database server has native SSL support, consider using <link linkend="ref.openssl">OpenSSL functions</link> in communication between <acronym>PHP</acronym> and database via SSL. </simpara--> - </sect1> - - <sect1 xml:id="security.database.storage"> - <title>Encrypted Storage Model</title> - <simpara> - SSL/SSH protects data travelling from the client to the server: SSL/SSH - does not protect persistent data stored in a database. SSL is an - on-the-wire protocol. - </simpara> - <simpara> - Once an attacker gains access to your database directly (bypassing the - webserver), stored sensitive data may be exposed or misused, unless - the information is protected by the database itself. Encrypting the data - is a good way to mitigate this threat, but very few databases offer this - type of data encryption. - </simpara> - <simpara> - The easiest way to work around this problem is to first create your own - encryption package, and then use it from within your <acronym>PHP</acronym> scripts. <acronym>PHP</acronym> - can assist you in this with several extensions, such as <link - linkend="ref.mcrypt">Mcrypt</link> and <link - linkend="ref.mhash">Mhash</link>, covering a wide variety of encryption - algorithms. The script encrypts the data before inserting it into the database, and decrypts - it when retrieving. See the references for further examples of how - encryption works. - </simpara> - <simpara> - In the case of truly hidden data, if its raw representation is not needed - (i.e. will not be displayed), hashing may also be taken into consideration. - The well-known example for hashing is storing the cryptographic hash of a - password in a database, instead of the password itself. See also - <function>crypt</function>. - </simpara> - <example> - <title>Using hashed password field</title> - <programlisting role="php"> + </sect1> + + <sect1 xml:id="security.database.storage"> + <title>Encrypted Storage Model</title> + <simpara> + SSL/SSH protects data travelling from the client to the server: SSL/SSH + does not protect persistent data stored in a database. SSL is an + on-the-wire protocol. + </simpara> + <simpara> + Once an attacker gains access to your database directly (bypassing the + webserver), stored sensitive data may be exposed or misused, unless + the information is protected by the database itself. Encrypting the data + is a good way to mitigate this threat, but very few databases offer this + type of data encryption. + </simpara> + <simpara> + The easiest way to work around this problem is to first create your own + encryption package, and then use it from within your <acronym>PHP</acronym> scripts. <acronym>PHP</acronym> + can assist you in this with several extensions, such as <link + linkend="ref.mcrypt">Mcrypt</link> and <link + linkend="ref.mhash">Mhash</link>, covering a wide variety of encryption + algorithms. The script encrypts the data before inserting it into the database, and decrypts + it when retrieving. See the references for further examples of how + encryption works. + </simpara> + <simpara> + In the case of truly hidden data, if its raw representation is not needed + (i.e. will not be displayed), hashing may also be taken into consideration. + The well-known example for hashing is storing the cryptographic hash of a + password in a database, instead of the password itself. See also + <function>crypt</function>. + </simpara> + <example> + <title>Using hashed password field</title> + <programlisting role="php"> <![CDATA[ <?php @@ -142,7 +142,7 @@ </programlisting> </example> </sect1> - + <sect1 xml:id="security.database.sql-injection"> <title>SQL Injection</title> <simpara> @@ -181,13 +181,13 @@ ]]> </programlisting> </example> - Normal users click on the 'next', 'prev' links where the <varname>$offset</varname> - is encoded into the <acronym>URL</acronym>. The script expects that the incoming - <varname>$offset</varname> is a decimal number. However, what if someone tries to - break in by appending a <function>urlencode</function>'d form of the - following to the <acronym>URL</acronym> - <informalexample> - <programlisting role="sql"> + Normal users click on the 'next', 'prev' links where the <varname>$offset</varname> + is encoded into the <acronym>URL</acronym>. The script expects that the incoming + <varname>$offset</varname> is a decimal number. However, what if someone tries to + break in by appending a <function>urlencode</function>'d form of the + following to the <acronym>URL</acronym> + <informalexample> + <programlisting role="sql"> <![CDATA[ 0; insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd) @@ -195,11 +195,11 @@ from pg_shadow where usename='postgres'; -- ]]> - </programlisting> - </informalexample> - If it happened, then the script would present a superuser access to him. - Note that <literal>0;</literal> is to supply a valid offset to the - original query and to terminate it. + </programlisting> + </informalexample> + If it happened, then the script would present a superuser access to him. + Note that <literal>0;</literal> is to supply a valid offset to the + original query and to terminate it. </para> <note> <para> @@ -258,9 +258,9 @@ just simply brute forcing. There are not so many naming conventions for fields storing passwords or usernames. <example> - <title> - From resetting a password ... to gaining more privileges (any database server) - </title> + <title> + From resetting a password ... to gaining more privileges (any database server) + </title> <programlisting role="php"> <![CDATA[ <?php @@ -295,7 +295,7 @@ A frightening example how operating system level commands can be accessed on some database hosts. <example> - <title>Attacking the database hosts operating system (MSSQL Server)</title> + <title>Attacking the database hosts operating system (MSSQL Server)</title> <programlisting role="php"> <![CDATA[ <?php @@ -346,7 +346,7 @@ </mediaobject> Image courtesy of <link xlink:href="&url.xkcd;327">xkcd</link> </para> - + <sect2 xml:id="security.database.avoiding"> <title>Avoidance Techniques</title> <simpara> @@ -369,7 +369,7 @@ a hidden input field or a cookie. The first example shows that such a blameless query can cause disasters. </simpara> - + <itemizedlist> <listitem> <simpara> @@ -392,7 +392,7 @@ found in <link linkend="ref.var">Variable Functions</link> and in <link linkend="ref.ctype">Character Type Functions</link> (e.g. <function>is_numeric</function>, <function>ctype_digit</function> - respectively) and onwards to the + respectively), <function>filter_var</function>, and onwards to the <link linkend="ref.pcre">Perl compatible Regular Expressions</link> support. </simpara> @@ -400,22 +400,28 @@ <listitem> <para> If the application waits for numerical input, consider verifying data - with <function>ctype_digit</function>, or silently change its type - using <function>settype</function>, or use its numeric representation - by <function>sprintf</function>. + with <function>filter_var</function> (<varname>FILTER_VALIDATE_INT</varname>) + or <function>ctype_digit</function>, or silently change its type using + <function>settype</function>, or use its numeric representation by + <function>sprintf</function>. <example> <title>A more secure way to compose a query for paging</title> <programlisting role="php"> <![CDATA[ <?php -settype($offset, 'integer'); +/* Cast $offset value to integer */ +$offset = (int) $offset; $query = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;"; -// please note %d in the format string, using %s would be meaningless +/* Please note %d in the format string, using %s would be meaningless */ $query = sprintf("SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET %d;", $offset); +/* Emulate named parameters */ +$query = strtr("SELECT id, name FROM products ORDER BY name LIMIT :limit OFFSET :offset", + array(":limit" => (int) $offset, ":offset" => (int) $offset)); + ?> ]]> </programlisting> @@ -451,7 +457,7 @@ </simpara> </listitem> </itemizedlist> - + <simpara> Besides these, you benefit from logging queries either within your script or by the database itself, if it supports logging. Obviously, the logging is unable @@ -461,7 +467,7 @@ </simpara> </sect2> </sect1> - </chapter> +</chapter> <!-- Keep this comment at the end of the file Local variables: => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=43984 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=43984 ------------------------------------------------------------------ Modified: en/language/variables.xml By: Dejan Marjanovic on 2012-12-17 06:09:33 =================================================================== --- en/language/variables.xml +++ en/language/variables.xml @@ -853,7 +853,14 @@ // Available since PHP 4.1.0 echo $_POST['username']; - echo $_REQUEST['username']; + +// Make sure to check if request method is POST, +// $_REQUEST contains $_GET, $_POST, $_COOKIE, +// failing to do so, you may be a victim of +// Cross-Site Request Forgery (CSRF) + if($_SERVER['REQUEST_METHOD'] === 'POST') { + echo $_REQUEST['username']; + } import_request_variables('p', 'p_'); echo $p_username; => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=43986 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=43986 ------------------------------------------------------------------ Modified: en/reference/pdo/pdo/getavailabledrivers.xml By: Ian.J. Gough on 2012-12-17 20:22:18 =================================================================== --- en/reference/pdo/pdo/getavailabledrivers.xml +++ en/reference/pdo/pdo/getavailabledrivers.xml @@ -56,8 +56,41 @@ </screen> </example> </para> - </refsect1> + + + + + <para> + <example> + <title>A <function>PDO::getAvailableDrivers</function> foreach example</title> + <programlisting role="php"> +<![CDATA[ +<?php +foreach (PDO::getAvailableDrivers() as $driver) { + if ($driver == NULL) { + echo "No PDO drivers were found!"; + } else { + echo $driver."<br />"; + } +} +?> +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +mysql +sqlite + +Or if no drivers are found show message stating that fact. + +]]> + </screen> + </example> + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=43993 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=43993 ------------------------------------------------------------------ Modified: en/reference/openssl/constants.xml By: z z on 2012-12-21 06:55:42 =================================================================== --- en/reference/openssl/constants.xml +++ en/reference/openssl/constants.xml @@ -172,7 +172,24 @@ </simpara> </listitem> </varlistentry> + <varlistentry xml:id="constant.openssl-keytype-ec"> + <term> + <constant>OPENSSL_KEYTYPE_EC</constant> + (<type>integer</type>) + </term> + <listitem> + <simpara> + This constant is only available when PHP is compiled with OpenSSL 0.9.8+. + </simpara> + </listitem> + </varlistentry> </variablelist> + <note> + <para>This constant was added in 5.2.0.</para> + <para> + <constant>OPENSSL_KEYTYPE_EC</constant> + </para> + </note> </section> <section xml:id="openssl.pkcs7.flags"> @@ -377,7 +394,10 @@ </term> <listitem> <simpara> - + As of PHP 5.2.13 and PHP 5.3.2, this constant is only available + if PHP is compiled with MD2 support. This requires passing in the + -DHAVE_OPENSSL_MD2_H CFLAG when compiling PHP, and enable-md2 when + compiling OpenSSL 1.0.0+. </simpara> </listitem> </varlistentry> => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=44029 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=44029 ------------------------------------------------------------------ -- https://edit.php.net/ This email is send automatically by the Php Docbook Online Editor.