mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
6972146ba2
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@341125 c90b9560-bf6c-de11-be94-00142212c4b1
372 lines
10 KiB
XML
372 lines
10 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
|
|
<refentry xml:id="context.ssl" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" role="noversion">
|
|
<refnamediv>
|
|
<refname>SSL context options</refname>
|
|
<refpurpose>SSL context option listing</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<para>
|
|
Context options for <literal>ssl://</literal> and <literal>tls://</literal>
|
|
transports.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="options"><!-- {{{ -->
|
|
&reftitle.options;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry xml:id="context.ssl.peer-name">
|
|
<term>
|
|
<parameter>peer_name</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Peer name to be used. If this value is not set, then the name is guessed
|
|
based on the hostname used when opening the stream.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.verify-peer">
|
|
<term>
|
|
<parameter>verify_peer</parameter>
|
|
<type>boolean</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Require verification of SSL certificate used.
|
|
</para>
|
|
<para>
|
|
Defaults to &true;.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.verify-peer-name">
|
|
<term>
|
|
<parameter>verify_peer_name</parameter>
|
|
<type>boolean</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Require verification of peer name.
|
|
</para>
|
|
<para>
|
|
Defaults to &true;.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.allow-self-signed">
|
|
<term>
|
|
<parameter>allow_self_signed</parameter>
|
|
<type>boolean</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Allow self-signed certificates. Requires
|
|
<link linkend="context.ssl.verify-peer"><parameter>verify_peer</parameter></link>.
|
|
</para>
|
|
<para>
|
|
Defaults to &false;
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.cafile">
|
|
<term>
|
|
<parameter>cafile</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Location of Certificate Authority file on local filesystem
|
|
which should be used with the <literal>verify_peer</literal>
|
|
context option to authenticate the identity of the remote peer.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.capath">
|
|
<term>
|
|
<parameter>capath</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
If <literal>cafile</literal> is not specified or if the certificate
|
|
is not found there, the directory pointed to by <literal>capath</literal>
|
|
is searched for a suitable certificate. <literal>capath</literal>
|
|
must be a correctly hashed certificate directory.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.local-cert">
|
|
<term>
|
|
<parameter>local_cert</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Path to local certificate file on filesystem. It must be a PEM
|
|
encoded file which contains your certificate and private key.
|
|
It can optionally contain the certificate chain of issuers.
|
|
The private key also may be contained in a separate file specified
|
|
by <literal>local_pk</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.local-pk">
|
|
<term>
|
|
<parameter>local_pk</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Path to local private key file on filesystem in case of separate
|
|
files for certificate (<literal>local_cert</literal>) and private key.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.passphrase">
|
|
<term>
|
|
<parameter>passphrase</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passphrase with which your <literal>local_cert</literal> file
|
|
was encoded.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.cn-match">
|
|
<term>
|
|
<parameter>CN_match</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Common Name we are expecting. PHP will perform limited wildcard
|
|
matching. If the Common Name does not match this, the connection
|
|
attempt will fail.
|
|
</para>
|
|
<note>
|
|
<simpara>
|
|
This option is deprecated, in favour of <parameter>peer_name</parameter>,
|
|
as of PHP 5.6.0.
|
|
</simpara>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.verify-depth">
|
|
<term>
|
|
<parameter>verify_depth</parameter>
|
|
<type>integer</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Abort if the certificate chain is too deep.
|
|
</para>
|
|
<para>
|
|
Defaults to no verification.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.ciphers">
|
|
<term>
|
|
<parameter>ciphers</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Sets the list of available ciphers. The format of the string is described
|
|
in <link xlink:href="&url.openssl.ciphers;">ciphers(1)</link>.
|
|
</para>
|
|
<para>
|
|
Defaults to <literal>DEFAULT</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.capture-peer-cert">
|
|
<term>
|
|
<parameter>capture_peer_cert</parameter>
|
|
<type>boolean</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
If set to &true; a <literal>peer_certificate</literal> context option
|
|
will be created containing the peer certificate.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.capture-peer-cert-chain">
|
|
<term>
|
|
<parameter>capture_peer_cert_chain</parameter>
|
|
<type>boolean</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
If set to &true; a <literal>peer_certificate_chain</literal> context
|
|
option will be created containing the certificate chain.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.sni-enabled">
|
|
<term>
|
|
<parameter>SNI_enabled</parameter>
|
|
<type>boolean</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
If set to &true; server name indication will be enabled. Enabling SNI
|
|
allows multiple certificates on the same IP address.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.sni-server-name">
|
|
<term>
|
|
<parameter>SNI_server_name</parameter>
|
|
<type>string</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
If set, then this value will be used as server name for server name
|
|
indication. If this value is not set, then the server name is guessed
|
|
based on the hostname used when opening the stream.
|
|
</para>
|
|
<note>
|
|
<simpara>
|
|
This option is deprecated, in favour of <parameter>peer_name</parameter>,
|
|
as of PHP 5.6.0.
|
|
</simpara>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.disable-compression">
|
|
<term>
|
|
<parameter>disable_compression</parameter>
|
|
<type>boolean</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
If set, disable TLS compression. This can help mitigate the CRIME attack
|
|
vector.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="context.ssl.peer-fingerprint">
|
|
<term>
|
|
<parameter>peer_fingerprint</parameter>
|
|
<type>string</type> | <type>array</type>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Aborts when the remote certificate digest doesn't match the specified
|
|
hash.
|
|
</para>
|
|
<para>
|
|
When a <type>string</type> is used, the length will determine which hashing algorithm
|
|
is applied, either "md5" (32) or "sha1" (40).
|
|
</para>
|
|
<para>
|
|
When an <type>array</type> is used, the keys indicate the hashing algorithm name
|
|
and each corresponding value is the expected digest.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1><!-- }}} -->
|
|
|
|
<refsect1 role="changelog"><!-- {{{ -->
|
|
&reftitle.changelog;
|
|
<para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>5.6.0</entry>
|
|
<entry>
|
|
Added <parameter>peer_fingerprint</parameter> and <parameter>verify_peer_name</parameter>.
|
|
<parameter>verify_peer</parameter> default changed to &true;.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>5.4.13</entry>
|
|
<entry>
|
|
Added <parameter>disable_compression</parameter>. Requires OpenSSL >= 1.0.0.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>5.3.2</entry>
|
|
<entry>
|
|
Added <parameter>SNI_enabled</parameter> and
|
|
<parameter>SNI_server_name</parameter>.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1><!-- }}} -->
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
<note>
|
|
<simpara>
|
|
Because <literal>ssl://</literal> is the underlying transport for the
|
|
<link linkend="wrappers.http"><literal>https://</literal></link> and
|
|
<link linkend="wrappers.ftp"><literal>ftps://</literal></link> wrappers,
|
|
any context options which apply to <literal>ssl://</literal> also apply to
|
|
<literal>https://</literal> and <literal>ftps://</literal>.
|
|
</simpara>
|
|
</note>
|
|
<note>
|
|
<simpara>
|
|
For SNI (Server Name Indication) to be available, then PHP must be compiled
|
|
with OpenSSL 0.9.8j or greater. Use the
|
|
<constant>OPENSSL_TLSEXT_SERVER_NAME</constant> to determine whether SNI is
|
|
supported.
|
|
</simpara>
|
|
</note>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><xref linkend="context.socket" /></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
|
|
-->
|
|
|