{"id":13814397,"url":"https://github.com/datatheorem/TrustKit-Android","last_synced_at":"2025-05-15T03:34:07.068Z","repository":{"id":15747418,"uuid":"73692244","full_name":"datatheorem/TrustKit-Android","owner":"datatheorem","description":"Easy SSL pinning validation and reporting for Android.","archived":false,"fork":false,"pushed_at":"2024-04-18T20:13:16.000Z","size":855,"stargazers_count":589,"open_issues_count":32,"forks_count":87,"subscribers_count":26,"default_branch":"master","last_synced_at":"2024-11-03T03:31:29.012Z","etag":null,"topics":["android","ssl","ssl-pinning","ssl-reporting"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datatheorem.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-14T10:12:05.000Z","updated_at":"2024-11-02T13:41:06.000Z","dependencies_parsed_at":"2024-08-01T09:21:48.394Z","dependency_job_id":"b1d6a511-4065-41b0-9de3-e2dced4efeec","html_url":"https://github.com/datatheorem/TrustKit-Android","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datatheorem%2FTrustKit-Android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datatheorem%2FTrustKit-Android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datatheorem%2FTrustKit-Android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datatheorem%2FTrustKit-Android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datatheorem","download_url":"https://codeload.github.com/datatheorem/TrustKit-Android/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225326467,"owners_count":17456947,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","ssl","ssl-pinning","ssl-reporting"],"created_at":"2024-08-04T04:01:56.085Z","updated_at":"2024-11-19T09:30:43.640Z","avatar_url":"https://github.com/datatheorem.png","language":"Java","readme":"TrustKit Android\n============\n\n\n[![Build Status](https://app.bitrise.io/app/00f0a4139c34c45d/status.svg?token=A5sTczJBYGmt3oFXQJ5Ymw\u0026branch=master)](https://app.bitrise.io/app/00f0a4139c34c45d#/builds)\n[![API](https://img.shields.io/badge/API-15%2B-blue.svg?style=flat)](https://android-arsenal.com/api?level=15)\n[![Version](https://img.shields.io/bintray/v/datatheoremoss/TrustKit-Android/trustkit.svg)](https://bintray.com/datatheoremoss/TrustKit-Android/trustkit)\n[![MIT License](https://img.shields.io/github/license/datatheorem/trustkit-android.svg)](https://en.wikipedia.org/wiki/MIT_License)\n[![Gitter chat](https://badges.gitter.im/datatheorem/gitter.png)](https://gitter.im/TrustKit/Lobby)\n\n**TrustKit Android** is an open source library that makes it easy to deploy SSL public key pinning and reporting in any Android App.\n\nIf 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).\n\n\nOverview\n--------\n\nTrustKit Android works by extending the [Android N Network Security Configuration](https://developer.android.com/training/articles/security-config.html) in two ways:\n\n* It provides support for the `\u003cpin-set\u003e` (for SSL pinning) and `\u003cdebug-overrides\u003e` 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.\n* 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).\n\nFor better compatibility, TrustKit will also run on API levels 15 and 16 but its functionality will be disabled.\n\n\nGetting Started\n----------------\n\n* Read the [Getting Started guide](https://github.com/datatheorem/TrustKit-Android/blob/master/docs/getting-started.md).\n* Check out the [API documentation](https://datatheorem.github.io/TrustKit-Android/documentation/).\n* The [iOS version of TrustKit](https://github.com/datatheorem/TrustKit) was initially released at the Black Hat USA 2015 conference.\n\n\nSample Usage\n---------------\n\n\n### Adding TrustKit as a Dependency\n\nAdd TrustKit to your project's _build.gradle_:\n\n`implementation 'com.datatheorem.android.trustkit:trustkit:\u003clast_version\u003e'`\n\n### Configuring a Pinning Policy\n\nDeploying 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 :\n\n```xml\n\u003c!-- res/xml/network_security_config.xml --\u003e\n\u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\n\u003cnetwork-security-config\u003e\n  \u003c!-- Pin the domain www.datatheorem.com --\u003e\n  \u003c!-- Official Android N API --\u003e\n  \u003cdomain-config\u003e\n    \u003cdomain\u003ewww.datatheorem.com\u003c/domain\u003e\n    \u003cpin-set\u003e\n      \u003cpin digest=\"SHA-256\"\u003ek3XnEYQCK79AtL9GYnT/nyhsabas03V+bhRQYHQbpXU=\u003c/pin\u003e\n      \u003cpin digest=\"SHA-256\"\u003e2kOi4HdYYsvTR1sTIR7RHwlf2SescTrpza9ZrWy7poQ=\u003c/pin\u003e\n    \u003c/pin-set\u003e\n    \u003c!-- TrustKit Android API --\u003e\n    \u003c!-- Do not enforce pinning validation --\u003e\n    \u003ctrustkit-config enforcePinning=\"false\"\u003e\n      \u003c!-- Add a reporting URL for pin validation reports --\u003e\n      \u003creport-uri\u003ehttp://report.datatheorem.com/log_report\u003c/report-uri\u003e\n    \u003c/trustkit-config\u003e\n  \u003c/domain-config\u003e\n  \u003cdebug-overrides\u003e\n    \u003ctrust-anchors\u003e\n      \u003c!-- For debugging purposes, add a debug CA and override pins --\u003e\n      \u003ccertificates overridePins=\"true\" src=\"@raw/debugca\" /\u003e\n    \u003c/trust-anchors\u003e\n  \u003c/debug-overrides\u003e\n\u003c/network-security-config\u003e\n```\n\n\n### Initializing TrustKit with the Pinning Policy\n\nThe 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:\n\n```\n\u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\n\u003cmanifest ... \u003e\n    \u003capplication android:networkSecurityConfig=\"@xml/network_security_config\"\n                    ... \u003e\n        ...\n    \u003c/application\u003e\n\u003c/manifest\u003e\n\n```\n\nThen, TrustKit should be initialized with the same path:\n\n```java\n@Override\nprotected void onCreate(Bundle savedInstanceState) {\n  super.OnCreate(savedInstanceState);\n\n  // Using the default path - res/xml/network_security_config.xml\n  TrustKit.initializeWithNetworkSecurityConfiguration(this);\n\n  // OR using a custom resource (TrustKit can't be initialized twice)\n  TrustKit.initializeWithNetworkSecurityConfiguration(this, R.xml.my_custom_network_security_config);\n\n  URL url = new URL(\"https://www.datatheorem.com\");\n  String serverHostname = url.getHost();\n  \n  //Optionally add a local broadcast receiver to receive PinningFailureReports\n  PinningValidationReportTestBroadcastReceiver receiver = new PinningValidationReportTestBroadcastReceiver();\n          LocalBroadcastManager.getInstance(context)\n                  .registerReceiver(receiver, new IntentFilter(BackgroundReporter.REPORT_VALIDATION_EVENT));\n\n  // HttpsUrlConnection\n  HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();\n  connection.setSSLSocketFactory(TrustKit.getInstance().getSSLSocketFactory(serverHostname));\n\n  // OkHttp 2.x\n  OkHttpClient client =\n    new OkHttpClient()\n        .setSslSocketFactory(OkHttp2Helper.getSSLSocketFactory());\n  client.interceptors().add(OkHttp2Helper.getPinningInterceptor());\n  client.setFollowRedirects(false);\n\n  // OkHttp 3.0.x, 3.1.x and 3.2.x\n  OkHttpClient client =\n    new OkHttpClient.Builder()\n        .sslSocketFactory(OkHttp3Helper.getSSLSocketFactory())\n        .addInterceptor(OkHttp3Helper.getPinningInterceptor())\n        .followRedirects(false)\n        .followSslRedirects(false)\n\n  // OkHttp 3.3.x and higher\n  OkHttpClient client =\n    new OkHttpClient.Builder()\n        .sslSocketFactory(OkHttp3Helper.getSSLSocketFactory(), OkHttp3Helper.getTrustManager())\n        .addInterceptor(OkHttp3Helper.getPinningInterceptor())\n        .followRedirects(false)\n        .followSslRedirects(false)\n    .build();\n}\n\nclass PinningFailureReportBroadcastReceiver extends BroadcastReceiver {\n\n    @Override\n    public void onReceive(Context context, Intent intent) {\n        PinningFailureReport report = (PinningFailureReport) intent.getSerializableExtra(BackgroundReporter.EXTRA_REPORT);\n    }\n}\n```\n\nOnce 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.\n\nYou can also create and register local broadcast receivers to receive the same certificate pinning error reports that would be sent to the report_uris. \n\n\n\nLimitations\n----------\n\nOn Android N devices, TrustKit uses the OS's implementation of pinning, and it is not affected by the following limitations.\n\nOn 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:\n\n* The pinning policy will only be applied to connections that were configured to use a TrustKit-provided `SSLSocketFactory` or `X509TrustManager`.\n* 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.\n* The `\u003ctrust-anchors\u003e` setting is only applied when used within the global `\u003cdebug-overrides\u003e` tag. Hence, custom trust anchors for specific domains cannot be set. \n* Within the `\u003ctrust-anchors\u003e` tag, only `\u003ccertificate\u003e` tags pointing to a raw certificate file are supported (the `user` or `system` values for the `src` attribute will be ignored).\n\nFor 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\n\nLicense\n-------\n\nTrustKit Android is released under the MIT license. See LICENSE for details.\n","funding_links":[],"categories":["Java"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatatheorem%2FTrustKit-Android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatatheorem%2FTrustKit-Android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatatheorem%2FTrustKit-Android/lists"}