<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<sect1 xml:id="migration56.openssl" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>OpenSSL changes in PHP 5.6.x</title>

 <sect2 xml:id="migration56.openssl.peer-verification">
  <title>Stream wrappers now verify peer certificates and host names by default when using SSL/TLS</title>

  &migration56.openssl.peer-verification;
 </sect2>

 <sect2 xml:id="migration56.openssl.fingerprint">
  <title>Certificate fingerprints</title>

  <para>
   Support has been added for extracting and verifying certificate
   fingerprints. <function>openssl_x509_fingerprint</function> has been added
   to extract a fingerprint from an X.509 certificate, and two
   <link linkend="context.ssl">SSL stream context</link> options have been
   added: <literal>capture_peer_cert</literal> to capture the peer's X.509
   certificate, and <literal>peer_fingerprint</literal> to assert that the
   peer's certificate should match the given fingerprint.
  </para>
 </sect2>

 <sect2 xml:id="migration56.openssl.ciphers">
  <title>Default ciphers updated</title>

  <para>
   The default ciphers used by PHP have been updated to a more secure list
   based on the
   <link xlink:href="&url.openssl.ciphers.mozilla;">Mozilla cipher recommendations</link>,
   with two additional exclusions: anonymous Diffie-Hellman ciphers, and RC4.
  </para>

  <para>
   This list can be accessed via the new
   <constant>OPENSSL_DEFAULT_STREAM_CIPHERS</constant> constant, and can be
   overridden (as in previous PHP versions) by setting the
   <link linkend="context.ssl.ciphers"><parameter>ciphers</parameter></link>
   context option.
  </para>
 </sect2>

 <sect2 xml:id="migration56.openssl.tls-compression">
  <title>Compression disabled by default</title>

  <para>
   SSL/TLS compression has been disabled by default to mitigate the CRIME
   attack. PHP 5.4.13 added a
   <link linkend="context.ssl.disable-compression"><parameter>disable_compression</parameter></link>
   context option to allow compression to be disabled: this is now set to
   &true; (that is, compression is disabled) by default.
  </para>
 </sect2>

 <sect2 xml:id="migration56.openssl.honor-cipher-order">
  <title>Allow servers to prefer their cipher order</title>

  <para>
   The <parameter>honor_cipher_order</parameter> SSL context option has been
   added to allow encrypted stream servers to mitigate BEAST vulnerabilities
   by preferring the server's ciphers to the client's.
  </para>
 </sect2>

 <sect2 xml:id="migration56.openssl.metadata">
  <title>Access the negotiated protocol and cipher</title>

  <para>
   The protocol and cipher that were negotiated for an encrypted stream can
   now be accessed via <function>stream_get_meta_data</function> or
   <function>stream_context_get_options</function> when the
   <parameter>capture_session_meta</parameter> SSL context option is set to
   &true;.
  </para>

  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$ctx = stream_context_create(['ssl' => [
    'capture_session_meta' => TRUE
]]);
 
$html = file_get_contents('https://google.com/', FALSE, $ctx);
$meta = stream_context_get_options($ctx)['ssl']['session_meta'];
var_dump($meta);
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
array(4) {
  ["protocol"]=>
  string(5) "TLSv1"
  ["cipher_name"]=>
  string(20) "ECDHE-RSA-AES128-SHA"
  ["cipher_bits"]=>
  int(128)
  ["cipher_version"]=>
  string(11) "TLSv1/SSLv3"
}
]]>
   </screen>
  </informalexample>
 </sect2>

 <sect2 xml:id="migration56.openssl.forward-secrecy">
  <title>New options for perfect forward secrecy in encrypted stream servers</title>

  <para>
   Encrypted client streams already support perfect forward secrecy, as it is
   generally controlled by the server. PHP encrypted server streams using
   certificates capable of perfect forward secrecy do not need to take any
   additional action to enable PFS; however a number of new SSL context options
   have been added to allow more control over PFS and deal with any
   compatibility issues that may arise. 
  </para>

  <variablelist>
   <varlistentry>
    <term><parameter>ecdh_curve</parameter></term>
    <listitem>
     <para>
      This option allows the selection of a specific curve for use with ECDH
      ciphers. If not specified, <literal>prime256v1</literal> will be used.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>dh_param</parameter></term>
    <listitem>
     <para>
      A path to a file containing parametrs for Diffie-Hellman key exchange,
      such as that created by the following command:
     </para>
     <programlisting role="shell">
