PHP 5.6.29 Released

SSL 上下文选项

SSL 上下文选项SSL 上下文选项清单

说明

ssl://tls:// 传输协议上下文选项清单。

可选项

peer_name string

要连接的服务器名称。如果未设置,那么服务器名称将根据打开 SSL 流的主机名称猜测得出。

verify_peer boolean

是否需要验证 SSL 证书。

默认值为 FALSE.

verify_peer_name boolean

Require verification of peer name.

默认值为 TRUE.

allow_self_signed boolean

是否允许自签名证书。需要配合 verify_peer 参数使用(注:当 verify_peer 参数为 true 时才会根据 allow_self_signed 参数值来决定是否允许自签名证书)。

默认值为 FALSE

cafile string

当设置 verify_peer 为 true 时, 用来验证远端证书所用到的 CA 证书。 本选项值为 CA 证书在本地文件系统的全路径及文件名。

capath string

如果未设置 cafile,或者 cafile 所指的文件不存在时, 会在 capath 所指定的目录搜索适用的证书。 该目录必须是已经经过哈希处理的证书目录。 (注:所谓 hashed certificate 目录是指使用类似 c_rehash 命令将目录中的 .pem 和 .crt 文件扫描并提取哈希码,然后根据此哈希码创建文件链接,以便于快速查找证书)

local_cert string

本地证书路径。 必须是 PEM 格式,并且包含本地的证书及私钥。 也可以包含证书颁发者证书链。 也可以通过 local_pk 指定包含私钥的独立文件。

local_pk string

如果使用独立的文件来存储证书(local_cert)和私钥, 那么使用此选项来指明私钥文件的路径。

passphrase string

local_cert 文件的密码。

CN_match string

期望远端证书的 CN 名称。 PHP 会进行有限的通配符匹配, 如果服务器给出的 CN 名称和本地访问的名称不匹配,则视为连接失败。

Note: 在PHP 5.6.0中,这个选项已废弃,替换为 peer_name

verify_depth integer

如果证书链条层次太深,超过了本选项的设定值,则终止验证。

默认情况下不限制证书链条层次深度。

ciphers string

设置可用的密码列表。 可用的值参见: » ciphers(1)

默认值为 DEFAULT.

capture_peer_cert boolean

如果设置为 TRUE 将会在上下文中创建 peer_certificate 选项, 该选项中包含远端证书。

capture_peer_cert_chain boolean

如果设置为 TRUE 将会在上下文中创建 peer_certificate_chain 选项, 该选项中包含远端证书链条。

SNI_enabled boolean

设置为 TRUE 将启用服务器名称指示(server name indication)。 启用 SNI 将允许同一 IP 地址使用多个证书。

SNI_server_name string

如果设置此参数,那么其设置值将被视为 SNI 服务器名称。 如果未设置,那么服务器名称将基于打开 SSL 流的主机名称猜测得出。

Note: 在PHP 5.6.0中,这个选项已废弃,替换为 peer_name

disable_compression boolean

如果设置,则禁用 TLS 压缩,有助于减轻恶意攻击。

peer_fingerprint string | array

当远程服务器证书的摘要和指定的散列值不相同的时候, 终止操作。

当使用 string 时, 会根据字符串的长度来检测所使用的散列算法:“md5”(32 字节)还是“sha1”(40 字节)。

当使用 array 时, 数组的键表示散列算法名称,其对应的值是预期的摘要值。

更新日志

版本 说明
5.6.0 新加 peer_fingerprint 参数。
5.4.13 新加 disable_compression。 需要 OpenSSL >= 1.0.0.
5.3.2 新加 SNI_enabledSNI_server_name
5.0.0 新加 capture_peer_certcapture_peer_chaincipherslocal_pk

注释

Note: 因为 ssl://https://ftps:// 的底层传输协议, 所以,ssl:// 的上下文选项也同样适用于 https://ftps:// 上下文。

Note: PHP 必须联合 OpenSSL 0.9.8j 或以上版本编译才可以支持 SNI, 同时也支持使用 OPENSSL_TLSEXT_SERVER_NAME 来探测 SNI 服务器名称。

add a note add a note

User Contributed Notes 6 notes

up
3
Anonymous
2 years ago
If I read the UPGRADING file correctly, in PHP 5.6 the default value of verify_peer has changed.
up
2
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.
up
2
website at meezaan dot net
3 months ago
There is also a crypto_type context. In older versions this was crypto_method. This is referenced on http://php.net/manual/en/function.stream-socket-enable-crypto.php.
up
1
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`.
up
0
Charlie
5 days ago
I am unable to load a PEM that was generated with the stunnel tools. However, I am able to use PHP calls to generate a working PEM that is recognized both by stunnel and php, as outlined here:

http://www.devdungeon.com/content/how-use-ssl-sockets-php

This code fragment is now working for me, and with stunnel verify=4, both sides confirm the fingerprint. Oddly, if "tls://" is set below, then TLSv1 is forced, but using "ssl://" allows TLSv1.2:

$stream_context = stream_context_create([ 'ssl' => [
'local_cert'        => '/path/to/key.pem',
'peer_fingerprint'  => openssl_x509_fingerprint(file_get_contents('/path/to/key.crt')),
'verify_peer'       => false,
'verify_peer_name'  => false,
'allow_self_signed' => true,
'verify_depth'      => 0 ]]);

$fp = stream_socket_client('ssl://ssl.server.com:12345',
   $errno, $errstr, 30, STREAM_CLIENT_CONNECT, $stream_context);
fwrite($fp, "foo bar\n");
while($line = fgets($fp, 8192)) echo $line;
up
0
Charlie
8 days ago
It appears that "allow_self_signed" does not and cannot apply to the local_cert option.

The stunnel verify=4 option, which verifies but ignores a CA, has no analog in these settings, which is unfortunate.

Even more perplexingly, while the "openssl verify -CAfile" is successful, PHP appears unable to use the new ca/crt pair in any configuration.

I did actually link my PHP against a copy of LibreSSL 2.3.8, but PHP oddly is unable to use TLS1.1 or 1.2. It does, however, enable EC secp521r1 (of which my native OpenSSL 0.9.8e is incapable).
To Top