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

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