From cd66fc9fce70d10b4cd7531ad4f7aa0c803b5579 Mon Sep 17 00:00:00 2001 From: "singi.qin" Date: Thu, 30 Apr 2026 09:36:16 +0800 Subject: [PATCH 1/2] =?UTF-8?q?feat:=20=E7=BF=BB=E8=AF=91=20appendices\exa?= =?UTF-8?q?mples.xml?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- appendices/examples.xml | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 appendices/examples.xml diff --git a/appendices/examples.xml b/appendices/examples.xml new file mode 100644 index 000000000..2469053b0 --- /dev/null +++ b/appendices/examples.xml @@ -0,0 +1,32 @@ + + + + + 关于手册示例 + + 需要注意的是，为了清晰简洁，PHP 文档中的许多示例都省略了错误和异常处理。 + + + 这并不意味着生产环境代码可以省略错误处理，因为此举可能会引发 TypeError 错误、强制转换失败值（例如将布尔值 &false; 转为空字符串），或是违背代码预设逻辑，进而产生难以排查的隐蔽漏洞。部分扩展库提供了完整示例，其中均包含错误处理逻辑，用以演示该扩展所提供各类函数与方法的规范用法。 + + + From 774ed3d744d519d528a829a155e965006d1cce33 Mon Sep 17 00:00:00 2001 From: "singi.qin" Date: Thu, 30 Apr 2026 10:54:54 +0800 Subject: [PATCH 2/2] =?UTF-8?q?feat:=20=E7=BF=BB=E8=AF=91=20appendices\mig?= =?UTF-8?q?ration56\openssl.xml?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot --- appendices/migration56/openssl.xml | 434 +++++++++++++++++++++++++++++ 1 file changed, 434 insertions(+) create mode 100644 appendices/migration56/openssl.xml diff --git a/appendices/migration56/openssl.xml b/appendices/migration56/openssl.xml new file mode 100644 index 000000000..49a498161 --- /dev/null +++ b/appendices/migration56/openssl.xml @@ -0,0 +1,434 @@ + + + + + + + PHP 5.6.x 中的 OpenSSL 更改 + + + 在使用 SSL/TLS 时，流包装器现在默认验证对等证书和主机名 + + &migration56.openssl.peer-verification; + + + + 证书指纹 + + + 已添加对提取和验证证书指纹的支持。添加了 openssl_x509_fingerprint + 以从 X.509 证书中提取指纹，并且添加了两个 + SSL 流上下文 选项：capture_peer_cert 用于捕获对等方的 X.509 + 证书，以及 peer_fingerprint 用于断言对等方的证书应与给定的指纹匹配。 + + + + + 默认密码套件已更新 + + + PHP 使用的默认密码套件已更新为基于 + Mozilla 密码套件推荐 的更安全的列表， + 另外排除了两个：匿名 Diffie-Hellman 密码套件和 RC4。 + + + + 此列表可以通过新的 + OPENSSL_DEFAULT_STREAM_CIPHERS 常量访问，并且可以通过设置 + ciphers + 上下文选项来覆盖。 + + + + + 默认禁用压缩 + + + SSL/TLS 压缩已默认禁用以缓解 CRIME + 攻击。PHP 5.4.13 添加了 + disable_compression + 上下文选项以允许禁用压缩：现在默认设置为 + &true;（即，压缩被禁用）。 + + + + + 允许服务器优先选择其密码套件顺序 + + + 已添加 honor_cipher_order SSL 上下文选项，以允许加密流服务器通过优先使用服务器的密码套件而不是客户端的密码套件来减轻 BEAST 漏洞。 + + + + + 访问协商的协议和密码套件 + + + 现在可以通过 stream_get_meta_data 或 + stream_context_get_options 访问为加密流协商的协议和密码套件，当 + capture_session_meta SSL 上下文选项设置为 + &true; 时。 + + + + + [ + '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); +?> +]]> + + &example.outputs; + + + string(5) "TLSv1" + ["cipher_name"]=> + string(20) "ECDHE-RSA-AES128-SHA" + ["cipher_bits"]=> + int(128) + ["cipher_version"]=> + string(11) "TLSv1/SSLv3" +} +]]> + + + + + + 加密流服务器中完美前向保密的新选项 + + + 加密客户端流已经支持完美前向保密，因为它通常由服务器控制。使用能够进行完美前向保密的证书的 PHP 加密服务器流不需要采取任何额外操作来启用 PFS；但是，已添加了许多新的 SSL 上下文选项，以允许对 PFS 进行更多控制并处理可能出现的任何兼容性问题。 + + + + + ecdh_curve + + + 此选项允许选择用于 ECDH 密码套件的特定曲线。如果未指定，将使用 prime256v1。 + + + + + dh_param + + + 指向包含 Diffie-Hellman 密钥交换参数的文件路径，例如由以下命令创建的文件： + + + + + + + + single_dh_use + + + 如果设置为 &true;，在使用 Diffie-Hellman 参数时将创建一个新的密钥对，从而改善前向保密。 + + + + + single_ecdh_use + + + 如果设置为 &true;，当协商 ECDH 密码套件时将始终生成新的密钥对。这改善了前向保密。 + + + + + + + + SSL/TLS 版本选择 + + + 现在可以通过 crypto_method SSL 上下文选项或通过在创建流包装器时指定特定传输来选择 SSL/TLS 版本（例如，通过调用 + stream_socket_client 或 + stream_socket_server）。 + + + + crypto_method SSL 上下文选项接受一个位掩码，枚举允许的协议，stream_socket_enable_crypto 的 + crypto_type 也是如此。 + + + + + 选定的协议版本及其对应选项 + 协议 + 客户端标志 + 服务器标志 + 传输 + + 任何 TLS 或 SSL 版本 + STREAM_CRYPTO_METHOD_ANY_CLIENT + STREAM_CRYPTO_METHOD_ANY_SERVER + ssl:// + + + 任何 TLS 版本 + STREAM_CRYPTO_METHOD_TLS_CLIENT + STREAM_CRYPTO_METHOD_TLS_SERVER + tls:// + + + TLS 1.0 + STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT + STREAM_CRYPTO_METHOD_TLSv1_0_SERVER + tlsv1.0:// + + + TLS 1.1 + STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT + STREAM_CRYPTO_METHOD_TLSv1_1_SERVER + tlsv1.1:// + + + TLS 1.2 + STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT + STREAM_CRYPTO_METHOD_TLSv1_2_SERVER + tlsv1.2:// + + + SSL 3 + STREAM_CRYPTO_METHOD_SSLv3_CLIENT + STREAM_CRYPTO_METHOD_SSLv3_SERVER + sslv3:// + + + + + + [ + '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/'); + +?> +]]> + + + + + + 添加了 <function>openssl_get_cert_locations</function> + + + 已添加 openssl_get_cert_locations 函数：它返回 PHP 在查找 CA 包时将搜索的默认位置。 + + + + + +]]> + + &example.outputs; + + + 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) "" +} +]]> + + + + + + SPKI 支持 + + + 已添加对生成、提取和验证签名公钥和挑战（SPKAC）的支持。添加了 openssl_spki_new、 + openssl_spki_verify、 + openssl_spki_export_challenge 和 + openssl_spki_export 以从 KeyGen HTML5 元素生成的 SPKAC 创建、验证和导出 PEM 公钥以及关联的挑战。 + + + + + openssl_spki_new + + + 使用私钥、挑战字符串和哈希算法生成新的 SPKAC。 + + + + + +]]> + + &example.outputs; + + + + + + + + + openssl_spki_verify + + + 验证提供的 SPKAC。 + + + + + +]]> + + + + + + + openssl_spki_export_challenge + + + 从提供的 SPKAC 导出关联的挑战。 + + + + + +]]> + + &example.outputs; + + + + + + + + + openssl_spki_export + + + 从 SPKAC 导出 PEM 格式的 RSA 公钥。 + + + + + +]]> + + &example.outputs; + + + + + + + + + + +