guzzlehttp/guzzle: Silent HTTPS-Proxy Downgrade to Cleartext
Impact
The built-in cURL handlers (GuzzleHttp\Handler\CurlHandler and GuzzleHttp\Handler\CurlMultiHandler, used by default whenever the PHP cURL extension is available) accept an https:// proxy — a proxy reached over a TLS-encrypted connection — through the proxy request option, client-level proxy defaults, or proxy environment variables such as http_proxy, https_proxy, HTTPS_PROXY, all_proxy, and ALL_PROXY.
When the installed libcurl does not support HTTPS proxies, behavior depends on the libcurl version/build:
- libcurl older than 7.50.2 silently treats an
https:// proxy as a plaintext http:// proxy. The TLS connection to the proxy is never established, and the proxy leg is cleartext with no error or warning. - libcurl 7.50.2 through 7.51.x rejects the unsupported proxy scheme at connect time, so no cleartext exposure occurs, but the failure is late and opaque.
- libcurl 7.52.0 or newer builds without HTTPS-proxy support also fail at connect time rather than downgrading.
The security-relevant case is the silent downgrade on libcurl older than 7.50.2. An application is affected when it sends requests through one of the built-in cURL handlers, configures an https:// proxy expecting the proxy connection itself to be encrypted, and runs with libcurl older than 7.50.2.
In that configuration, traffic expected to be protected by TLS on the hop to the proxy is transmitted in cleartext. Proxy authentication credentials (the Proxy-Authorization header, proxy userinfo in the proxy URL, or CURLOPT_PROXYUSERPWD) are sent without encryption, and the CONNECT target host and port for tunneled HTTPS requests are exposed. For plain HTTP requests, request headers and bodies are also exposed on the proxy leg. End-to-end HTTPS requests tunneled through the proxy remain protected by their inner TLS session; the exposure is limited to the proxy negotiation and proxy credentials.
Applications that do not configure an https:// proxy are not affected. Installations running libcurl 7.52.0 or newer built with HTTPS-proxy support are not affected because HTTPS proxies work as intended. Installations running libcurl 7.50.2 through 7.51.x, or libcurl 7.52.0 or newer built without HTTPS-proxy support, are not exposed to the silent cleartext downgrade, but Guzzle now rejects those unsupported configurations up front as well. The built-in stream handler is not affected; the issue is specific to the cURL handlers' proxy handling. Low-level cURL options under the curl request option, such as CURLOPT_PROXY or CURLOPT_PROXYTYPE, are advanced custom configuration and remain the caller's responsibility.
Patches
The issue is patched in 7.12.1 and later. Starting in that release, the built-in cURL handlers detect whether the installed libcurl supports HTTPS proxies — requiring both libcurl 7.52.0 or newer and the CURL_VERSION_HTTPS_PROXY feature bit — and reject a request configured through Guzzle's first-class proxy handling with an https:// proxy up front by throwing a GuzzleHttp\Exception\RequestException. No request bytes reach the network when the proxy cannot be used securely. Versions before 7.12.1 are affected by the silent downgrade when run against libcurl older than 7.50.2.
Workarounds
If you cannot upgrade immediately, do not configure an https:// proxy on an installation whose libcurl lacks HTTPS-proxy support, and verify the capability in application code before using one. Remember to check proxy environment variables as well as any explicit proxy option:
```php
$curl = \curl_version();
$httpsProxyBit = \defined('CURL_VERSION_HTTPS_PROXY') ? \CURL_VERSION_HTTPS_PROXY : (1 << 21);
if (\version_compare($curl['version'], '7.52.0', '<') || 0 === ($curl['features'] & $httpsProxyBit)) {
throw new \RuntimeException('Installed libcurl does not support HTTPS proxies.');
}
```
Upgrading the system libcurl to 7.52.0 or newer built with HTTPS-proxy support also resolves the underlying unsupported-proxy behavior.
