SSL context options

SSL context options — SSL context option listing

Description

Context options for ssl:// and tls:// transports.

Options

peer_name string

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.

verify_peer boolean

Require verification of SSL certificate used.

Defaults to TRUE.

verify_peer_name boolean

Require verification of peer name.

Defaults to TRUE.

allow_self_signed boolean

Allow self-signed certificates. Requires verify_peer.

Defaults to FALSE

cafile string

Location of Certificate Authority file on local filesystem which should be used with the verify_peer context option to authenticate the identity of the remote peer.

capath string

If cafile is not specified or if the certificate is not found there, the directory pointed to by capath is searched for a suitable certificate. capath must be a correctly hashed certificate directory.

local_cert string

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

local_pk string

Path to local private key file on filesystem in case of separate files for certificate (local_cert) and private key.

passphrase string

Passphrase with which your local_cert file was encoded.

CN_match string

Common Name we are expecting. PHP will perform limited wildcard matching. If the Common Name does not match this, the connection attempt will fail.

Note: This option is deprecated, in favour of peer_name, as of PHP 5.6.0.

verify_depth integer

Abort if the certificate chain is too deep.

Defaults to no verification.

ciphers string

Sets the list of available ciphers. The format of the string is described in » ciphers(1).

Defaults to DEFAULT.

capture_peer_cert boolean

If set to TRUE a peer_certificate context option will be created containing the peer certificate.

capture_peer_cert_chain boolean

If set to TRUE a peer_certificate_chain context option will be created containing the certificate chain.

SNI_enabled boolean

If set to TRUE server name indication will be enabled. Enabling SNI allows multiple certificates on the same IP address.

SNI_server_name string

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.

Note: This option is deprecated, in favour of peer_name, as of PHP 5.6.0.

disable_compression boolean

If set, disable TLS compression. This can help mitigate the CRIME attack vector.

peer_fingerprint string | array

Aborts when the remote certificate digest doesn't match the specified hash.

When a string is used, the length will determine which hashing algorithm is applied, either "md5" (32) or "sha1" (40).

When an array is used, the keys indicate the hashing algorithm name and each corresponding value is the expected digest.

Changelog

Version	Description
5.6.0	Added `peer_fingerprint` and `verify_peer_name`. `verify_peer` default changed to `TRUE`.
5.4.13	Added `disable_compression`. Requires OpenSSL >= 1.0.0.
5.3.2	Added `SNI_enabled` and `SNI_server_name`.
5.0.0	Added `capture_peer_cert`, `capture_peer_chain`, `ciphers` and `local_pk`.

Notes

Note: Because ssl:// is the underlying transport for the https:// and ftps:// wrappers, any context options which apply to ssl:// also apply to https:// and ftps://.

Note: For SNI (Server Name Indication) to be available, then PHP must be compiled with OpenSSL 0.9.8j or greater. Use the OPENSSL_TLSEXT_SERVER_NAME to determine whether SNI is supported.

User Contributed Notes

Botjan kufca

6 years ago


CN_match works contrary to intuitive thinking. I came across this when I was developing SSL server implemented in PHP. I stated (in code): 

- do not allow self signed certs (works)
- verify peer certs against CA cert (works)
- verify the client's CN against CN_match (does not work), like this:

stream_context_set_option($context, 'ssl', 'CN_match', '*.example.org');

I presumed this would match any client with CN below .example.org domain.
Unfortunately this is NOT the case. The option above does not do that.

What it really does is this:
- it takes client's CN and compares it to CN_match
- IF CLIENT's CN CONTAINS AN ASTERISK like *.example.org, then it is matched against CN_match in wildcard matching fashion

Examples to illustrate behaviour:
(CNM = server's CN_match)
(CCN = client's CN)

- CNM=host.example.org, CCN=host.example.org ---> OK
- CNM=host.example.org, CCN=*.example.org ---> OK
- CNM=.example.org, CCN=*.example.org ---> OK
- CNM=example.org, CCN=*.example.org ---> ERROR

- CNM=*.example.org, CCN=host.example.org ---> ERROR
- CNM=*.example.org, CCN=*.example.org ---> OK

According to PHP sources I believe that the same applies if you are trying to act as Client and the server contains a wildcard certificate. If you set CN_match to myserver.example.org and server presents itself with *.example.org, the connection is allowed.

Everything above applies to PHP version 5.2.12.
I will supply a patch to support CN_match starting with asterisk.

Anonymous

1 year ago


If I read the UPGRADING file correctly, in PHP 5.6 the default value of verify_peer has changed.

borbas dot geri at gmail dot com

2 years ago


I used this for Apple Push Notification Service.
Passed in a local certificate filename `cert.pem` trough local_cert option. 
Worked fine, when invoked the script directly.

But when I included/required the script from a different location, it stopped working, without any explicit error message.

Resolved by passed in the full path for the file `<FullPathTo>cert.pem`.