yii\httpclient\Client SSL verification behavior across transports

Question

The yii\httpclient\Client provides a unified interface for making HTTP requests, utilizing either cURL or stream transports depending on the environment and configuration. By default, the client performs SSL peer verification to ensure the security of HTTPS connections.

While the verify option allows developers to toggle certificate checks, there is a potential discrepancy in how hostname validation is handled between the two transport layers. Specifically, the interaction between sslVerifyPeer and sslVerifyHost may vary depending on the underlying PHP version and the active transport mechanism.

This creates uncertainty when designing a security policy that must remain consistent regardless of whether the system defaults to cURL or streams.

Does the yii\httpclient\Client guarantee identical hostname validation behavior when switching between cURL and stream transports?
  In what specific scenarios does the stream transport ignore sslVerifyHost settings compared to the cURL transport?

Tasadduq Burney · Answer

Answer
Yes – when the same verification options are explicitly set, yii\httpclient\Client behaves identically for both the cURL and Stream transports.
Explanation
The client maps its generic verify flag (or the transport‑specific ssl_verify_peer and ssl_verify_host flags) to the underlying library as follows:

CurlTransport: verify → CURLOPT_SSL_VERIFYPEER (and CURLOPT_SSL_VERIFYHOST when host verification is requested).
  StreamTransport: verify → stream context options verify_peer and verify_peer_name.

If you set verify => true (or leave it unset, which defaults to true), both transports enable peer verification and hostname verification. If you set verify => false (or ssl_verify_peer => false), both transports disable peer verification; hostname verification is then only performed when ssl_verify_host => true is also explicitly supplied.
When the Stream transport may ignore sslVerifyHost
The Stream transport will effectively ignore an explicit ssl_verify_host => true setting in the following situation:

The client is configured with verify => false (or ssl_verify_peer => false).
  No explicit ssl_verify_host value is provided, leaving it at its default.
  Under these conditions the stream context sets verify_peer => false and, consequently, verify_peer_name => false regardless of the ssl_verify_host flag, because the stream API only honors hostname verification when peer verification is enabled.

In contrast, the cURL transport keeps CURLOPT_SSL_VERIFYHOST at its default value (2) even when CURLOPT_SSL_VERIFYPEER is false, so hostname verification may still occur unless you also set CURLOPT_SSL_VERIFYHOST => 0. Therefore, to guarantee identical behavior you must either:

Leave verify at its default (true) and rely on the library defaults, or
  Explicitly set both ssl_verify_peer and ssl_verify_host to the same value for both transports.

Verification steps

Create a client with verify => false and ssl_verify_host => true.
  Send a request to a host with a valid certificate but a mismatched hostname (e.g., https://wrong.host.badssl.com/) using both transports.
  Observe that the Stream transport succeeds (no hostname error) while the cURL transport fails with a hostname mismatch error.

If you need to confirm which transport is active, inspect $client->getTransport() or force a transport via 'transport' => 'yii\httpclient\StreamTransport'.

yii\httpclient\Client SSL verification behavior across transports

1 answer

1 question comment

Stream transport cannot decouple hostname from peer verification

Redirect handling divergence

Answer

Explanation

When the Stream transport may ignore `sslVerifyHost`

Verification steps

Your perspective belongs here.