<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>SSL context option listing</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="context.ftp.html">FTP context options</a></div>
<div class="next" style="text-align: right; float: right;"><a href="context.curl.html">CURL context options</a></div>
<div class="up"><a href="context.html">Context options and parameters</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="context.ssl" class="refentry">
<div class="refnamediv">
<h1 class="refname">SSL context options</h1>
<p class="refpurpose"><span class="refname">SSL context options</span> — <span class="dc-title">SSL context option listing</span></p>
</div>
<div class="refsect1 description" id="refsect1-context.ssl-description">
<h3 class="title">Description</h3>
<p class="para">
Context options for <em>ssl://</em> and <em>tls://</em>
transports.
</p>
</div>
<div class="refsect1 options" id="refsect1-context.ssl-options">
<h3 class="title">Options</h3>
<p class="para">
<dl>
<dt id="context.ssl.peer-name">
<code class="parameter">peer_name</code>
<span class="type"><a href="language.types.string.html" class="type string">string</a></span>
</dt>
<dd>
<p class="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.
</p>
</dd>
<dt id="context.ssl.verify-peer">
<code class="parameter">verify_peer</code>
<span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span>
</dt>
<dd>
<p class="para">
Require verification of SSL certificate used.
</p>
<p class="para">
Defaults to <strong><code>TRUE</code></strong>.
</p>
</dd>
<dt id="context.ssl.verify-peer-name">
<code class="parameter">verify_peer_name</code>
<span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span>
</dt>
<dd>
<p class="para">
Require verification of peer name.
</p>
<p class="para">
Defaults to <strong><code>TRUE</code></strong>.
</p>
</dd>
<dt id="context.ssl.allow-self-signed">
<code class="parameter">allow_self_signed</code>
<span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span>
</dt>
<dd>
<p class="para">
Allow self-signed certificates. Requires
<a href="context.ssl.html#context.ssl.verify-peer" class="link"><code class="parameter">verify_peer</code></a>.
</p>
<p class="para">
Defaults to <strong><code>FALSE</code></strong>
</p>
</dd>
<dt id="context.ssl.cafile">
<code class="parameter">cafile</code>
<span class="type"><a href="language.types.string.html" class="type string">string</a></span>
</dt>
<dd>
<p class="para">
Location of Certificate Authority file on local filesystem
which should be used with the <em>verify_peer</em>
context option to authenticate the identity of the remote peer.
</p>
</dd>
<dt id="context.ssl.capath">
<code class="parameter">capath</code>
<span class="type"><a href="language.types.string.html" class="type string">string</a></span>
</dt>
<dd>
<p class="para">
If <em>cafile</em> is not specified or if the certificate
is not found there, the directory pointed to by <em>capath</em>
is searched for a suitable certificate. <em>capath</em>
must be a correctly hashed certificate directory.
</p>
</dd>
<dt id="context.ssl.local-cert">
<code class="parameter">local_cert</code>
<span class="type"><a href="language.types.string.html" class="type string">string</a></span>
</dt>
<dd>
<p class="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 <em>local_pk</em>.
</p>
</dd>
<dt id="context.ssl.local-pk">
<code class="parameter">local_pk</code>
<span class="type"><a href="language.types.string.html" class="type string">string</a></span>
</dt>
<dd>
<p class="para">
Path to local private key file on filesystem in case of separate
files for certificate (<em>local_cert</em>) and private key.
</p>
</dd>
<dt id="context.ssl.passphrase">
<code class="parameter">passphrase</code>
<span class="type"><a href="language.types.string.html" class="type string">string</a></span>
</dt>
<dd>
<p class="para">
Passphrase with which your <em>local_cert</em> file
was encoded.
</p>
</dd>
<dt id="context.ssl.cn-match">
<code class="parameter">CN_match</code>
<span class="type"><a href="language.types.string.html" class="type string">string</a></span>
</dt>
<dd>
<p class="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.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="simpara">
This option is deprecated, in favour of <code class="parameter">peer_name</code>,
as of PHP 5.6.0.
</span>
</p></blockquote>
</dd>
<dt id="context.ssl.verify-depth">
<code class="parameter">verify_depth</code>
<span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span>
</dt>
<dd>
<p class="para">
Abort if the certificate chain is too deep.
</p>
<p class="para">
Defaults to no verification.
</p>
</dd>
<dt id="context.ssl.ciphers">
<code class="parameter">ciphers</code>
<span class="type"><a href="language.types.string.html" class="type string">string</a></span>
</dt>
<dd>
<p class="para">
Sets the list of available ciphers. The format of the string is described
in <a href="https://www.openssl.org/docs/manmaster/man1/ciphers.html#CIPHER-LIST-FORMAT" class="link external">» ciphers(1)</a>.
</p>
<p class="para">
Defaults to <em>DEFAULT</em>.
</p>
</dd>
<dt id="context.ssl.capture-peer-cert">
<code class="parameter">capture_peer_cert</code>
<span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span>
</dt>
<dd>
<p class="para">
If set to <strong><code>TRUE</code></strong> a <em>peer_certificate</em> context option
will be created containing the peer certificate.
</p>
</dd>
<dt id="context.ssl.capture-peer-cert-chain">
<code class="parameter">capture_peer_cert_chain</code>
<span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span>
</dt>
<dd>
<p class="para">
If set to <strong><code>TRUE</code></strong> a <em>peer_certificate_chain</em> context
option will be created containing the certificate chain.
</p>
</dd>
<dt id="context.ssl.sni-enabled">
<code class="parameter">SNI_enabled</code>
<span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span>
</dt>
<dd>
<p class="para">
If set to <strong><code>TRUE</code></strong> server name indication will be enabled. Enabling SNI
allows multiple certificates on the same IP address.
</p>
</dd>
<dt id="context.ssl.sni-server-name">
<code class="parameter">SNI_server_name</code>
<span class="type"><a href="language.types.string.html" class="type string">string</a></span>
</dt>
<dd>
<p class="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.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="simpara">
This option is deprecated, in favour of <code class="parameter">peer_name</code>,
as of PHP 5.6.0.
</span>
</p></blockquote>
</dd>
<dt id="context.ssl.disable-compression">
<code class="parameter">disable_compression</code>
<span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span>
</dt>
<dd>
<p class="para">
If set, disable TLS compression. This can help mitigate the CRIME attack
vector.
</p>
</dd>
<dt id="context.ssl.peer-fingerprint">
<code class="parameter">peer_fingerprint</code>
<span class="type"><a href="language.types.string.html" class="type string">string</a></span> | <span class="type"><a href="language.types.array.html" class="type array">array</a></span>
</dt>
<dd>
<p class="para">
Aborts when the remote certificate digest doesn't match the specified
hash.
</p>
<p class="para">
When a <span class="type"><a href="language.types.string.html" class="type string">string</a></span> is used, the length will determine which hashing algorithm
is applied, either "md5" (32) or "sha1" (40).
</p>
<p class="para">
When an <span class="type"><a href="language.types.array.html" class="type array">array</a></span> is used, the keys indicate the hashing algorithm name
and each corresponding value is the expected digest.
</p>
</dd>
</dl>
</p>
</div>
<div class="refsect1 changelog" id="refsect1-context.ssl-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>5.6.0</td>
<td>
Added <code class="parameter">peer_fingerprint</code> and <code class="parameter">verify_peer_name</code>.
<code class="parameter">verify_peer</code> default changed to <strong><code>TRUE</code></strong>.
</td>
</tr>
<tr>
<td>5.4.13</td>
<td>
Added <code class="parameter">disable_compression</code>. Requires OpenSSL >= 1.0.0.
</td>
</tr>
<tr>
<td>5.3.2</td>
<td>
Added <code class="parameter">SNI_enabled</code> and
<code class="parameter">SNI_server_name</code>.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 notes" id="refsect1-context.ssl-notes">
<h3 class="title">Notes</h3>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="simpara">
Because <em>ssl://</em> is the underlying transport for the
<a href="wrappers.http.html" class="link"><em>https://</em></a> and
<a href="wrappers.ftp.html" class="link"><em>ftps://</em></a> wrappers,
any context options which apply to <em>ssl://</em> also apply to
<em>https://</em> and <em>ftps://</em>.
</span>
</p></blockquote>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="simpara">
For SNI (Server Name Indication) to be available, then PHP must be compiled
with OpenSSL 0.9.8j or greater. Use the
<strong><code>OPENSSL_TLSEXT_SERVER_NAME</code></strong> to determine whether SNI is
supported.
</span>
</p></blockquote>
</div>
<div class="refsect1 seealso" id="refsect1-context.ssl-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"><a href="context.socket.html" class="xref">Socket context options</a></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="context.ftp.html">FTP context options</a></div>
<div class="next" style="text-align: right; float: right;"><a href="context.curl.html">CURL context options</a></div>
<div class="up"><a href="context.html">Context options and parameters</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
