ReqResReqRes
Skip to content
Docs menu · Change traffic

Change traffic

New in 1.1

Keep SSL-pinned apps working

On this page

Some apps check their servers' certificates themselves and accept only the ones they expect. This is SSL pinning, and such an app refuses ReqRes's certificate even when you trust it. ReqRes passes those connections through without decrypting them, so the app keeps working while you capture, and lists each one as a row marked SSL pinned.

This applies once the ReqRes certificate is trusted. Before that, ReqRes decrypts no HTTPS, so each HTTPS connection is a relayed row marked not decrypted, pinned or not.

What happens when an app refuses the certificate

The first request that meets a new pin fails. It is a Failed row naming the host and the app, and its cause ends: "ReqRes now passes this app's connections to whatsapp.net through untouched, marked SSL pinned — try again in the app."

ReqRes remembers the app and the host's domain. For media-dub4-1.cdn.whatsapp.net, the domain is whatsapp.net, because a pinning app often picks a new server on each try. When you try again in the app, its connections to that domain pass through untouched, and each one is a row marked "SSL pinned by WhatsApp".

  • An alert from the app counts at once. A bare hang-up during the TLS handshake counts only when it repeats within 30 s, because a browser's spare connection looks the same.
  • A handshake that fails for another reason, such as no cipher in common, is not pinning. ReqRes does not remember it.
  • The pin covers that app only. Another app reaching the same domain, such as Safari, is still decrypted.
  • If ReqRes could not tell which app made the connection, it remembers the domain for any app.

The row's banner says what ReqRes remembered: "ReqRes remembered this: WhatsApp's connections to whatsapp.net now pass through untouched, marked SSL pinned — try again in the app. Forget it to try decrypting again." A Forget button sits below it.

Read an SSL-pinned row

An SSL-pinned row is a connection, not a request. It is written when the connection closes.

  • The Code column shows a pin. The URL column shows the endpoint, such as media-dub4-1.cdn.whatsapp.net:443, then "SSL pinned by WhatsApp" and the bytes sent and received.
  • The detail explains why, then lists Endpoint, Protocol (relay/tcp), SSL pinned by, Server, Sent, Received, Opened, Closed and Open for.
  • It has no method, status, headers or body. Nothing inside a pinned connection can be read by any proxy.
  • No rule or breakpoint applies to it.
  • Opening it never uses one of the free version's HTTPS inspections. Neither does opening the Failed row.

Type proto:relay in the search field to list relayed connections, or outcome:failed to find the refusals. See why a request failed covers Failed rows.

Apple services macOS pins

macOS keeps its own pinning list. For the Apple services on it, any app on the Mac accepts only a certificate Apple issued, so no proxy can decrypt them. ReqRes has a copy of that list and relays those hosts from the first connection, so nothing fails.

  • The row reads, for example, "SSL pinned by macOS · iCloud". The detail names the service and macOS's policy for it, such as "iCloud (MMCS)".
  • Rows name these services: iCloud, iCloud Keychain, the App Store and Apple media, Apple push notifications, Find My, iMessage and FaceTime, Apple Pay, Software Update, Siri, the Apple Account, Game Center, Shazam, Weather, Maps and Location, Health and device activation. Other hosts on the list read "an Apple service".
  • These hosts are not in the SSL-pinned apps list and cannot be forgotten. The detail says: "Nothing to fix: this is macOS's rule, not a ReqRes setting, and installing a certificate does not change it."

Forget an app

  1. Open Settings ▸ Capture.
  2. Scroll to SSL-pinned apps.
  3. Click Forget beside the app, or Forget All below the list.

Each entry shows the app, the domain and when ReqRes learned it. An entry learned without an app reads Any app. With nothing learned, the section reads "No app has refused ReqRes's certificate yet."

  • Forget an app to try decrypting it again, after the app changes or if the refusal was a one-off. If the app still pins, its next connection fails again and ReqRes remembers it again.
  • ReqRes keeps the list between launches and applies it each time capture starts. It applies it again when it reconnects to a capture that kept running after ReqRes quit unexpectedly, and adds any app that refused the certificate in the meantime.

Exclude a host instead

Exclude the host instead when you know it pins and want no failure, when you want no rows for it at all, or when it should pass through for any app. An excluded host is checked first, so it is never marked SSL pinned. See Pass a host through untouched.

  • A Failed row whose refusal ReqRes did not remember offers Exclude api.example.com… in its banner. It asks "Stop recording api.example.com?" first.
  • For a command-line tool, the banner first offers Export the CA and the environment lines…. A tool that refuses the certificate usually reads its trusted certificates from a file. ReqRes remembers that refusal like any other, so once the tool trusts the ReqRes CA, click Forget in the banner or in Settings ▸ Capture ▸ SSL-pinned apps. Until then its connections to that domain stay relayed, marked SSL pinned. See Capture command-line tools and agents.
  • To pass a host macOS pins through without a row, exclude it too.

What an agent sees

  • list_sessions outcome=failed lists the refusals, with the phase tlsClient.
  • Each relayed pinned connection is a kind=relay row, found with proto=relay. After the endpoint it reads (SSL pinned by WhatsApp) or (SSL pinned by macOS · iCloud), then the bytes each way and how long it was open. get_session gives the same explanation as the app.
  • diagnose_setup has a tls_rejections check, "Apps refusing ReqRes's certificate". It warns with each host and app and how many times it refused, and suggests exclude_host, which you approve every time. For an app ReqRes remembered, trying again in the app is enough.
  • capture_status and diagnose_setup list both cases as relayed in their protocol list: "Apps that pin their certificate" and "Apple services macOS pins".
  • No MCP tool reads or changes the SSL-pinned apps list. Only you forget an app, in Settings ▸ Capture or with Forget on its Failed row.

See MCP tools.

Related