<![CDATA[
openssl dhparam -out /path/to/my/certs/dh-2048.pem 2048
]]>
     </programlisting>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>single_dh_use</parameter></term>
    <listitem>
     <para>
      If set to &true;, a new key pair will be created when using
      Diffie-Hellman parameters, thereby improving forward secrecy.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>single_ecdh_use</parameter></term>
    <listitem>
     <para>
      If set to &true;, a new key pair will always be generated when ECDH
      cipher suites are negotiated. This improves forward secrecy.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect2>

 <sect2 xml:id="migration56.openssl.crypto-method">
  <title>SSL/TLS version selection</title>

  <para>
   It is now possible to select specific versions of SSL and TLS via the
   <parameter>crypto_method</parameter> SSL context option or by specifying a
   specific transport when creating a stream wrapper (for example, by calling
   <function>stream_socket_client</function> or
   <function>stream_socket_server</function>).
  </para>

  <para>
   The <parameter>crypto_method</parameter> SSL context option accepts a
   bitmask enumerating the protocols that are permitted, as does the
   <parameter>crypto_type</parameter> of
   <function>stream_socket_enable_crypto</function>.
   <!-- TODO: link to full list, which is too big for this page but should be
              in the crypto_method and stream_socket_enable_crypto()
              documentation. -->
  </para>

  <segmentedlist>
   <title>Selected protocol versions and corresponding options</title>
   <segtitle>Protocol(s)</segtitle>
   <segtitle>Client flag</segtitle>
   <segtitle>Server flag</segtitle>
   <segtitle>Transport</segtitle>
   <seglistitem>
    <seg>Any TLS or SSL version</seg>
    <seg><constant>STREAM_CRYPTO_METHOD_ANY_CLIENT</constant></seg>
    <seg><constant>STREAM_CRYPTO_METHOD_ANY_SERVER</constant></seg>
    <seg><literal>ssl://</literal></seg>
   </seglistitem>
   <seglistitem>
    <seg>Any TLS version</seg>
    <seg><constant>STREAM_CRYPTO_METHOD_TLS_CLIENT</constant></seg>
    <seg><constant>STREAM_CRYPTO_METHOD_TLS_SERVER</constant></seg>
    <seg><literal>tls://</literal></seg>
   </seglistitem>
   <seglistitem>
    <seg>TLS 1.0</seg>
    <seg><constant>STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT</constant></seg>
    <seg><constant>STREAM_CRYPTO_METHOD_TLSv1_0_SERVER</constant></seg>
    <seg><literal>tlsv1.0://</literal></seg>
   </seglistitem>
   <seglistitem>
    <seg>TLS 1.1</seg>
    <seg><constant>STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT</constant></seg>
    <seg><constant>STREAM_CRYPTO_METHOD_TLSv1_1_SERVER</constant></seg>
    <seg><literal>tlsv1.1://</literal></seg>
   </seglistitem>
   <seglistitem>
    <seg>TLS 1.2</seg>
    <seg><constant>STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT</constant></seg>
    <seg><constant>STREAM_CRYPTO_METHOD_TLSv1_2_SERVER</constant></seg>
    <seg><literal>tlsv1.2://</literal></seg>
   </seglistitem>
   <seglistitem>
    <seg>SSL 3</seg>
    <seg><constant>STREAM_CRYPTO_METHOD_SSLv3_CLIENT</constant></seg>
    <seg><constant>STREAM_CRYPTO_METHOD_SSLv3_SERVER</constant></seg>
    <seg><literal>sslv3://</literal></seg>
   </seglistitem>
  </segmentedlist>

  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php

// Requiring TLS 1.0 or better when using file_get_contents():
$ctx = stream_context_create([
    'ssl' => [
        'crypto_method' => STREAM_CRYPTO_METHOD_TLS_CLIENT,
    ],
]);
$html = file_get_contents('https://google.com/', false, $ctx);

// Requiring TLS 1.1 or 1.2:
$ctx = stream_context_create([
    'ssl' => [
        'crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT |
                           STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT,
    ],
]);
$html = file_get_contents('https://google.com/', false, $ctx);

// Connecting using the tlsv1.2:// stream socket transport.
$sock = stream_socket_client('tlsv1.2://google.com:443/');

?>
]]>
   </programlisting>
  </informalexample>
 </sect2>

 <sect2 xml:id="migration56.openssl.default-certificate-paths">
  <title><function>openssl_get_cert_locations</function> added</title>

  <para>
   The <function>openssl_get_cert_locations</function> function has been
   added: it returns the default locations PHP will search when looking for
   CA bundles.
  </para>

  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
