Skip to content

Commit

Permalink
Migrate to an Android library project.
Browse files Browse the repository at this point in the history
  • Loading branch information
moxie0 committed Mar 9, 2013
1 parent 5224988 commit 9098125
Show file tree
Hide file tree
Showing 23 changed files with 1,518 additions and 274 deletions.
6 changes: 6 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
.idea
*.iml
local.properties
gen
out
*~
9 changes: 9 additions & 0 deletions AndroidManifest.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="org.thoughtcrime.ssl.pinning"
android:versionCode="1"
android:versionName="1.0">

<uses-sdk android:minSdkVersion="8" android:targetSdkVersion="16"/>

</manifest>
85 changes: 85 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
Android Pinning
=================

libpinning is a standalone Android library project that facilitates certificate pinning for SSL
connections from Android apps, in order to minimize dependence on Certificate Authorities.

CA signatures are necessary for *general purpose* network communication tools: things like web
browsers, which connect to arbitrary network endpoints and have no advance knowledge of what the SSL
certificates for those endpoint should look like.

Most mobile apps are not *general purpose* communication tools. Instead, they typically connect
directly to a narrow set of backend services that the app's author either controls, or can
predict ahead of time.

This creates an opportunity for app developers to sidestep the security problems inherent with
Certificate Authorities. The best way is to throw CA certificates out the window entirely by
signing your own endpoint certificates with your own offline signing certificate, which you then
distribute with your app. See [this blog post](http://thoughtcrime.org/blog/authenticity-is-broken-in-ssl-but-your-app-ha/)
for examples of the no-CA technique.

Sometimes, however, that's not possible, and you need to continue using CA certificates for one
reason or another. Perhaps the API endpoint is shared with a web browser's endpoint, for instance.

In that case, it's necessary to employ "pinning," which is simply the act of verifying that the
certificate chain looks the way you know it should, even if it's signed by a CA. This prevents
*other* CAs from being able to effectively create forged certificates for your domain, as with the
many Comodo breaches, the DigiNotar breach, and the TurkTrust breach.

This library is designed to make pinning easier on Android. It's structured as an Android library
project, so you can simply link it to your own project and begin.

Examples
-----------

Using a simple `HttpsURLConnection` with a `PinningTrustManager`:

``// Define an array of pins. One of these must be present
// in the certificate chain you receive. A pin is a hex-encoded
// hash of a X.509 certificate's SubjectPublicKeyInfo. A pin can
// be generated using the provided pin.py script:
// python ./tools/pin.py certificate_file.pem
String[] pins = new String[] {"f30012bbc18c231ac1a44b788e410ce754182513"};
URL url = new URL("https://www.google.com");
HttpsURLConnection connection = PinningHelper.getPinnedHttpsURLConnection(context, pins, url);

return connection.getInputStream();
``

Using a simple ``HttpClient` with a `PinningTrustManager`:

``String[] pins = new String[] {"f30012bbc18c231ac1a44b788e410ce754182513"};
HttpClient httpClient = PinningHelper.getPinnedHttpClient(context, pins);

HttpResponse response = httpClient.execute(new HttpGet("https://www.google.com/"));
``

It's also possible to work with `PinningTrustManager` and `PinningSSLSocketFactory` more directly:

``String[] pins = new String[] {"40c5401d6f8cbaf08b00edefb1ee87d005b3b9cd"};
SchemeRegistry schemeRegistry = new SchemeRegistry();
schemeRegistry.register(new Scheme("http", PlainSocketFactory.getSocketFactory(), 80));
schemeRegistry.register(new Scheme("https", new PinningSSLSocketFactory(getContext() ,pins, 0), 443));

HttpParams httpParams = new BasicHttpParams();
ClientConnectionManager connectionManager = new ThreadSafeClientConnManager(httpParams, schemeRegistry);
DefaultHttpClient httpClient = new DefaultHttpClient(connectionManager, httpParams);

HttpResponse response = httpClient.execute(new HttpGet("https://www.google.com/"));
``

Issues
-----------

Have a bug? Please create an issue here on GitHub!

https://github.com/moxie0/AndroidPinning/issues

License
---------------------

Copyright 2011-2013 Moxie Marlinspike

Licensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html

Please contact me if this license doesn't work for you.
17 changes: 17 additions & 0 deletions ant.properties
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# This file is used to override default values used by the Ant build system.
#
# This file must be checked into Version Control Systems, as it is
# integral to the build system of your project.

# This file is only used by the Ant script.

# You can use this to override default values such as
# 'source.dir' for the location of your java source folder and
# 'out.dir' for the location of your output folder.

# You can also use it define how the release builds are signed by declaring
# the following properties:
# 'key.store' for the location of your keystore and
# 'key.alias' for the name of the key to use.
# The password will be asked during the build when you use the 'release' target.

92 changes: 92 additions & 0 deletions build.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
<?xml version="1.0" encoding="UTF-8"?>
<project name="libpinning" default="help">

<!-- The local.properties file is created and updated by the 'android' tool.
It contains the path to the SDK. It should *NOT* be checked into
Version Control Systems. -->
<property file="local.properties" />

<!-- The ant.properties file can be created by you. It is only edited by the
'android' tool to add properties to it.
This is the place to change some Ant specific build properties.
Here are some properties you may want to change/update:
source.dir
The name of the source directory. Default is 'src'.
out.dir
The name of the output directory. Default is 'bin'.
For other overridable properties, look at the beginning of the rules
files in the SDK, at tools/ant/build.xml
Properties related to the SDK location or the project target should
be updated using the 'android' tool with the 'update' action.
This file is an integral part of the build system for your
application and should be checked into Version Control Systems.
-->
<property file="ant.properties" />

<!-- if sdk.dir was not set from one of the property file, then
get it from the ANDROID_HOME env var.
This must be done before we load project.properties since
the proguard config can use sdk.dir -->
<property environment="env" />
<condition property="sdk.dir" value="${env.ANDROID_HOME}">
<isset property="env.ANDROID_HOME" />
</condition>

<!-- The project.properties file is created and updated by the 'android'
tool, as well as ADT.
This contains project specific properties such as project target, and library
dependencies. Lower level build properties are stored in ant.properties
(or in .classpath for Eclipse projects).
This file is an integral part of the build system for your
application and should be checked into Version Control Systems. -->
<loadproperties srcFile="project.properties" />

<!-- quick check on sdk.dir -->
<fail
message="sdk.dir is missing. Make sure to generate local.properties using 'android update project' or to inject it through the ANDROID_HOME environment variable."
unless="sdk.dir"
/>

<!--
Import per project custom build rules if present at the root of the project.
This is the place to put custom intermediary targets such as:
-pre-build
-pre-compile
-post-compile (This is typically used for code obfuscation.
Compiled code location: ${out.classes.absolute.dir}
If this is not done in place, override ${out.dex.input.absolute.dir})
-post-package
-post-build
-pre-clean
-->
<import file="custom_rules.xml" optional="true" />

<!-- Import the actual build file.
To customize existing targets, there are two options:
- Customize only one target:
- copy/paste the target into this file, *before* the
<import> task.
- customize it to your needs.
- Customize the whole content of build.xml
- copy/paste the content of the rules files (minus the top node)
into this file, replacing the <import> task.
- customize to your needs.
***********************
****** IMPORTANT ******
***********************
In all cases you must update the value of version-tag below to read 'custom' instead of an integer,
in order to avoid having your file be overridden by tools such as "android update project"
-->
<!-- version-tag: 1 -->
<import file="${sdk.dir}/tools/ant/build.xml" />

</project>
Loading

0 comments on commit 9098125

Please sign in to comment.