HTTPS Decryption (MITM)
Surge can decrypt HTTPS traffic with a man-in-the-middle (MITM) attack, so that the HTTP processing features can work on HTTPS requests. See the Wikipedia article for background on the technique.
A minimal configuration looks like this:
[MITM]
ca-p12 = MIIJtQ.........
ca-passphrase = password
hostname = *.google.com
h2 = true
Surge only decrypts traffic to hosts declared in hostname.
CA certificate
To perform MITM, Surge needs a CA certificate that the system trusts.
The certificate generator can generate a new CA certificate for debugging and make it trusted by the system. It is available in Surge Dashboard (Mac version) and the Surge iOS Config Editor. The certificate is generated locally and saved only in your profile and the system Keychain. The key of the new certificate is generated randomly using OpenSSL.
You can also use an existing CA certificate. Export the certificate to PKCS#12 format (.p12) with a passphrase. The passphrase cannot be empty due to system limitations. Use the base64 command to encode the certificate, then set ca-p12 and ca-passphrase in the profile.
Some applications use certificate pinning and refuse any certificate not issued by the expected CA. Enabling decryption for these hosts breaks their connections. If a client completes the TLS handshake but disconnects without sending a request, Surge logs a hint that the host is likely protected by certificate pinning.
Parameters
hostname: Host List
The list of hosts to decrypt. This parameter is of the Host List parameter type; the default port is 443:
- Wildcards
*and?are supported. - Use the
-prefix to exclude a host. Items are matched in order, so put exclusions first:hostname = -*.apple.com, -*.icloud.com, *decrypts everything except Apple and iCloud hosts. - A bare
example.comentry matches port 443 only. Useexample.com:8443to match another port, orexample.com:0to match all ports. - When the client gives Surge only an address and the hostname comes from the SNI instead, a bare entry matches whatever port the connection used. For QUIC that always applies, since the SNI is read from every ClientHello. For TLS it depends on Surge looking inside the connection at all, which it does on ports 80 and 443, or when the address and port already match this list or
force-http-engine-hosts; on any other port the connection is forwarded without being inspected, so a bare entry does not reach it. Add the port (example.com:8443) to decrypt there. - Special tokens like
<ip-address>and<simple-hostname>are available; see the Host List reference.
An invalid entry in the list produces a profile warning instead of a parse error, so a single typo does not prevent the profile from loading.
hostname-disabled: Optional, Host List
Entries in this list are removed from the effective hostname list. Surge's UI uses this key to temporarily disable a hostname without deleting it from the profile; you may also edit it manually.
ca-p12: Optional, string
The CA certificate and private key in PKCS#12 format, base64-encoded.
ca-passphrase: Optional, string
The passphrase of the PKCS#12 data. It cannot be empty due to system limitations.
ca-keystore-name: Optional, string
Use a certificate stored in the Keystore section instead of an inline ca-p12. The value is the name of a Keystore item of p12 type. When set, it takes precedence over ca-p12.
server-certificates: Optional, list iOS 6.0.0+ Mac 6.11.0+
Present your own certificate for specific hosts, instead of one generated and signed by the CA. This helps when you debug an app whose domains and certificates you control, and the app rejects certificates from user-installed CAs or pins its certificate or public key.
[MITM]
hostname = api.example.com, *.dev.example.com
server-certificates = api.example.com:api-cert, *.dev.example.com:dev-cert
[Keystore]
api-cert = type=p12, base64=<P12 base64 string here>, password=123456
dev-cert = type=p12, base64=<P12 base64 string here>, password=123456
- Each entry is
hostname:keystore-item-name, and entries are separated by commas. The keystore item must be of p12 type and contain the certificate with its private key. Include the intermediate certificates in the p12 file; Surge sends them to the client in the correct order. A password-less p12 file is supported, but then settype=p12on the Keystore item explicitly. - The hostname supports the
*and?wildcards, matched against the SNI. It doesn't take a port. - Entries are matched in order, and the first matching entry is used. If that entry's certificate can't be loaded, Surge logs a warning and falls back to a certificate signed by the CA.
- This parameter only selects the certificate. A host is decrypted only if it also matches
hostname. - In Surge's wildcard syntax,
*also matches dots, while a certificate's wildcard covers only one level. For example, the entry*.dev.example.commatchesa.b.dev.example.com, but a certificate for*.dev.example.comdoesn't cover that host. Surge still presents it, so the client rejects it, and Surge logs a warning. - A CA certificate is still required to turn on MITM.
To convert a PEM certificate and its private key to a p12 file:
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -out cert.p12
base64 -i cert.p12
skip-server-cert-verify: Optional, Boolean, default: false
Do not verify the certificate of the remote server while performing MITM. This relaxes verification of the real server only; the client side still receives the Surge-generated certificate.
h2: Optional, Boolean, default: false
MITM over HTTP/2: decrypt HTTPS traffic with MITM over the HTTP/2 protocol, which can improve the performance of concurrent requests.
client-source-address: Optional, list
Enable the MITM function for specific client devices only.
- This is a list parameter using commas as the separator.
- You may specify a single IP address or use a CIDR block. Both IPv4 and IPv6 are supported.
- You may use the
-prefix to exclude some clients, e.g.client-source-address = -192.168.1.2, 0.0.0.0/0. - If the parameter is not set, MITM is enabled for all clients. This is equivalent to
client-source-address = 0.0.0.0/0, ::/0. 127.0.0.1should be included if you want to enable MITM for the current device.- Since Surge Mac version 6.1.0, this parameter can use MAC addresses to match specific clients.
auto-quic-block: Optional, Boolean, default: true iOS 5.8.0+ Mac 5.4.0+
When a QUIC connection (i.e. HTTP/3) hits the MITM hostname list, Surge automatically blocks that QUIC connection, causing the client to fall back to HTTP/2 or HTTP/1.1 so the traffic can be intercepted by MITM.
In the app, this option is the Automatically Block QUIC switch in the MITM settings. It only affects QUIC connections to MITM hostnames, and takes effect even when block-quic = always-allow. To block QUIC traffic regardless of MITM, use the block-quic option in [General] or the block-quic policy parameter.