Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/datatheorem/TrustKit-Android
Easy SSL pinning validation and reporting for Android.
https://github.com/datatheorem/TrustKit-Android
android ssl ssl-pinning ssl-reporting
Last synced: 3 months ago
JSON representation
Easy SSL pinning validation and reporting for Android.
- Host: GitHub
- URL: https://github.com/datatheorem/TrustKit-Android
- Owner: datatheorem
- License: mit
- Created: 2016-11-14T10:12:05.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2024-04-18T20:13:16.000Z (7 months ago)
- Last Synced: 2024-08-01T09:22:03.663Z (3 months ago)
- Topics: android, ssl, ssl-pinning, ssl-reporting
- Language: Java
- Homepage:
- Size: 835 KB
- Stars: 583
- Watchers: 24
- Forks: 87
- Open Issues: 32
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
TrustKit Android
============
[](https://app.bitrise.io/app/00f0a4139c34c45d#/builds)
[](https://android-arsenal.com/api?level=15)
[](https://bintray.com/datatheoremoss/TrustKit-Android/trustkit)
[](https://en.wikipedia.org/wiki/MIT_License)
[](https://gitter.im/TrustKit/Lobby)
**TrustKit Android** is an open source library that makes it easy to deploy SSL public key pinning and reporting in any Android App.
If you need SSL pinning/reporting in your iOS App. we have also released **TrustKit for iOS and macOS** at [https://github.com/datatheorem/TrustKit](https://github.com/datatheorem/TrustKit).
Overview
--------
TrustKit Android works by extending the [Android N Network Security Configuration](https://developer.android.com/training/articles/security-config.html) in two ways:
* It provides support for the `` (for SSL pinning) and `` functionality of the Network Security Configuration to earlier versions of Android, down to API level 17. This allows Apps that support versions of Android earlier than N to implement SSL pinning in a way that is future-proof.
* It adds the ability to send reports when pinning validation failed for a specific connection. Reports have a format that is similar to the report-uri feature of [HTTP Public Key Pinning](https://developer.mozilla.org/en-US/docs/Web/HTTP/Public_Key_Pinning) and [TrustKit iOS](https://github.com/datatheorem/trustkit).
For better compatibility, TrustKit will also run on API levels 15 and 16 but its functionality will be disabled.
Getting Started
----------------
* Read the [Getting Started guide](https://github.com/datatheorem/TrustKit-Android/blob/master/docs/getting-started.md).
* Check out the [API documentation](https://datatheorem.github.io/TrustKit-Android/documentation/).
* The [iOS version of TrustKit](https://github.com/datatheorem/TrustKit) was initially released at the Black Hat USA 2015 conference.
Sample Usage
---------------
### Adding TrustKit as a Dependency
Add TrustKit to your project's _build.gradle_:
`implementation 'com.datatheorem.android.trustkit:trustkit:'`
### Configuring a Pinning Policy
Deploying SSL pinning in the App requires initializing TrustKit with a pinning policy (domains, pins, and additional settings). The policy is wrapped in the official [Android N Network Security Configuration](https://developer.android.com/training/articles/security-config.html) i.e :
```xml
www.datatheorem.com
k3XnEYQCK79AtL9GYnT/nyhsabas03V+bhRQYHQbpXU=
2kOi4HdYYsvTR1sTIR7RHwlf2SescTrpza9ZrWy7poQ=
http://report.datatheorem.com/log_report
```
### Initializing TrustKit with the Pinning Policy
The path to the XML policy should then be specified [in the App's manifest](https://developer.android.com/training/articles/security-config.html#manifest) in order to enable it as the App's [Network Security Configuration](https://developer.android.com/training/articles/security-config.html) on Android N:
```
...
```
Then, TrustKit should be initialized with the same path:
```java
@Override
protected void onCreate(Bundle savedInstanceState) {
super.OnCreate(savedInstanceState);
// Using the default path - res/xml/network_security_config.xml
TrustKit.initializeWithNetworkSecurityConfiguration(this);
// OR using a custom resource (TrustKit can't be initialized twice)
TrustKit.initializeWithNetworkSecurityConfiguration(this, R.xml.my_custom_network_security_config);
URL url = new URL("https://www.datatheorem.com");
String serverHostname = url.getHost();
//Optionally add a local broadcast receiver to receive PinningFailureReports
PinningValidationReportTestBroadcastReceiver receiver = new PinningValidationReportTestBroadcastReceiver();
LocalBroadcastManager.getInstance(context)
.registerReceiver(receiver, new IntentFilter(BackgroundReporter.REPORT_VALIDATION_EVENT));
// HttpsUrlConnection
HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
connection.setSSLSocketFactory(TrustKit.getInstance().getSSLSocketFactory(serverHostname));
// OkHttp 2.x
OkHttpClient client =
new OkHttpClient()
.setSslSocketFactory(OkHttp2Helper.getSSLSocketFactory());
client.interceptors().add(OkHttp2Helper.getPinningInterceptor());
client.setFollowRedirects(false);
// OkHttp 3.0.x, 3.1.x and 3.2.x
OkHttpClient client =
new OkHttpClient.Builder()
.sslSocketFactory(OkHttp3Helper.getSSLSocketFactory())
.addInterceptor(OkHttp3Helper.getPinningInterceptor())
.followRedirects(false)
.followSslRedirects(false)
// OkHttp 3.3.x and higher
OkHttpClient client =
new OkHttpClient.Builder()
.sslSocketFactory(OkHttp3Helper.getSSLSocketFactory(), OkHttp3Helper.getTrustManager())
.addInterceptor(OkHttp3Helper.getPinningInterceptor())
.followRedirects(false)
.followSslRedirects(false)
.build();
}
class PinningFailureReportBroadcastReceiver extends BroadcastReceiver {
@Override
public void onReceive(Context context, Intent intent) {
PinningFailureReport report = (PinningFailureReport) intent.getSerializableExtra(BackgroundReporter.EXTRA_REPORT);
}
}
```
Once TrustKit has been initialized and the client or connection's `SSLSocketFactory` has been set, it will verify the server's certificate chain against the configured pinning policy whenever an HTTPS connection is initiated. If a report URI has been configured, the App will also send reports to the specified URI whenever a pin validation failure occurred.
You can also create and register local broadcast receivers to receive the same certificate pinning error reports that would be sent to the report_uris.
Limitations
----------
On Android N devices, TrustKit uses the OS's implementation of pinning, and it is not affected by the following limitations.
On Android M and earlier devices, TrustKit provides uses its own implementation of pinning that is mostly-compatible with Android N's pinning behavior. However, in order to keep the code base as simple as possible, it has the following limitations:
* The pinning policy will only be applied to connections that were configured to use a TrustKit-provided `SSLSocketFactory` or `X509TrustManager`.
* The `SSLSocketFactory` or `X509TrustManager` provided by TrustKit can only be used for connections to the domain that was passed to the `getTrustManager()` and `getSSLSocketFactory()` methods. Hence, if a redirection to a different domain occurs, the new domain will fail SSL validation and the connection will fail. In practice, this should not be a problem because pinning validation is only meant to be used on the few specific domains on which the App's main server API is hosted --- redirections should not happen in this scenario.
* The `` setting is only applied when used within the global `` tag. Hence, custom trust anchors for specific domains cannot be set.
* Within the `` tag, only `` tags pointing to a raw certificate file are supported (the `user` or `system` values for the `src` attribute will be ignored).
For consumers of TrustKit's OkHttpHelper solutions, redirects must to be disabled as Pinning will currently only work properly on the initial request and not any redirects
License
-------
TrustKit Android is released under the MIT license. See LICENSE for details.