svn: /pear/peardoc/trunk/ en/package/http/http-request2/config.xml entities/global.ent
[email protected] (Alexey Borzov) Wed, 15 Jan 2014 08:44:25 +0000
| Newsgroups | php.pear.doc |
|---|---|
| Message-ID | <[email protected]> |
--55a12f2e30e92aa443a979be4e2d64096bd76539
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit
avb Wed, 15 Jan 2014 08:44:25 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=332624
Log:
Documented the new config option in 2.2.0 (from request #19515), documented the peer verification issues (bug #19351)
Bugs: http://pear.php.net/bugs/19515 (unknown)
http://pear.php.net/bugs/19351 (unknown)
Changed paths:
U pear/peardoc/trunk/en/package/http/http-request2/config.xml
U pear/peardoc/trunk/entities/global.ent
Modified: pear/peardoc/trunk/en/package/http/http-request2/config.xml
===================================================================
--- pear/peardoc/trunk/en/package/http/http-request2/config.xml 2014-01-15 08:36:35 UTC (rev 332623)
+++ pear/peardoc/trunk/en/package/http/http-request2/config.xml 2014-01-15 08:44:25 UTC (rev 332624)
@@ -86,6 +86,14 @@
<entry>&type.bool;</entry>
<entry>&false;</entry>
</row>
+ <row>
+ <entry><literal>local_ip</literal></entry>
+ <entry>Specifies the IP address that will be used for accessing the network, if the computer
+ running <classname>HTTP_Request2</classname> has more than one
+ (since <emphasis>2.2.0</emphasis>)</entry>
+ <entry>&type.string;</entry>
+ <entry>&null;</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -204,7 +212,13 @@
<row valign="top">
<entry><literal>ssl_verify_peer</literal></entry>
<entry>Whether to verify peer's SSL certificate. Note that this is on by default, to follow
- the behaviour of modern browsers and current cURL version.</entry>
+ the behaviour of modern browsers and current cURL version.
+ <note><simpara>
+ Peer verification <link linkend="package.http.http-request2.config.ssl">is likely to fail</link>
+ if you don't explicitly provide <literal>ssl_cafile</literal> and/or <literal>ssl_capath</literal>,
+ especially with <classname>Socket</classname> adapter.
+ </simpara></note>
+ </entry>
<entry>&type.bool;</entry>
<entry>&true;</entry>
</row>
@@ -218,7 +232,12 @@
<row valign="top">
<entry><literal>ssl_cafile</literal></entry>
<entry>Certificate Authority file to verify the peer with (use when
- <literal>ssl_verify_peer</literal> is &true;)</entry>
+ <literal>ssl_verify_peer</literal> is &true;)
+ <note><simpara>
+ You can use e.g. <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="&url.http_request2.caextract;">cURL's CA Extract tool</link> to get such a file.
+ </simpara></note>
+ </entry>
<entry>&type.string;</entry>
<entry>&null;</entry>
</row>
@@ -246,6 +265,7 @@
</para>
</refsection>
+
<refsection xml:id="package.http.http-request2.config.proxy">
<info><title>Proxy Configuration</title></info>
<para>
@@ -271,4 +291,51 @@
]]></programlisting>
</example>
</refsection>
+
+ <refsection xml:id="package.http.http-request2.config.ssl">
+ <info><title>SSL peer verification issues</title></info>
+ <para>
+ For SSL peer verification to work, OpenSSL library (used under the hood by both Curl and
+ Socket adapter) needs <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="&url.http_request2.ca;">certificate authority</link> files. However it does
+ not include any such files itself, expecting OS distributions compiling OpenSSL library
+ to provide proper default locations.
+ </para>
+ <para>
+ Unfortunately OpenSSL extension of PHP below version 5.6 <emphasis>does not</emphasis>
+ try to use the distribution-default values for CA file / CA path when explicit ones
+ are not provided. Curl extension, however, does use these defaults, so you can sometimes
+ be able to use <literal>'verify_peer'</literal> without setting <literal>'ssl_cafile'</literal>
+ for Curl adapter, but not for Socket one (see e.g. <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="&url.pear.bug;18480">bug #18480</link> and <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="&url.pear.bug;19351">bug #19351</link>).
+ </para>
+ <para>
+ For versions of PHP below 5.6 the only solution is to provide <literal>'ssl_cafile'</literal>
+ and / or <literal>'ssl_capath'</literal> for every request if using
+ <classname>Socket</classname> adapter. <classname>Curl</classname> adapter will or
+ will not be able to use the defaults depending on distribution, additionally you can set
+ <varname>curl.cainfo</varname> parameter in <filename>php.ini</filename> on PHP 5.3.7+
+ (it contains the default value for <constant>CURLOPT_CAINFO</constant> setting to which
+ <literal>'ssl_cafile'</literal> setting is mapped).
+ </para>
+ <para>
+ PHP version 5.6 will <emphasis>finally</emphasis> <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="&url.http_request2.rfc-verification;">enable peer verification by default</link>
+ for <literal>'ssl'</literal> stream wrapper, so it will also provide more possibilities for
+ using default values:
+ <itemizedlist>
+ <listitem><simpara>
+ PHP will use defaults compiled into the OpenSSL library by distribution.
+ </simpara></listitem>
+ <listitem><simpara>
+ <varname>openssl.cafile</varname> and <varname>openssl.capath</varname> settings in
+ <filename>php.ini</filename> will provide default values for <literal>'cafile'</literal>
+ and <literal>'capath'</literal> SSL stream context options (<literal>'ssl_cafile'</literal>
+ and <literal>'ssl_capath'</literal> settings map to these in <classname>Socket</classname> adapter).
+ </simpara></listitem>
+ </itemizedlist>
+ </para>
+ </refsection>
+
</refentry>
Modified: pear/peardoc/trunk/entities/global.ent
===================================================================
--- pear/peardoc/trunk/entities/global.ent 2014-01-15 08:36:35 UTC (rev 332623)
+++ pear/peardoc/trunk/entities/global.ent 2014-01-15 08:44:25 UTC (rev 332624)
@@ -292,6 +292,11 @@
<!ENTITY url.html_table.javascript.sorting2 "http://www.workingwith.me.uk/articles/scripting/standardista_table_sorting">
<!ENTITY url.html_table.api.html_common "http://pear.php.net/package/HTML_Common/docs/latest/HTML_Common/HTML_Common.html">
+<!-- HTTP_Request2 -->
+<!ENTITY url.http_request2.ca "http://en.wikipedia.org/wiki/Certificate_authority">
+<!ENTITY url.http_request2.caextract "http://curl.haxx.se/docs/caextract.html">
+<!ENTITY url.http_request2.rfc-verification "https://wiki.php.net/rfc/tls-peer-verification">
+
<!-- Log -->
<!ENTITY url.log.home "http://pear.github.com/Log/">
--55a12f2e30e92aa443a979be4e2d64096bd76539--