On this page
Two schemes, two different hops
A proxied request has two URLs, and each scheme controls a different hop. The proxy URL's scheme decides how your client talks to the proxy. The destination URL's scheme decides how your client talks to the server behind it.
For an https:// destination, the client always asks the proxy for a CONNECT tunnel and then runs TLS with the destination inside it. That part is the same whatever the proxy URL says. The CONNECT explainer walks through those bytes. What changes with an https:// proxy URL is the layer under the tunnel. The client opens a TLS session with the proxy first, and everything it says to the proxy goes inside that session.
| Proxy URL | Destination | Proxy credentials | Request content |
|---|---|---|---|
http:// | https:// | Readable (base64) | Encrypted by your TLS to the destination |
https:// | https:// | Encrypted | Encrypted twice (TLS inside TLS) |
http:// | http:// | Readable (base64) | Readable, full request |
https:// | http:// | Encrypted | Encrypted to the proxy, plain after it |
The first row is the common setup, and it is why many engineers assume a plain proxy is safe for HTTPS. Your API payloads are safe in that row. Your proxy password is not.
Why cleartext proxy credentials matter
Proxies authenticate with the Proxy-Authorization header, most often with the Basic scheme. Basic is base64, which is an encoding, not encryption. RFC 7617 says plainly that Basic results in the cleartext transmission of the password and should not be used without something like TLS around it. Oracle's Java networking guide uses nearly the same words for proxies.
Here is the header curl sent in a test through a local proxy with the user app and the password secret, and what one shell command turns it back into.
> CONNECT example.com:443 HTTP/1.1
> Host: example.com:443
> Proxy-Authorization: Basic YXBwOnNlY3JldA==
$ echo 'YXBwOnNlY3JldA==' | base64 -d
app:secretA fixed-IP egress proxy raises the stakes. The whole point of the proxy is that a bank, broker, or partner API trusts its IP address. Anyone who captures the token can send traffic from that trusted address, from anywhere. The partner's allowlist then admits them, and the logs show your IP.
Who sits on that first hop depends on where your code runs. It can be a hosting platform's shared network, a cloud provider's backbone, a corporate network with inspection boxes, or public Wi-Fi on a developer laptop. You rarely control all of it. An https:// proxy URL removes the question, because nothing readable crosses the hop.
TLS to the proxy also hides the CONNECT line itself from the network. That matters less than it sounds, since the TLS handshake inside the tunnel carries the destination name in SNI to the proxy anyway. The credentials are the real gain.
What happens on an https:// proxy connection
- 1TCP to the proxyThe client connects to the proxy host. curl assumes port 443 for an
https://proxy without a port, per Everything curl. Defaults differ between clients, so write the port in the URL. - 2TLS with the proxyThe client sends SNI for the proxy's host name and verifies the proxy's certificate against its trust store. This is a separate check from the destination's certificate.
- 3CONNECT inside TLSThe client sends
CONNECT api.partner.example:443and theProxy-Authorizationheader inside the encrypted session. The proxy decrypts this layer, checks the credentials, opens a TCP connection to the destination, and replies200. - 4TLS with the destination, inside the first TLSThe client starts a second handshake with the destination through the tunnel. The proxy relays those records without keys for them. Your request and response travel encrypted twice on the first hop and once after the proxy.
The extra cost is one more TLS handshake each time the client opens a new connection to the proxy. A client that keeps connections alive pays it once and then sends many requests through the same tunnel. Create the agent or client once and reuse it, especially on serverless platforms where each cold start already pays for new connections.
Running TLS inside TLS needs the client library to layer one session on another. Some runtimes could not do that for years. asyncio before Python 3.11 is one example, and it explains the aiohttp row in the next section. The TLS passthrough post covers what the proxy can still see once the inner session is up.
Which clients support HTTPS proxies
Support is wide on current versions and patchy on older ones. The version floors below come from each project's release notes and from the Fixedmark language guides, which were tested against a TLS-wrapped CONNECT proxy.
| Client | https:// proxy | Notes |
|---|---|---|
| curl and libcurl | Yes, since 7.52.0 | Added in December 2016 per the curl changelog. Works with OpenSSL, GnuTLS, and, from 7.87.0, mbedTLS, Rustls, Schannel, and wolfSSL. |
| PHP cURL and Guzzle | Yes, with libcurl 7.52.0+ | Check CURL_VERSION_HTTPS_PROXY in curl_version(). See the PHP guide. |
Node.js undici ProxyAgent | Yes | TLS to the proxy, then CONNECT, per the undici docs. |
| Node.js built-in proxy | Yes, 22.21+ and 24.5+ | NODE_USE_ENV_PROXY=1 with HTTPS_PROXY. The Node docs list both http and https proxy URLs. |
Node.js https-proxy-agent | Yes | For the https module, axios, and SDKs that take an agent. See the Node guide. |
| Python requests | Yes, with urllib3 1.26+ | urllib3 1.26.0 added HTTPS proxies to HTTPS servers, per its changelog. |
| Python httpx | Yes | Use 0.28 or later and the proxy argument. See the Python guide. |
| Python aiohttp | Yes, on Python 3.11+ | Older asyncio cannot run TLS inside TLS. The aiohttp docs call the support limited. |
Go net/http | Yes, since Go 1.10 | Per the Go 1.10 release notes. See the Go guide. |
Deno and Bun fetch | Yes | Deno through Deno.createHttpClient, Bun through the proxy fetch option. See the Deno and Bun guide. |
| Ruby Typhoeus | Yes | Runs on libcurl. See the Ruby guide. |
Ruby Net::HTTP and Faraday's default adapter | Partial | net-http 0.5.0 added TLS to the proxy, but HTTPS destinations still failed in testing. |
Java HttpClient and HttpURLConnection | No | Connects to proxies over plain TCP only. See the Java guide. |
Here is the same call in each language that supports it. The proxy URL comes from an environment variable in the form https://USER:TOKEN@proxy.example.com:443. Percent-encode the token if it contains reserved characters.
curl -v --proxy "$PROXY_URL" https://api.partner.example/v1/statusimport { fetch, ProxyAgent } from "undici";
// Create once at module scope and reuse.
const proxy = new ProxyAgent(process.env.PROXY_URL);
const res = await fetch("https://api.partner.example/v1/status", {
dispatcher: proxy,
});
console.log(res.status);import os
import requests
proxy = os.environ["PROXY_URL"]
r = requests.get(
"https://api.partner.example/v1/status",
proxies={"http": proxy, "https": proxy},
timeout=15,
)
print(r.status_code)package main
import (
"fmt"
"net/http"
"net/url"
"os"
"time"
)
func main() {
proxyURL, err := url.Parse(os.Getenv("PROXY_URL"))
if err != nil {
panic(err)
}
client := &http.Client{
Transport: &http.Transport{Proxy: http.ProxyURL(proxyURL)},
Timeout: 15 * time.Second,
}
res, err := client.Get("https://api.partner.example/v1/status")
if err != nil {
panic(err)
}
defer res.Body.Close()
fmt.Println(res.StatusCode)
}<?php
$ch = curl_init('https://api.partner.example/v1/status');
curl_setopt_array($ch, [
CURLOPT_PROXY => getenv('PROXY_URL'),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 15,
]);
curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), PHP_EOL;require "typhoeus"
res = Typhoeus.get(
"https://api.partner.example/v1/status",
proxy: ENV.fetch("PROXY_URL"),
timeout: 15
)
puts res.codeWhen a client that cannot do TLS to a proxy is pointed at a TLS port, it sends plain text into a TLS listener. The result is a handshake error, a reset, or a hang, rarely a clear message. The proxy error codes guide covers how to tell these apart with curl -v.
Trusting the proxy's certificate
A proxy with a certificate from a public CA needs no extra setup. Every client above verifies it against the default trust store. A proxy with a private CA, common inside companies, needs that CA on the proxy hop. Each client exposes this differently, and the differences cause real bugs.
- curl keeps the two hops apart.
--proxy-cacertsets trust for the proxy only, and the curl man page describes it as a different trust for the proxy compared to the remote server.--cacertstill applies to the destination. - PHP has the same split through
CURLOPT_PROXY_CAINFO, which the PHP manual says is for connecting to an HTTPS proxy, not an HTTPS server. - undici takes
proxyTlsfor the proxy hop andrequestTlsfor the destination.https-proxy-agentpasses its TLS options, such asca, to the proxy connection. - httpx takes an
ssl_contextonhttpx.Proxy, separate from the client'sverifysetting. - requests has no separate option. In a test with requests on urllib3 2.x, the
verifybundle was used for both hops. Pointing it at the private CA alone made the destination fail, so the bundle must hold the public roots plus your CA. - Go uses one
TLSClientConfigfor both hops. Add your CA toRootCAson top of the system pool. Do not setServerName, because Go then checks that name against the proxy's certificate too.
// Breaks the proxy hop. ServerName is used for BOTH handshakes.
tr := &http.Transport{
Proxy: http.ProxyURL(proxyURL),
TLSClientConfig: &tls.Config{ServerName: "example.com"},
}
// Get "https://example.com": proxyconnect tcp: tls: failed to verify
// certificate: x509: certificate is valid for localhost, not example.comNever fix a proxy certificate error by turning verification off with --proxy-insecure, CURLOPT_PROXY_SSL_VERIFYPEER set to false, or rejectUnauthorized: false. The curl man page warns that it makes the transfer to the proxy insecure. An attacker on the path can then present any certificate, collect your token, and you are back to cleartext with extra steps.
HTTPS_PROXY names the destination, not the proxy
The variable HTTPS_PROXY means the proxy to use for HTTPS destinations. It says nothing about how to reach the proxy. The curl man page defines it as the proxy server to use for HTTPS. The value is a URL, and its own scheme picks the hop. So both of these are valid and do different things.
# HTTPS destinations through a plain proxy. Credentials in cleartext.
export HTTPS_PROXY="http://USER:TOKEN@proxy.example.com:8080"
# HTTPS destinations through a TLS proxy. Credentials encrypted.
export HTTPS_PROXY="https://USER:TOKEN@proxy.example.com:443"The same confusion shows up in Python. The https key in a requests proxies dict selects HTTPS destinations, and its value can be an https:// proxy URL. The requests docs show http:// values in their examples, and the httpx proxy docs advise http:// because most proxies only support that. Those examples describe typical corporate proxies. They do not mean an https:// value is wrong.
Watch for a missing scheme. Go's ProxyFromEnvironment accepts a bare host:port and assumes http. curl treats a proxy with no scheme as an HTTP proxy. If a deploy script strips https:// from the value, nothing errors. The client quietly sends your token in cleartext to a port that expects TLS, and the request fails in a confusing way. Keep the full URL, scheme and port included.
Global variables also proxy calls you did not mean to proxy. Per-client configuration avoids that, as the post on NO_PROXY and per-client agents explains.
When a client cannot do TLS to the proxy
Java is the big gap. java.net.http.HttpClient takes a ProxySelector that returns a host and port, and it always connects there over plain TCP. A write-up of the JDK source traces this to the tunnel classes, and Maven's transporter known issues list no TLS proxy support for the JDK client. The JDK also disables Basic auth for CONNECT tunnels by default through jdk.http.auth.tunneling.disabledSchemes, so a plain proxy returns 407 until you clear that property. Ruby's Net::HTTP is the other common case, as the Ruby guide describes.
You have three practical options, from best to worst.
- Switch the allowlisted calls to a client that supports
https://proxies. In Ruby, Typhoeus covers this. In Java, check your third-party HTTP client's documentation and test it against a TLS proxy before relying on it. - Wrap the hop in TLS locally. A small forwarder on
127.0.0.1accepts the plain connection and opens TLS to the proxy, so cleartext never leaves the machine. Thesocatcommand below did this for Java'sHttpClientin a test, and it verified the proxy's certificate and host name by default. - Use the plain proxy port and limit the damage. Restrict what the credential can reach, rotate it on a schedule (see rotating proxy credentials), and keep the hop inside networks you trust as far as you can.
# Listens in plain text on loopback, speaks TLS to the proxy.
socat TCP-LISTEN:3128,bind=127.0.0.1,reuseaddr,fork \
OPENSSL:proxy.example.com:443
# Point the client at 127.0.0.1:3128 as a plain HTTP proxy.
# Java HttpClient also needs Basic auth for tunnels turned back on:
# -Djdk.http.auth.tunneling.disabledSchemes=The wrapper runs as a sidecar process next to your app. It suits a VM or container you control. It does not fit platforms where you cannot run a second process.
Check which kind of proxy hop you have
Run curl -v with your proxy URL and read the lines before CONNECT. A TLS proxy hop shows a handshake and a Proxy certificate block first, then the CONNECT request, then a second handshake with the destination's Server certificate. A plain hop goes straight from the TCP connection to CONNECT, with no proxy certificate in between.
* Proxy certificate:
* subject: CN=localhost
* issuer: CN=Test Proxy CA
* Establishing HTTP proxy tunnel to example.com:443
> CONNECT example.com:443 HTTP/1.1
< HTTP/1.1 200 Connection Established
* CONNECT tunnel established, response 200
* Server certificate:
* subject: CN=example.comThen check your application, not only curl. Log the proxy URL's scheme and port at startup with the credentials masked, and fail fast if the scheme is not https. It is one line of code and it catches the stripped-scheme bug before it reaches production.
Doing this with Fixedmark
Fixedmark, in early access, gives outbound calls a fixed pair of static IPs that partners allowlist. Its proxy URL is an https:// endpoint, so the default setup already encrypts the token on the first hop. The concepts page covers the details.
- The HTTP proxy over TLS listens on port 443, in the form
https://APP_ID:TOKEN@mum.egress.fixedmark.com:443. SOCKS5 over TLS listens on port 1443. - Ports 8080 (HTTP) and 1080 (SOCKS5) are plain, for clients that cannot do TLS. They send the token in cleartext, so use them only when you have to.
- A destination allowlist restricts a credential to the hosts and ports you name, such as
api.razorpay.com:443. A leaked token from a plain port then cannot reach anything else. fm tunnelforwards local ports to databases and TCP services over TLS, for drivers with no proxy support. See the CLI reference.- The proxy passes your TLS session with the destination through without decrypting it. The security page explains what is logged.
The Node, Python, Go, PHP, Ruby, Deno and Bun, and Java guides show the tested setup for each client. If a call fails at the TLS step, the troubleshooting guide lists the symptoms of a client that does not support https:// proxies.
Sources
Checked November 2026. Confirm current details on the vendor's site before you decide. Prices and limits change.
- RFC 7617: The Basic HTTP Authentication Scheme
- curl: command line manual (proxy and proxy TLS options)
- curl: changelog, 7.52.0 adds HTTPS proxy support
- Everything curl: HTTPS proxy
- undici: ProxyAgent documentation
- Node.js: built-in proxy support
- urllib3: changelog, 1.26.0 HTTPS proxy support
- Requests: advanced usage, proxies
- HTTPX: proxies
- aiohttp: advanced client usage, proxy support
- Go 1.10 release notes: https proxy URLs
- Go: net/http ProxyFromEnvironment
- PHP manual: cURL constants
- Oracle: Java networking properties
- Maven Resolver: transporter known issues
- DEV: HttpClient can't connect to a TLS proxy

