Subtree merged in MemorizingTrustManager

2 files changed, 125 insertions, 0 deletions

diff --git a/libs/MemorizingTrustManager b/libs/MemorizingTrustManager
deleted file mode 160000
-Subproject fad835037adc1bd313bb56b694426fca4eb6734
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
+
+![MemorizingTrustManager dialog](mtm-screenshot.png)
+![MemorizingTrustManager notification](mtm-notification.png)
+![MemorizingTrustManager server name dialog](mtm-servername.png)
+
+## 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/)!