21.09.2019 - Frank Ganske, about this abandoned repository and new versions

Unfortunately I've lost my PGP private key for uploading Maven artifacts to the Central Repository. So version 1.1.0 will be the last I think.

LittleProxy - Man-In-The-Middle

LittleProxy-mitm is an extension for LittleProxy which provides all the filter capabilities of LittleProxy with HTTPS sites too. It aims to support every Java platform including Android. To answer HTTPS while offline for caching purposes consider to use ganskef/LittleProxy-parent. See Aldo Cortesi for a detailed description of proxy interception processes.

Get it up and running

Java is required to be installed on the system, then execute this commands:

$ java -jar littleproxy-mitm-1.1.0-shade.jar
$ curl --cacert littleproxy-mitm.pem --verbose --proxy localhost:9090 https://github.com/

The first run creates the key store for your Certificate Authority. It's used to generate server certificates on the fly. The littleproxy-mitm.pem file have to be imported in your browser or within the systems certificates, Mozilla for example:

You have to set your browsers proxy settings to 9090. It's hard coded in the simple Launcher class. You may chose an other implementation, of course.

Important Security Note

Please use your browser directly for every security-critical transmission. Mozilla Firefox and Google Chrome implements her own certificate handling for a reason. Handling security in Java like here must be less secure in most situations. See http://www.cs.utexas.edu/~shmat/shmat_ccs12.pdf "The Most Dangerous Code in the World: Validating SSL Certificates in Non-Browser Software".

Getting the library

Add this dependency to your Maven build:

<dependency>
   <groupId>com.github.ganskef</groupId>
   <artifactId>littleproxy-mitm</artifactId>
   <version>1.1.0</version>
</dependency>

The version corresponds to LittleProxy since the intention was to integrate it as a module.

Wiring everything together

Once you've included LittleProxy-mitm, you can start the server with the following:

HttpProxyServer server =
    DefaultHttpProxyServer.bootstrap()
        .withPort(9090) // for both HTTP and HTTPS
        .withManInTheMiddle(new CertificateSniffingMitmManager())
        .start();

Please give an Authority in the constructor to personalize your application. You impersonate certificates which is normally a bad thing. You have to describe the reason for.

Please refer to the documentation of LittleProxy and Netty especially the Javadoc of org.littleshoot.proxy.HttpFiltersSource, org.littleshoot.proxy.HttpFilters and io.netty.channel.ChannelPipeline to filter HTTP/S contents. FAQ: #25, #32

Resolving URI in case of HTTPS

Mostly you will need an URL to handle content in your filters. With HTTP it's provided by originalRequest.getUri(), but with HTTPS you have to get the host name from the initiating CONNECT request. Therefore you have to do something like this in your HttpFiltersSource implementation:

    private static final AttributeKey<String> CONNECTED_URL = AttributeKey.valueOf("connected_url");

    @Override
    public HttpFilters filterRequest(HttpRequest originalRequest, ChannelHandlerContext clientCtx) {
        String uri = originalRequest.getUri();
        if (originalRequest.getMethod() == HttpMethod.CONNECT) {
            if (clientCtx != null) {
                String prefix = "https://" + uri.replaceFirst(":443$", "");
                clientCtx.channel().attr(CONNECTED_URL).set(prefix);
            }
            return new HttpFiltersAdapter(originalRequest, clientCtx);
        }
        String connectedUrl = clientCtx.channel().attr(CONNECTED_URL).get();
        if (connectedUrl == null) {
            return new MyHttpFilters(uri);
        }
        return new MyHttpFilters(connectedUrl + uri);
    }

• On CONNECT you must always return a HttpFiltersAdapter, since it has to bypass all filtering.
• Without a saved connected_url in the context it's plain HTTP, no HTTPS.
• Following requests on this channel have to concatenate the saved connected_url with the URI from the originalRequest.

Workarounds for Known Problems

• HTTPS fails with Exception: Handshake has already been started on Android Version 5+ (netty/netty#4718). It's fixed with PR #4767. Using Netty 4.1.0.CR2-SNAPSHOT MITM works well with Android 5.0, 5.1, and 6.0, just as Java platforms too.

• Connection failure with some HTTPS sites like https://www.archlinux.org/ for example. You have to use Java Cryptography Extension to fix it.

387481 2015-05-19 21:34:39,061 WARN  [LittleProxy-ProxyToServerWorker-6] impl.ProxyToServerConnection - (HANDSHAKING) [id: 0x7e0de7f2, /192.168.178.30:1475 => www.archlinux.org/66.211.214.131:443]: Caught exception on proxy -> web connection
io.netty.handler.codec.DecoderException: java.lang.RuntimeException: Could not generate DH keypair
    at io.netty.handler.codec.ByteToMessageDecoder.callDecode(ByteToMessageDecoder.java:346)
...
Caused by: java.security.InvalidAlgorithmParameterException: Prime size must be multiple of 64, and can only range from 512 to 1024 (inclusive)
    at com.sun.crypto.provider.DHKeyPairGenerator.initialize(DHKeyPairGenerator.java:120)
...

• I'm not a natural English speaker/writer. So feel free to fix me if I'm wrong (or always in generally) and don't feel sad about a phrase.

FAQ - Answered Questions

Issues labeled with question which could be interesting for you too.