1# MemorizingTrustManager - Private Cloud Support for Your App
2
3MemorizingTrustManager (MTM) is a project to enable smarter and more secure use
4of SSL on Android. If it encounters an unknown SSL certificate, it asks the
5user whether to accept the certificate once, permanently or to abort the
6connection. This is a step in preventing man-in-the-middle attacks by blindly
7accepting any invalid, self-signed and/or expired certificates.
8
9MTM is aimed at providing seamless integration into your Android application,
10and the source code is available under the MIT license.
11
12## Screenshots
13
14
15
16
17
18## Status
19
20MemorizingTrustManager is in production use in the
21[yaxim XMPP client](https://yaxim.org/). It is usable and easy to integrate,
22though it does not yet support hostname validation (the Java API makes it
23**hard** to integrate).
24
25## Integration
26
27MTM is easy to integrate into your own application. Follow these steps or have
28a look into the demo application in the `example` directory.
29
30### 1. Add MTM to your project
31
32Download the MTM source from GitHub, or add it as a
33[git submodule](http://git-scm.com/docs/git-submodule):
34
35 # plain download:
36 git clone https://github.com/ge0rg/MemorizingTrustManager
37 # submodule:
38 git submodule add https://github.com/ge0rg/MemorizingTrustManager
39
40Then add a library project dependency to `default.properties`:
41
42 android.library.reference.1=MemorizingTrustManager
43
44### 2. Add the MTM (popup) Activity to your manifest
45
46Edit your `AndroidManifest.xml` and add the MTM activity element right before the
47end of your closing `</application>` tag.
48
49 ...
50 <activity android:name="de.duenndns.ssl.MemorizingActivity"
51 android:theme="@android:style/Theme.Translucent.NoTitleBar"
52 />
53 </application>
54 </manifest>
55
56### 3. Hook MTM as the default TrustManager for your connection type
57
58Hooking MemorizingTrustmanager in HTTPS connections:
59
60 // register MemorizingTrustManager for HTTPS
61 SSLContext sc = SSLContext.getInstance("TLS");
62 MemorizingTrustManager mtm = new MemorizingTrustManager(this);
63 sc.init(null, new X509TrustManager[] { mtm }, new java.security.SecureRandom());
64 HttpsURLConnection.setDefaultSSLSocketFactory(sc.getSocketFactory());
65 HttpsURLConnection.setDefaultHostnameVerifier(
66 mtm.wrapHostnameVerifier(HttpsURLConnection.getDefaultHostnameVerifier()));
67
68
69Or, for aSmack you can use `setCustomSSLContext()`:
70
71 org.jivesoftware.smack.ConnectionConfiguration connectionConfiguration = …
72 SSLContext sc = SSLContext.getInstance("TLS");
73 MemorizingTrustManager mtm = new MemorizingTrustManager(this);
74 sc.init(null, new X509TrustManager[] { mtm }, new java.security.SecureRandom());
75 connectionConfiguration.setCustomSSLContext(sc);
76 connectionConfiguration.setHostnameVerifier(
77 mtm.wrapHostnameVerifier(new org.apache.http.conn.ssl.StrictHostnameVerifier()));
78
79By default, MTM falls back to the system `TrustManager` before asking the user.
80If you do not trust the establishment, you can enforce a dialog on *every new
81connection* by supplying a `defaultTrustManager = null` parameter to the
82constructor:
83
84 MemorizingTrustManager mtm = new MemorizingTrustManager(this, null);
85
86If you want to use a different underlying `TrustManager`, like
87[AndroidPinning](https://github.com/moxie0/AndroidPinning), just supply that to
88MTM's constructor:
89
90 X509TrustManager pinning = new PinningTrustManager(SystemKeyStore.getInstance(),
91 new String[] {"f30012bbc18c231ac1a44b788e410ce754182513"}, 0);
92 MemorizingTrustManager mtm = new MemorizingTrustManager(this, pinning);
93
94### 4. Profit!
95
96### Logging
97
98MTM uses java.util.logging (JUL) for logging purposes. If you have not
99configured a Handler for JUL, then Android will by default log all
100messages of Level.INFO or higher. In order to get also the debug log
101messages (those with Level.FINE or lower) you need to configure a
102Handler accordingly. The MTM example project contains
103de.duenndns.mtmexample.JULHandler, which allows to enable and disable
104debug logging at runtime.
105
106## Alternatives
107
108MemorizingTrustManager is not the only one out there.
109
110[**NetCipher**](https://guardianproject.info/code/netcipher/) is an Android
111library made by the [Guardian Project](https://guardianproject.info/) to
112improve network security for mobile apps. It comes with a StrongTrustManager
113to do more thorough certificate checks, an independent Root CA store, and code
114to easily route your traffic through
115[the Tor network](https://www.torproject.org/) using [Orbot](https://guardianproject.info/apps/orbot/).
116
117[**AndroidPinning**](https://github.com/moxie0/AndroidPinning) is another Android
118library, written by [Moxie Marlinspike](http://www.thoughtcrime.org/) to allow
119pinning of server certificates, improving security against government-scale
120MitM attacks. Use this if your app is made to communicate with a specific
121server!
122
123## Contribute
124
125Please [help translating MTM into more languages](https://translations.launchpad.net/yaxim/master/+pots/mtm/)!