{"id":13538757,"url":"https://github.com/commonsguy/cwac-netsecurity","last_synced_at":"2025-05-04T21:09:01.581Z","repository":{"id":66933460,"uuid":"60649051","full_name":"commonsguy/cwac-netsecurity","owner":"commonsguy","description":"CWAC-NetSecurity: Simplifying Secure Internet Access","archived":false,"fork":false,"pushed_at":"2019-10-12T12:01:56.000Z","size":504,"stargazers_count":240,"open_issues_count":6,"forks_count":22,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-05-04T21:08:55.471Z","etag":null,"topics":["android","android-library","android-security","ssl","ssl-pinning"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/commonsguy.png","metadata":{"files":{"readme":"README-original.markdown","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-06-07T21:53:18.000Z","updated_at":"2025-04-20T09:25:58.000Z","dependencies_parsed_at":"2023-04-21T10:07:12.965Z","dependency_job_id":null,"html_url":"https://github.com/commonsguy/cwac-netsecurity","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commonsguy%2Fcwac-netsecurity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commonsguy%2Fcwac-netsecurity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commonsguy%2Fcwac-netsecurity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commonsguy%2Fcwac-netsecurity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/commonsguy","download_url":"https://codeload.github.com/commonsguy/cwac-netsecurity/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252399517,"owners_count":21741672,"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","android-library","android-security","ssl","ssl-pinning"],"created_at":"2024-08-01T09:01:15.614Z","updated_at":"2025-05-04T21:09:01.559Z","avatar_url":"https://github.com/commonsguy.png","language":"Java","readme":"# CWAC-NetSecurity: Simplifying Secure Internet Access\n\nThis library contains a backport of\n[the Android 7.0 network security configuration](https://developer.android.com/training/articles/security-config.html)\nsubsystem. In Android 7.0, this subsystem makes it easier for developers\nto tie their app to particular certificate authorities or certificates,\nsupport self-signed certificates, and handle other advanced SSL\ncertificate scenarios. This backport allows the same XML configuration\nto be used, going back to API Level 17 (Android 4.2).\n\nThis library also offers a `TrustManagerBuilder` and related classes\nto make it easier for developers to integrate the network security\nconfiguration backport, particularly for\n[OkHttp3](https://github.com/square/okhttp)\nand `HttpURLConnection`.\n\nThis library also includes support for certificate memorization, where you\ncan elect to trust certificates discovered \"in the wild\", either automatically\nor with user approval.\n\nNote that OkHttp has its own `CertificatePinner`. If all you are looking to do is pin certificates, and you are usign OkHttp (and you should be!), use `CertificatePinner` and do not use CWAC-NetSecurity. Conversely, if there are [advanced features of CWAC-NetSecurity](https://github.com/commonsguy/cwac-netsecurity/blob/master/docs/ADVANCED_USAGE.markdown) that you wish to use, that's great... but do not also use `CertificatePinner`. Use one or the other, not both.\n\n## Installation\n\nThe artifact for this library is distributed via the CWAC repository,\nso you will need to configure that in your module's `build.gradle` file,\nalong with your `compile` statement:\n\n```groovy\nrepositories {\n    maven {\n        url \"https://s3.amazonaws.com/repo.commonsware.com\"\n    }\n}\n\ndependencies {\n    implementation 'com.commonsware.cwac:netsecurity:0.5.0'\n    implementation 'com.squareup.okhttp3:okhttp:3.9.1'\n}\n```\n\nIf you are using this library with OkHttp3, you also need to have\nan `implementation` statement for a compatible OkHttp3 artifact, as shown\nabove. Right now, the most recent compatible OkHttp3 version is 3.9.1.\n\nIf you are using `HttpURLConnection`, or tying this code into some\nother HTTP client stack, you can skip the OkHttp3 dependency.\n\n## Basic Usage\n\nStart by following\n[Google's documentation for the Android 7.0 network security configuration](https://developer.android.com/training/articles/security-config.html).\nIdeally, confirm that your configuration works using an Android 7.0+\ndevice.\n\nNext, add in this `\u003cmeta-data\u003e` element to your manifest, as a child\nof the `\u003capplication\u003e` element:\n\n```xml\n\u003cmeta-data\n  android:name=\"android.security.net.config\"\n  android:resource=\"@xml/net_security_config\" /\u003e\n```\n\nThe value for `android:resource` should be the same XML resource that\nyou used in the `android:networkSecurityConfig` attribute in the\n`\u003capplication\u003e` element.\n\nThen, in your code where you want to set up your network communications,\ncreate a `TrustManagerBuilder` and teach it to load the configuration\nfrom the manifest:\n\n```java\nTrustManagerBuilder tmb=\n  new TrustManagerBuilder().withManifestConfig(ctxt);\n```\n\n(where `ctxt` is some `Context`)\n\nIf you are using OkHttp3, create your basic `OkHttpClient.Builder`,\nthen call:\n\n```java\nOkHttp3Integrator.applyTo(tmb, okb);\n```\n\n(where `tmb` is the `TrustManagerBuilder` from before, and `okb`\nis your `OkHttpClient.Builder`)\n\nAt this point, you can create your `OkHttpClient` from the `Builder`\nand start using it.\n\nIf you are using `HttpURLConnection`, you can call `applyTo()` on\nthe `TrustManagerBuilder` itself, passing in the `HttpURLConnection`.\nAfterwards, you can start using the `HttpURLConnection` to make your\nHTTP request.\n\nIn either case, on Android 7.0+ devices, `withManifestConfig()` will\n*not* use the backport. Instead, the platform-native implementation\nof the network security configuration subsystem will be used. On\nAndroid 4.2-6.0 devices, the backport will be used.\n\n## Basic Limitations\n\nIf you use `HttpURLConnection`, you cannot use `\u003cdomain-config\u003e`\nelements in the network security configuration XML. Similarly,\nyou cannot use `cleartextTrafficPermitted` with `HttpURLConnection`.\nIf you have them in the XML, they will be ignored.\n\nOkHttp3 should support the full range of network security configuration\nXML features.\n\nThe `\u003ccertificates src=\"user\" /\u003e` cannot really be supported prior to Android 7.0,\ninsofar as the system will check user certificates any time it checks for\nsystem certificates. If you include such an element in a configuration:\n\n- If you are using `withManifestConfig()`, a warning will be logged to LogCat,\nand the element will be treated as if it were `\u003ccertificates src=\"system\" /\u003e`\n\n- If you are using anything else (e.g., `withConfig()`), your app will crash\nat startup, with an error indicating that `\u003ccertificates src=\"user\" /\u003e` is not\nsupported\n\n## Advanced Usage\n\nIf you want to employ certificate memorization or otherwise\ndo more sophisticated things with the network security\nconfiguration backport and/or `TrustManagerBuilder`, there is a\n[separate page of documentation](https://github.com/commonsguy/cwac-netsecurity/blob/master/docs/ADVANCED_USAGE.markdown)\nfor that.\n\n## Notes for Upgraders\n\nIf you are upgrading to v0.3.0 or higher from v0.2.1 or older, and you\nare using `\u003ccertificates src=\"user\" /\u003e`, note that this is no longer supported\n(see above).\n\n## Compiling from Source and Running the Test Suites\n\nThe instrumentation tests in `androidTest/` are divided into two\nsub-packages: `pub` and `priv`.\n\nThe `pub` tests hit publicly-available Web servers (mostly those\nhosted by CommonsWare). As such, you should be able to run those\ntests without issue.\n\nThe `priv` tests need additional configuration on your part. That\nconfiguration is designed to be held in a `gradle.properties`\nfile that you need to add to your root directory of your copy\nof the project code. Specifically, three values should reside there:\n\n- `TEST_PRIVATE_HTTP_URL`: a URL to some Web server that you control\n- `TEST_PRIVATE_HTTPS_URL`: a URL to some Web server that you control, where the communications are secured via SSL using a self-signed certificate\n- `TEST_PRIVATE_HTTP_REDIR_URL`: a URL to some Web server that you control that, when requested, issues a server-side redirect to an SSL-secured page (such as the one from `TEST_PRIVATE_HTTPS_URL`)\n\nThe first two URLs should each return:\n\n```json\n{\"Hello\": \"world\"}\n```\n\nYou will need to define those values in your `gradle.properties` file\neven if you are just planning on modifying the code, as otherwise\nthe `build.gradle` files for the library modules will fail, as they expect\nthose values.\n\nIn addition, if you wish to run the `priv` tests, you will need to\nreplace the `androidTest/res/raw/selfsigned.crt` file in each library\nmodule with the CRT file that matches your self-signed certificate that\n`TEST_PRIVATE_HTTPS_URL` uses.\n\nNote that right now the tests require Android 8.1 or *older*; some tests will\nnot work on Android 9.0 and higher.\n\n## Dependencies\n\n`netsecurity` has a `provided` dependency on OkHttp3. Version 0.5.0\nof this library uses OkHttp version **3.9.1**. `netsecurity` presently is\nnot compatible with newer versions of OkHttp.\n\nOtherwise, there are no external dependencies.\n\n## Version\n\nThe current version is **0.5.0**.\n\n## License\n\nAll of the code in this repository is licensed under the\nApache Software License 2.0. Look to the headers of the Java source\nfiles to determine the actual copyright holder, as it is a mix of\nthe Android Open Source Project and CommonsWare, LLC.\n\n## Questions\n\nIf you have questions regarding the use of this code, please post a question\non [Stack Overflow](http://stackoverflow.com/questions/ask) tagged with\n`commonsware-cwac` and `android` after [searching to see if there already is an answer](https://stackoverflow.com/search?q=[commonsware-cwac]+camera). Be sure to indicate\nwhat CWAC module you are having issues with, and be sure to include source code \nand stack traces if you are encountering crashes.\n\nIf you have encountered what is clearly a bug, or if you have a feature request,\nplease read [the contribution guidelines](.github/CONTRIBUTING.md), then\npost an [issue](https://github.com/commonsguy/cwac-netsecurity/issues).\n**Be certain to include complete steps for reproducing the issue.**\nIf you believe that the issue you have found represents a security bug,\nplease follow the instructions in\n[the contribution guidelines](https://github.com/commonsguy/cwac-netsecurity/blob/master/.github/CONTRIBUTING.md#contributing-security-bug-reports).\n\nYou are also welcome to join\n[the CommonsWare Community](https://community.commonsware.com/)\nand post questions\nand ideas to [the CWAC category](https://community.commonsware.com/c/cwac).\n\nDo not ask for help via social media.\n\n## AOSP Version Tracking and Release Notes\n\n|Library Version|AOSP Code Base                                                                                          |Release Notes|\n|:-------------:|:------------------------------------------------------------------------------------------------------:|-------------|\n|v0.5.0         |Android 9.0 source code from the SDK, plus [the `android-7.1.0_r7` tagged edition of `conscrypt`](https://android.googlesource.com/platform/external/conscrypt/+/android-7.1.0_r7)|updated to OkHttp 3.9.1 and newer build instructions, [added methods to `CompositeTrustManager`](https://github.com/commonsguy/cwac-netsecurity/issues/18) |\n|v0.4.5         |Android 8.0 source code from the SDK, plus [the `android-7.1.0_r7` tagged edition of `conscrypt`](https://android.googlesource.com/platform/external/conscrypt/+/android-7.1.0_r7)|updated to OkHttp 3.9.0 and newer Android Plugin for Gradle, Gradle|\n|v0.4.4         |Android 7.1 source code from the SDK, plus [the `android-7.1.0_r7` tagged edition of `conscrypt`](https://android.googlesource.com/platform/external/conscrypt/+/android-7.1.0_r7)|updated to OkHttp 3.8.1 and fixed testing bug|\n|v0.4.3         |Android 7.1 source code from the SDK, plus [the `android-7.1.0_r7` tagged edition of `conscrypt`](https://android.googlesource.com/platform/external/conscrypt/+/android-7.1.0_r7)|updated to OkHttp 3.8.0 and new test SSL certificate|\n|v0.4.2         |Android 7.1 source code from the SDK, plus [the `android-7.1.0_r7` tagged edition of `conscrypt`](https://android.googlesource.com/platform/external/conscrypt/+/android-7.1.0_r7)|added single-item-chain filtering for memorization|\n|v0.4.1         |Android 7.1 source code from the SDK, plus [the `android-7.1.0_r7` tagged edition of `conscrypt`](https://android.googlesource.com/platform/external/conscrypt/+/android-7.1.0_r7)|switched to OkHttp 3.6.0, add domain filtering for memorization|\n|v0.4.0         |Android 7.1 source code from the SDK, plus [the `android-7.1.0_r7` tagged edition of `conscrypt`](https://android.googlesource.com/platform/external/conscrypt/+/android-7.1.0_r7)|added certificate memorization and NetCipher integration options|\n|v0.3.1         |Android 7.1 source code from the SDK, plus [the `android-7.1.0_r7` tagged edition of `conscrypt`](https://android.googlesource.com/platform/external/conscrypt/+/android-7.1.0_r7)|bug fix per [issue #7](https://github.com/commonsguy/cwac-netsecurity/issues/7)|\n|v0.3.0         |Android 7.1 source code from the SDK, plus [the `android-7.1.0_r7` tagged edition of `conscrypt`](https://android.googlesource.com/platform/external/conscrypt/+/android-7.1.0_r7)|`user` validation per [issue #5](https://github.com/commonsguy/cwac-netsecurity/issues/5)|\n|v0.2.1         |Android 7.1 source code from the SDK, plus [the `android-7.1.0_r7` tagged edition of `conscrypt`](https://android.googlesource.com/platform/external/conscrypt/+/android-7.1.0_r7)|bug fix per [issue #3](https://github.com/commonsguy/cwac-netsecurity/issues/3)|\n|v0.2.0         |Android 7.0 source code from the SDK, plus [the `android-7.0.0_r1` tagged edition of `conscrypt`](https://android.googlesource.com/platform/external/conscrypt/+/android-7.0.0_r1)|`HttpURLConnection` no longer requires `setHost()` call|\n|v0.1.0         |Android 7.0 source code from the SDK, plus [the `android-7.0.0_r1` tagged edition of `conscrypt`](https://android.googlesource.com/platform/external/conscrypt/+/android-7.0.0_r1)|update for new version of Android|\n|v0.0.1         |[`android-n-preview-4`](https://android.googlesource.com/platform/frameworks/base/+/android-n-preview-4)|initial release|\n","funding_links":[],"categories":["\u003ca id=\"9eee96404f868f372a6cbc6769ccb7f8\"\u003e\u003c/a\u003e工具"],"sub_categories":["\u003ca id=\"31185b925d5152c7469b963809ceb22d\"\u003e\u003c/a\u003e新添加的"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommonsguy%2Fcwac-netsecurity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcommonsguy%2Fcwac-netsecurity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommonsguy%2Fcwac-netsecurity/lists"}