diff options
Diffstat (limited to 'libs/MemorizingTrustManager/README.mdwn')
| -rw-r--r-- | libs/MemorizingTrustManager/README.mdwn | 125 |
1 files changed, 125 insertions, 0 deletions
diff --git a/libs/MemorizingTrustManager/README.mdwn b/libs/MemorizingTrustManager/README.mdwn new file mode 100644 index 00000000..c48f38de --- /dev/null +++ b/libs/MemorizingTrustManager/README.mdwn @@ -0,0 +1,125 @@ +# MemorizingTrustManager - Private Cloud Support for Your App + +MemorizingTrustManager (MTM) is a project to enable smarter and more secure use +of SSL on Android. If it encounters an unknown SSL certificate, it asks the +user whether to accept the certificate once, permanently or to abort the +connection. This is a step in preventing man-in-the-middle attacks by blindly +accepting any invalid, self-signed and/or expired certificates. + +MTM is aimed at providing seamless integration into your Android application, +and the source code is available under the MIT license. + +## Screenshots + + + + + +## Status + +MemorizingTrustManager is in production use in the +[yaxim XMPP client](https://yaxim.org/). It is usable and easy to integrate, +though it does not yet support hostname validation (the Java API makes it +**hard** to integrate). + +## Integration + +MTM is easy to integrate into your own application. Follow these steps or have +a look into the demo application in the `example` directory. + +### 1. Add MTM to your project + +Download the MTM source from GitHub, or add it as a +[git submodule](http://git-scm.com/docs/git-submodule): + + # plain download: + git clone https://github.com/ge0rg/MemorizingTrustManager + # submodule: + git submodule add https://github.com/ge0rg/MemorizingTrustManager + +Then add a library project dependency to `default.properties`: + + android.library.reference.1=MemorizingTrustManager + +### 2. Add the MTM (popup) Activity to your manifest + +Edit your `AndroidManifest.xml` and add the MTM activity element right before the +end of your closing `</application>` tag. + + ... + <activity android:name="de.duenndns.ssl.MemorizingActivity" + android:theme="@android:style/Theme.Translucent.NoTitleBar" + /> + </application> + </manifest> + +### 3. Hook MTM as the default TrustManager for your connection type + +Hooking MemorizingTrustmanager in HTTPS connections: + + // register MemorizingTrustManager for HTTPS + SSLContext sc = SSLContext.getInstance("TLS"); + MemorizingTrustManager mtm = new MemorizingTrustManager(this); + sc.init(null, new X509TrustManager[] { mtm }, new java.security.SecureRandom()); + HttpsURLConnection.setDefaultSSLSocketFactory(sc.getSocketFactory()); + HttpsURLConnection.setDefaultHostnameVerifier( + mtm.wrapHostnameVerifier(HttpsURLConnection.getDefaultHostnameVerifier())); + + +Or, for aSmack you can use `setCustomSSLContext()`: + + org.jivesoftware.smack.ConnectionConfiguration connectionConfiguration = … + SSLContext sc = SSLContext.getInstance("TLS"); + MemorizingTrustManager mtm = new MemorizingTrustManager(this); + sc.init(null, new X509TrustManager[] { mtm }, new java.security.SecureRandom()); + connectionConfiguration.setCustomSSLContext(sc); + connectionConfiguration.setHostnameVerifier( + mtm.wrapHostnameVerifier(new org.apache.http.conn.ssl.StrictHostnameVerifier())); + +By default, MTM falls back to the system `TrustManager` before asking the user. +If you do not trust the establishment, you can enforce a dialog on *every new +connection* by supplying a `defaultTrustManager = null` parameter to the +constructor: + + MemorizingTrustManager mtm = new MemorizingTrustManager(this, null); + +If you want to use a different underlying `TrustManager`, like +[AndroidPinning](https://github.com/moxie0/AndroidPinning), just supply that to +MTM's constructor: + + X509TrustManager pinning = new PinningTrustManager(SystemKeyStore.getInstance(), + new String[] {"f30012bbc18c231ac1a44b788e410ce754182513"}, 0); + MemorizingTrustManager mtm = new MemorizingTrustManager(this, pinning); + +### 4. Profit! + +### Logging + +MTM uses java.util.logging (JUL) for logging purposes. If you have not +configured a Handler for JUL, then Android will by default log all +messages of Level.INFO or higher. In order to get also the debug log +messages (those with Level.FINE or lower) you need to configure a +Handler accordingly. The MTM example project contains +de.duenndns.mtmexample.JULHandler, which allows to enable and disable +debug logging at runtime. + +## Alternatives + +MemorizingTrustManager is not the only one out there. + +[**NetCipher**](https://guardianproject.info/code/netcipher/) is an Android +library made by the [Guardian Project](https://guardianproject.info/) to +improve network security for mobile apps. It comes with a StrongTrustManager +to do more thorough certificate checks, an independent Root CA store, and code +to easily route your traffic through +[the Tor network](https://www.torproject.org/) using [Orbot](https://guardianproject.info/apps/orbot/). + +[**AndroidPinning**](https://github.com/moxie0/AndroidPinning) is another Android +library, written by [Moxie Marlinspike](http://www.thoughtcrime.org/) to allow +pinning of server certificates, improving security against government-scale +MitM attacks. Use this if your app is made to communicate with a specific +server! + +## Contribute + +Please [help translating MTM into more languages](https://translations.launchpad.net/yaxim/master/+pots/mtm/)! |