var_dump(openssl_get_cert_locations());
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
array(8) {
  ["default_cert_file"]=>
  string(21) "/etc/pki/tls/cert.pem"
  ["default_cert_file_env"]=>
  string(13) "SSL_CERT_FILE"
  ["default_cert_dir"]=>
  string(18) "/etc/pki/tls/certs"
  ["default_cert_dir_env"]=>
  string(12) "SSL_CERT_DIR"
  ["default_private_dir"]=>
  string(20) "/etc/pki/tls/private"
  ["default_default_cert_area"]=>
  string(12) "/etc/pki/tls"
  ["ini_cafile"]=>
  string(0) ""
  ["ini_capath"]=>
  string(0) ""
}
]]>
   </screen>
  </informalexample>
 </sect2>

 <sect2 xml:id="migration56.openssl.spki">
  <title>SPKI support</title>

  <para>
   Support has been added for generating, extracting and verifying signed
   public key and challenges (SPKAC). <function>openssl_spki_new</function>,
   <function>openssl_spki_verify</function>,
   <function>openssl_spki_export_challenge</function>, and
   <function>openssl_spki_export</function> have been added to create, verify
   export <acronym>PEM</acronym> public key and associated challenge from
   SPKAC's generated from a <literal>KeyGen</literal> HTML5 element.
  </para>

  <variablelist>
   <varlistentry>
    <term><parameter>openssl_spki_new</parameter></term>
    <listitem>
     <para>
      Generates a new SPKAC using private key, challenge string and hashing
      algorithm.
     </para>

     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
$pkey = openssl_pkey_new();
openssl_pkey_export($pkey, 'secret passphrase');

$spkac = openssl_spki_new($pkey, 'challenge string');
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
SPKAC=MIIBXjCByDCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA3L0IfUijj7+A8CPC8EmhcdNoe5fUAog7OrBdhn7EkxFButUp40P7+LiYiygYG1TmoI/a5EgsLU3s9twEz3hmgY9mYIqb/rb+SF8qlD/K6KVyUORC7Wlz1Df4L8O3DuRGzx6/+3jIW6cPBpfgH1sVuYS1vDBsP/gMMIxwTsKJ4P0CAwEAARYkYjViMzYxMTktNjY5YS00ZDljLWEyYzctMGZjNGFhMjVlMmE2MA0GCSqGSIb3DQEBAwUAA4GBAF7hu0ifzmjonhAak2FhhBRsKFDzXdKIkrWxVNe8e0bZzMrWOxFM/rqBgeH3/gtOUDRS5Fnzyq425UsTYbjfiKzxGeCYCQJb1KJ2V5Ij/mIJHZr53WYEXHQTNMGR8RPm7IxwVXVSHIgAfXsXZ9IXNbFbcaLRiSTr9/N4U+MXUWL7
]]>
      </screen>
     </informalexample>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>openssl_spki_verify</parameter></term>
    <listitem>
     <para>
      Verifies provided SPKAC.
     </para>

     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
$pkey = openssl_pkey_new();
openssl_pkey_export($pkey, 'secret passphrase');

$spkac = openssl_spki_new($pkey, 'challenge string');
var_dump(openssl_spki_verify($spkac));
?>
]]>
      </programlisting>
     </informalexample>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>openssl_spki_export_challenge</parameter></term>
    <listitem>
     <para>
      Exports associated challenge from provided SPKAC.
     </para>

     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
$pkey = openssl_pkey_new();
openssl_pkey_export($pkey, 'secret passphrase');

$spkac = openssl_spki_new($pkey, 'challenge string');
$challenge = openssl_spki_export_challenge($spkac);
echo $challenge;
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
challenge string
]]>
      </screen>
     </informalexample>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>openssl_spki_export</parameter></term>
    <listitem>
     <para>
      Exports the <acronym>PEM</acronym> formatted RSA public key from SPKAC.
     </para>

     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
$pkey = openssl_pkey_new();
openssl_pkey_export($pkey, 'secret passphrase');

$spkac = openssl_spki_new($pkey, 'challenge string');
echo openssl_spki_export($spkac);
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDcvQh9SKOPv4DwI8LwSaFx02h7
l9QCiDs6sF2GfsSTEUG61SnjQ/v4uJiLKBgbVOagj9rkSCwtTez23ATPeGaBj2Zg
ipv+tv5IXyqUP8ropXJQ5ELtbXPUN/gvw7cO5EbPHr/7eMhbpw8Gl+AfWxW5hLW8
MGw/+AwwjHBOwong/QIDAQAB
-----END PUBLIC KEY-----
]]>
      </screen>
     </informalexample>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect2>
</sect1>

<!-- 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
-->