{"id":22287608,"url":"https://github.com/charleskorn/okhttp-system-keystore","last_synced_at":"2025-07-28T22:32:19.487Z","repository":{"id":37010423,"uuid":"441058425","full_name":"charleskorn/okhttp-system-keystore","owner":"charleskorn","description":"Automatically use trusted certificates from the operating system keystore (Keychain on macOS, Certificate Store on Windows) with OkHttp","archived":false,"fork":false,"pushed_at":"2024-11-20T18:55:00.000Z","size":507,"stargazers_count":27,"open_issues_count":8,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-20T19:39:28.083Z","etag":null,"topics":["okhttp"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"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/charleskorn.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-23T04:11:19.000Z","updated_at":"2024-06-17T22:51:39.000Z","dependencies_parsed_at":"2023-10-01T17:25:47.884Z","dependency_job_id":"4ca98e61-dcdc-4b12-a2d7-5175e080b239","html_url":"https://github.com/charleskorn/okhttp-system-keystore","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charleskorn%2Fokhttp-system-keystore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charleskorn%2Fokhttp-system-keystore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charleskorn%2Fokhttp-system-keystore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charleskorn%2Fokhttp-system-keystore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charleskorn","download_url":"https://codeload.github.com/charleskorn/okhttp-system-keystore/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227961821,"owners_count":17847838,"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":["okhttp"],"created_at":"2024-12-03T17:00:47.485Z","updated_at":"2024-12-03T17:00:48.550Z","avatar_url":"https://github.com/charleskorn.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# okhttp-system-keystore\n\n[![CI](https://github.com/charleskorn/okhttp-system-keystore/actions/workflows/ci.yml/badge.svg)](https://github.com/charleskorn/okhttp-system-keystore/actions/workflows/ci.yml)\n[![License](https://img.shields.io/github/license/charleskorn/okhttp-system-keystore.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Maven Central](https://img.shields.io/maven-central/v/com.charleskorn.okhttp.systemkeystore/okhttp-system-keystore.svg?label=maven%20central)](https://search.maven.org/artifact/com.charleskorn.okhttp.systemkeystore/okhttp-system-keystore)\n\nAutomatically use trusted certificates from the operating system native certificate trust system with [OkHttp](https://github.com/square/okhttp).\n\nSupports Keychain on macOS and Certificate Store on Windows, in addition to any certificates in the local JVM's default keystore.\n\n## Why would you want to do this?\n\nThere are a couple of scenarios where using the operating system certificate trust system can be useful:\n\n* when communicating with servers that present a self-signed certificate, such as local test servers\n\n* when communicating with servers that present a certificate signed by a private certificate authority (CA), such as private services signed by an \n  organisation's internal CA\n  \n* when communicating with servers via an encryption-terminating proxy, which is common in corporate environments where network administrators\n  want to be able to intercept and examine all encrypted traffic flowing through their network\n\nIn all of these scenarios, it's usually easier to add the certificate required to the operating system's certificate trust store rather than the local JVM's\ndefault keystore. However, by default, JVM-based applications use only the JVM's default keystore, which means connecting to servers will fail due to not\ntrusting the certificate presented. \n\nThis library provides a convenience method to configure OkHttp to use the operating system's native certificate trust system in addition to\nthe JVM's default keystore, allowing your application to communicate in situations such as these while still verifying that the certificate presented is trustworthy.\n\n## Setup\n\nIn Gradle:\n\n```kotlin\ndependencies {\n  implementation(\"com.charleskorn.okhttp.systemkeystore:okhttp-system-keystore:\u003cversion number here\u003e\") // Get the latest version number from https://github.com/charleskorn/okhttp-system-keystore/releases/latest\n}\n```\n\nCheck the [releases page](https://github.com/charleskorn/okhttp-system-keystore/releases) for the latest release information, and the \n[Maven Central page](https://search.maven.org/artifact/com.charleskorn.okhttp.systemkeystore/okhttp-system-keystore) for examples of how to reference the library in other build systems.\n\n### macOS security note\n\n:warning: On macOS, it's highly recommended that this library only be used with versions of the JDK that contain a fix for JDK-8278449\n(\"Only Expose Certificates With Proper Trust Settings as Trusted Certificate Entries in macOS KeychainStore\").\n\nWithout this fix, certificates marked as 'never trust' in your certificate trust settings will be treated as trusted by Java. \n\nThe following versions of the JDK contain a fix for this issue:\n\n* JDK 8: 8u332 or later\n* JDK 11: 11.0.15 or later\n* JDK 17: 17.0.3 or later\n* JDK 18: 18.0.1 or later\n* All versions of JDK 19 or later\n\n## Usage\n\nCall `useOperatingSystemCertificateTrustStore()` when building your OkHttp client:\n\n```kotlin\nimport com.charleskorn.okhttp.systemkeystore\n\nval client = OkHttpClient.Builder()\n    .useOperatingSystemCertificateTrustStore()\n    .build()\n```\n\n## Behaviour\n\nOn Windows: uses both user-trusted and machine-trusted root CA certificates, in addition to the local JVM's default keystore.\n\nOn macOS: uses trusted certificates from the user's `login` keychain, in addition to the local JVM's default keystore.\n\nOn all other operating systems: uses only the local JVM's default keystore (which is what OkHttp uses by default).\n\n## Contributing\n\nThis project uses Gradle. \n\nRun linting and tests with `./gradlew check`.\n\n### macOS-specific notes\n\nThe tests need to temporarily add certificates to your local keychain. Therefore, when the tests run you will need to approve adding each certificate (two in total) by entering your password or using Touch ID. \n\n### Windows-specific notes\n\nThe tests need to temporarily add a certificate trusted at the machine-wide level. Therefore, you must run tests from an elevated (administrator) terminal.\n\nIf you are using an elevated terminal and still encounter issues, try disabling the Gradle daemon with `--no-daemon`, for example. `./gradlew --no-daemon check`.\n(The Gradle daemon might have started un-elevated, disabling the daemon ensures that it runs with the same level of access as your terminal.)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharleskorn%2Fokhttp-system-keystore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharleskorn%2Fokhttp-system-keystore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharleskorn%2Fokhttp-system-keystore/lists"}