<?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" annotations="verify_info:false" role="stream_context_option">
 <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>bool</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>bool</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>bool</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
       <acronym>PEM</acronym> 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.verify-depth">
     <term>
      <parameter>verify_depth</parameter>
      <type>int</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>bool</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>bool</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>bool</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.disable-compression">
     <term>
      <parameter>disable_compression</parameter>
      <type>bool</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>
    <varlistentry xml:id="context.ssl.security-level">
     <term>
      <parameter>security_level</parameter>
      <type>int</type>
     </term>
     <listitem>
      <para>
       Sets the security level. If not specified the library default security level is used.
       The security levels are described in
       <link xlink:href="&url.openssl.security-level;">SSL_CTX_get_security_level(3)</link>.
      </para>
      <para>
       Available as of PHP 7.2.0 and OpenSSL 1.1.0.
      </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>7.2.0</entry>
       <entry>
        Added <parameter>security_level</parameter>. Requires OpenSSL &gt;= 1.1.0.
       </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
-->