SSL — SSL/TLS Decryption Module

Note

SSL module is currently only available in beta and for macOS 10.12 minimum.
You can enable beta updates inside Debookee in Menu Debookee -> Preferences -> General -> Propose beta version updates
Then force update with Menu Debookee -> Check for Updates...

Check out this blog post for more informations.

The SSL module is an extension of NA Module which allows HTTPS decryption of your own traffic and intercepted targets by setting an HTTPS man-in-the-middle proxy.

By default, TLS decryption is not enabled. Debookee can run in 3 modes:

  • No TLS decryption
  • TLS decryption for targets only
  • TLS decryption for Own Traffic and all the intercepted targets

How it works

  1. We intercept the client HTTPS connection (Client->Debookee)
  2. Create it’s own HTTPS connection to the server (Debookee->Server)
  3. Retrieve some data from the server & decrypt them
  4. Create on-the-fly a fake certificate impersonating the server, created from Debookee’s Certificate Authority (CA)
  5. Send the fake certificate to the client and establish Client->Debookee TLS connection
  6. Send the data to the client

Clients SSL/TLS warnings/failures

Most HTTPS clients (browsers, applications, email clients...) will detect Debookee’s fake certificates and will behave differently, depending their capabilities.

A solution to avoid those warnings can be the installation of Debookee’s Certificate Authority on the client.

By default, without Debookee’s CA, reactions to the fake certificate could be:

  1. Clients present a warning and propose to accept the fake certificate
  2. Clients present a fatal alert and deny the connection in case of Key Pinning
  3. Clients TLS connections fails silently

Examples

_images/module_ssl_chrome_no_hpkp.png

CA certificate is not installed on client and debookee.com doesn’t implement Key Pinning -> Chrome proposes you to proceed with fake certificate

_images/module_ssl_chrome_hpkp.png

CA certificate is not installed on client and google.com uses Key Pinning -> no way to access the website

Key Pinning

Some clients implement HTTP Public Key Pinning, a security mechanism which prevents impersonation of a TLS server.

Key Pinning can be strict or not. When strict, even if the CA is installed, the client won’t accept to establish the impersonated TLS connection. In a future release, Debookee will implement a white-list to avoid decryption of some connections involving strict Key Pinning.

Installation of Debookee’s Certificate Authority (CA)

Target traffic decryption

If you intercept a target traffic and want to decrypt its traffic, by default, the client’s browser will warn you of the MITM attempt. In that case, you need to install the Debookee’s Certificate Authority on the target (not on the Mac running Debookee).

You can access the certificate with the following steps:

  1. Select a target
  2. Start NA module, target’s traffic must be intercepted
  3. On the target, run a browser on http://mitm.it:6969
  4. Follow the steps on the following website to install the CA on the target
_images/module_ssl_certinstall_webpage.png

The webpage is proposed by mitmproxy which is internally used in Debookee for the SSL/TLS decryption.
If you want to learn more about this incredible project, you can checkout their very complete documentation..

Own Traffic decryption

To decrypt your Own Traffic without browser’s warnings, you need to install the CA on the Mac running Debookee.
You don’t need to manually install certificate in the Keychain, this can be done automatically in Debookee by pressing Add CA cert to Keychain.

Press Remove CA cert from Keychain to disable automatic decryption of your traffic and bring back warnings.

If you need to have access to the certificates for Private certificate store, life for targets, you can browse http://mitm.it:6969 from a browser on the Mac running Debookee.

Private certificate store

Target traffic decryption and Own Traffic decryption allows you to install a CA certificate into the system certificate store of the OS. (macOS Keychain, Windows, Android certificate store, etc ...)

Some applications are not using the OS certificate store, but instead have their own, like Firefox or Thunderbird.

In that case, you will have to install manually Debookee’s CA certificate inside the private certificate store.
You’ll find the CA file by downloading it from http://mitm.it:6969.