mirror of
https://github.com/php/doc-en.git
synced 2026-03-23 23:32:18 +01:00
460 lines
14 KiB
XML
460 lines
14 KiB
XML
<?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
|
|
-->
|