Skip to content
Mittelware

Documentation

Learn Mittelware

Everything you need to go from first launch to confident rule-writing.

HTTPS & certificates

How Mittelware inspects HTTPS traffic with its own certificate authority, what trusting it means, how to keep chosen hosts out of it with the bypass list, and how to remove the certificate.

Most traffic is encrypted. To show it to you, Mittelware needs your device to trust its certificate.

In plain terms: HTTPS scrambles the data between an app and a server so nobody in between can read it. Mittelware is you choosing to sit in between on your own computer, so it needs your permission to unscramble your own traffic. That permission is a certificate: a small file, made on your computer, that your computer is told to trust. (New to these terms? See Start here.)

How it works#

Mittelware creates its own certificate authority named Mittelware CA on your computer. When an application opens an HTTPS connection, Mittelware presents a certificate for that site signed by this authority, reads the traffic, then makes its own connection to the real server. Because your device trusts Mittelware CA, applications accept the connection without warnings.

  • The certificate and its private key are generated locally and never leave your device.
  • It's trusted for your user account on this device only: in the Current User trusted roots on Windows, and the login keychain on macOS. Nothing changes for other devices on your network.
  • Connections from Mittelware to real servers are verified normally, against your system's trust store.

Trusting the certificate#

The first time you switch Mittelware on, it asks whether to monitor HTTPS too. Choose Trust & Monitor HTTPS. Windows asks you to confirm installing the certificate; on macOS you'll be asked to authenticate (if you've also enabled the system proxy, the two requests are combined so you're only prompted once). You can also manage this from Settings.

If you'd rather not, choose Monitor HTTP Only. Mittelware then only sees unencrypted HTTP, and HTTPS requests pass through without being inspected.

To check where you stand, open Settings. The Trust certificate for HTTPS card shows whether the certificate is trusted. It carries a Trusted badge when it is, and a Trust button when it isn't:

The Settings page on the Proxy tab, with the Trust certificate for HTTPS card marked 4 and reading Trusted, HTTPS interception is ready.
Card 4 is the one to check: Trusted means HTTPS interception is ready.

Certificate warnings#

If a browser warns that a connection isn't private while Mittelware is running, the certificate isn't trusted for that application. Trust it from Settings and restart the browser. Firefox keeps its own certificate store on some setups, so it may need the certificate imported separately.

Runtimes with their own certificate list#

Browsers and tools that use the operating system's store trust Mittelware CA once you've trusted it. Some runtimes ship their own list of authorities and ignore the system store. For those, point them at the certificate file (mittelware-ca.pem, kept in the app's data folder):

# Node.js
export NODE_EXTRA_CA_CERTS=/path/to/mittelware-ca.pem

# Python requests
export REQUESTS_CA_BUNDLE=/path/to/mittelware-ca.pem

# curl, for a single call
curl --cacert /path/to/mittelware-ca.pem -x http://127.0.0.1:8080 https://example.com

The bypass list#

Some connections can't survive being inspected. An app that pins its server's certificate refuses the one Mittelware presents, and a sign-in that is tied to the encrypted connection itself (a client certificate, Kerberos or NTLM, a device check) breaks when something re-terminates it. For those hosts the right behaviour is to leave the connection alone: Mittelware relays the bytes between the app and the server without decrypting them.

The bypass list is where you say which hosts get that treatment. It is the Bypass domains card on the Proxy tab of Settings.

The Bypass domains card in Settings: its one-line description, a count of 22 entries marked 1, and an Edit list button marked 2.
The card shows how many entries are in force. Edit list opens the editor.
  1. The number of entries that are saved and active.
  2. Edit list opens the editor.
The bypass list editor: a panel with the rules for writing an entry at the top, and a text box below it with numbered lines of comments and host names such as login.microsoftonline.com.
One entry per line. Lines that start with # are comments.

What goes in it#

One entry per line. A line that starts with #, or anything after a #, is a comment.

Entry Matches
example.com The host and every subdomain of it
*.example.com Subdomains only, not example.com itself
example.com:8443 Only connections to that port
10.1.2.3 or ::1 Exactly that address
10.0.0.0/8 Every address in that range

Case doesn't matter, and a pasted address such as https://example.com/path is reduced to its host.

Saving#

The editor checks the list as you type and points at any line it can't read, with the reason. A list with a mistake can't be saved, so a typo never leaves a site quietly broken. Save applies the list straight away, to the very next connection.

What it ships with#

A fresh install starts with a list of the sign-in providers organisations use (Microsoft, Google, Apple, Okta, OneLogin, Ping, Duo) and the operating-system update services, which are pinned and not worth reading. Identity platforms that developers build on, such as Auth0 and Amazon Cognito, are in the list as commented-out examples, because debugging your own sign-in is exactly when you want to see it. Remove the # to bypass one.

Once you save a list of your own, it is exactly what you saved. Future versions don't add to it.

What you see#

  • A bypassed connection shows in Flows as a single CONNECT row, whose details explain that it matched the bypass list. Nothing inside it is shown, and no rule applies to it. That includes WebSockets: a wss:// connection to a bypassed host has no Messages tab.
  • Only HTTPS is affected. Plain http:// traffic to the same host is inspected as usual.
  • On Windows, with System proxy on, host entries are also excluded from the system proxy itself. Applications that follow it then connect to those hosts directly, so they don't appear in the flow list at all, plain HTTP included. Ranges and entries with a port are handled by Mittelware only.

TIP

If a site you are debugging shows up as a lone CONNECT row, or doesn't show up at all, look in the bypass list first. Put a # in front of its line, save, and reconnect.

What can't be inspected#

  • Apps that pin their own certificates, which refuse any certificate other than the one they expect. If one of them is a sign-in or update service you rely on, add its host to the bypass list so it works as it did before.
  • Apps that ignore the operating system's proxy settings.
  • Bodies over 32 MB aren't captured. A response that arrives in pieces (text/event-stream and similar) is followed live, chunk by chunk: see Streaming responses. HTTPS streams work once the certificate is trusted.

Removing the certificate#

You can remove trust at any time by deleting Mittelware CA from your operating system's certificate store:

  • Windows: run certmgr.msc, open Trusted Root Certification Authorities → Certificates, and delete Mittelware CA.
  • macOS: open Keychain Access, select the login keychain, find Mittelware CA under Certificates, and delete it.

After removal, HTTPS traffic can no longer be inspected until you trust the certificate again. Questions? Get in touch.