{"id":22859377,"url":"https://github.com/stevenjdh/simple-ssl","last_synced_at":"2025-03-31T08:20:18.261Z","repository":{"id":41515614,"uuid":"398708204","full_name":"StevenJDH/simple-ssl","owner":"StevenJDH","description":"A lightweight library to easily create SSLContext instances from KeyStore and PEM files with different formats.","archived":false,"fork":false,"pushed_at":"2024-01-27T16:23:15.000Z","size":607,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-06T12:48:00.406Z","etag":null,"topics":["certificate","https","java","keystore","pem","pkcs1","pkcs12","pkcs8","private-key","publick-key","rsa","ssl","sslcontext","tls","truststore","x509"],"latest_commit_sha":null,"homepage":"","language":"Java","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/StevenJDH.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":"2021-08-22T03:50:13.000Z","updated_at":"2023-03-02T00:38:31.000Z","dependencies_parsed_at":"2025-02-06T12:41:34.522Z","dependency_job_id":"9e2aec07-2859-4ba5-94b1-f52f736cc055","html_url":"https://github.com/StevenJDH/simple-ssl","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StevenJDH%2Fsimple-ssl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StevenJDH%2Fsimple-ssl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StevenJDH%2Fsimple-ssl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StevenJDH%2Fsimple-ssl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StevenJDH","download_url":"https://codeload.github.com/StevenJDH/simple-ssl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246436340,"owners_count":20776995,"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":["certificate","https","java","keystore","pem","pkcs1","pkcs12","pkcs8","private-key","publick-key","rsa","ssl","sslcontext","tls","truststore","x509"],"created_at":"2024-12-13T09:06:47.818Z","updated_at":"2025-03-31T08:20:18.241Z","avatar_url":"https://github.com/StevenJDH.png","language":"Java","funding_links":["https://www.buymeacoffee.com/stevenjdh","https://www.paypal.me/stevenjdh"],"categories":[],"sub_categories":[],"readme":"# Simple SSL\n\n[![build](https://github.com/StevenJDH/simple-ssl/actions/workflows/maven-sonar-workflow.yml/badge.svg?branch=main)](https://github.com/StevenJDH/simple-ssl/actions/workflows/maven-sonar-workflow.yml)\n![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/StevenJDH/simple-ssl?include_prereleases\u0026logo=github\u0026logoColor=lightgrey)\n[![Maven Central](https://img.shields.io/maven-central/v/io.github.stevenjdh/simple-ssl?logo=java)](https://mvnrepository.com/artifact/io.github.stevenjdh/simple-ssl)\n[![Sonatype Nexus (Snapshots)](https://img.shields.io/nexus/s/io.github.stevenjdh/simple-ssl?logo=java\u0026server=https%3A%2F%2Fs01.oss.sonatype.org)](https://s01.oss.sonatype.org/content/repositories/snapshots/io/github/stevenjdh/simple-ssl/)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/48f1f6d78ce04a269402694189199fa3)](https://www.codacy.com/gh/StevenJDH/simple-ssl/dashboard?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=StevenJDH/simple-ssl\u0026amp;utm_campaign=Badge_Grade)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=StevenJDH_simple-ssl\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=StevenJDH_simple-ssl\u0026metric=sqale_rating)](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=StevenJDH_simple-ssl\u0026metric=reliability_rating)](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)\n[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=StevenJDH_simple-ssl\u0026metric=sqale_index)](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)\n[![Sonar Violations (long format)](https://img.shields.io/sonar/violations/StevenJDH_simple-ssl?format=long\u0026server=https%3A%2F%2Fsonarcloud.io)](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=StevenJDH_simple-ssl\u0026metric=security_rating)](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=StevenJDH_simple-ssl\u0026metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=StevenJDH_simple-ssl\u0026metric=coverage)](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)\n[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=StevenJDH_simple-ssl\u0026metric=ncloc)](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)\n![Maintenance](https://img.shields.io/maintenance/yes/2024)\n![GitHub](https://img.shields.io/github/license/StevenJDH/simple-ssl)\n\nSimple SSL is a lightweight library to easily create SSLContext instances from KeyStore and PEM files with different formats. Similar to how the native HttpClient works, the library makes use of the builder pattern to expose optional methods that can be used to customize a context without having to constantly rewrite the same blocks of code that would otherwise be required to do the same for many projects. With the resulting context, a secure connection can be established between a client and a server with or without mutual authentication (mTLS) to safeguard sensitive information.\n\n[![Buy me a coffee](https://img.shields.io/static/v1?label=Buy%20me%20a\u0026message=coffee\u0026color=important\u0026style=flat\u0026logo=buy-me-a-coffee\u0026logoColor=white)](https://www.buymeacoffee.com/stevenjdh)\n\nReleases: [https://github.com/StevenJDH/simple-ssl/releases](https://github.com/StevenJDH/simple-ssl/releases)\n\n## Features\n* Load KeyStores/TrustStores in PKCS#12 and JKS formats (*.p12, *.pfx, *.jks, *.ks).\n* Load Base64 encoded X.509 certificates and certificate chains (*.pem, *.crt, *.cer, *.pub).\n* Load Base64 encoded encrypted/unencrypted private keys in PKCS#1 and PKCS#8 formats (*.pem, *.key).\n* Certificate utilities for common tasks.\n* Support for overriding to provide different implementations.\n\n## Prerequisites\n* Java 17+ ([Temurin/Adopt](https://adoptium.net)) OpenJDK.\n* Optional: [Maven](https://maven.apache.org) 3.8.4+ CLI for compiling.\n\n## Installing the library\nThe following shows you how to set up a maven project to make use of this library for both releases and snapshots.\n\n### Add the dependency\nAdd the dependency to the project's `pom.xml` file like in any other maven project.\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.stevenjdh\u003c/groupId\u003e\n    \u003cartifactId\u003esimple-ssl\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nBy default, releases are downloaded from the Maven Central Repository except for snapshots. To download snapshots, see [Enable OSSRH Nexus Repository Snapshots](#enable-ossrh-nexus-repository-snapshots).\n\n### Enable OSSRH Nexus Repository Snapshots\nSnapshot releases like `1.0.0-SNAPSHOT` are managed in a separate repository, and therefore, are not synced to the Maven Central Repository. To enable access to snapshot releases, add the following `repository` section to the project's `pom.xml` file.\n\n```xml\n\u003cproject\u003e\n\u003c!-- [...] --\u003e\n    \u003crepositories\u003e\n        \u003crepository\u003e\n            \u003cid\u003eossrh-snapshots\u003c/id\u003e\n            \u003cname\u003eOSSRH Nexus Repository Snapshots\u003c/name\u003e\n            \u003curl\u003ehttps://s01.oss.sonatype.org/content/repositories/snapshots/\u003c/url\u003e\n            \u003creleases\u003e\n                \u003cenabled\u003efalse\u003c/enabled\u003e\n            \u003c/releases\u003e\n            \u003csnapshots\u003e\n                \u003cenabled\u003etrue\u003c/enabled\u003e\n            \u003c/snapshots\u003e\n        \u003c/repository\u003e\n    \u003c/repositories\u003e\n\u003c!-- [...] --\u003e\n\u003c/project\u003e\n```\n\nAlternatively, add the below `profile` section to your global `settings.xml` file located in the `%USERPROFILE%\\.m2\\` folder on Windows and in the `~/.m2/` directory on Linux if you do not want to define this repository in the `pom.xml` file. However, the disadvantage here is that this won't be committed to your repo, so other contributors will have to do the same.\n\n```xml\n\u003csettings\u003e\n\u003c!-- [...] --\u003e\n    \u003cprofiles\u003e\n        \u003cprofile\u003e\n            \u003cid\u003eallow-snapshots\u003c/id\u003e\n            \u003cactivation\u003e\n                \u003cactiveByDefault\u003etrue\u003c/activeByDefault\u003e\n            \u003c/activation\u003e\n            \u003crepositories\u003e\n                \u003crepository\u003e\n                    \u003cid\u003eossrh-snapshots\u003c/id\u003e\n                    \u003cname\u003eOSSRH Nexus Repository Snapshots\u003c/name\u003e\n                    \u003curl\u003ehttps://s01.oss.sonatype.org/content/repositories/snapshots/\u003c/url\u003e\n                    \u003creleases\u003e\n                        \u003cenabled\u003efalse\u003c/enabled\u003e\n                    \u003c/releases\u003e\n                    \u003csnapshots\u003e\n                        \u003cenabled\u003etrue\u003c/enabled\u003e\n                    \u003c/snapshots\u003e\n                \u003c/repository\u003e\n            \u003c/repositories\u003e\n        \u003c/profile\u003e\n    \u003c/profiles\u003e\n\u003c!-- [...] --\u003e\n\u003c/settings\u003e\n```\n\nRemember, snapshots are a development build that will likely change from one day to the next despite keeping the same version number. They should not be used in production code, and they should be treated as a preview release that is buggy with partially implemented features that can break at any time.\n\n### Add GitHub's Apache Maven registry\nThe library can also be downloaded from GitHub's package registry as an alternative to the Maven Central Repository by specifying it in the `repository` section of the project's `pom.xml` file.\n\n```xml\n\u003cproject\u003e\n\u003c!-- [...] --\u003e\n    \u003crepositories\u003e\n        \u003crepository\u003e\n            \u003cid\u003egithub\u003c/id\u003e\n            \u003cname\u003eStevenJDH's GitHub Apache Maven Packages\u003c/name\u003e\n            \u003curl\u003ehttps://maven.pkg.github.com/StevenJDH/simple-ssl\u003c/url\u003e\n            \u003creleases\u003e\n                \u003cenabled\u003etrue\u003c/enabled\u003e\n            \u003c/releases\u003e\n            \u003csnapshots\u003e\n                \u003cenabled\u003etrue\u003c/enabled\u003e\n            \u003c/snapshots\u003e\n        \u003c/repository\u003e\n    \u003c/repositories\u003e\n\u003c!-- [...] --\u003e\n\u003c/project\u003e\n```\n\nAccess to the registry requires authentication to download the publicly available library. To set up the required access, add the following `server` section to your global `settings.xml` file located in the `%USERPROFILE%\\.m2\\` folder on Windows and in the `~/.m2/` directory on Linux.\n\n``` xml\n\u003csettings\u003e\n\u003c!-- [...] --\u003e\n    \u003cservers\u003e\n        \u003cserver\u003e\n            \u003cid\u003egithub\u003c/id\u003e\n            \u003cusername\u003eYOUR_USERNAME\u003c/username\u003e\n            \u003cpassword\u003eYOUR_AUTH_TOKEN\u003c/password\u003e\n        \u003c/server\u003e\n    \u003c/servers\u003e\n\u003c!-- [...] --\u003e\n\u003c/settings\u003e\n```\n\nReplace `YOUR_USERNAME` with your GitHub login name, and replace `YOUR_AUTH_TOKEN` with a GitHub generated personal access token from _GitHub_ \u003e _Settings_ \u003e _Developer Settings_ \u003e _Personal access tokens_ and by clicking on the `Generate new token` button. The token needs to have at least `read:packages` scope or you will get a `Not authorized` exception. For more information, see [Working with the Apache Maven registry](https://help.github.com/en/articles/configuring-apache-maven-for-use-with-github-package-registry). Also, see the [Password Encryption](https://maven.apache.org/guides/mini/guide-encryption.html) guide to better secure any passwords defined in the `settings.xml` file.\n\n## Using the library\nAs the name implies, the use of the library is simple. See a few examples below to get started.\n\nGenerating the default SSLContext:\n\n```java\nvar ctx = SimpleSSLContext.newSSLContext();\n```\n\nCreating an SSLContext from an existing keystore and or truststore using the default PKCS12 format:\n\n```java\nvar ctx = SimpleSSLContext.newBuilder()\n        .withKeyStore(path, \"password\")\n        .withTrustStore(path, \"password\")\n        .build();\n```\n\nCreating an SSLContext from a PEM file while changing the default format to JKS, and saving the result:\n\n```java\nvar ctx = SimpleSSLContext.newPEMContextBuilder()\n        .withPublicKey(path)\n        .saveTrustStore(path, \"password\", KeyStoreType.JKS)\n        .build();\n```\n\nGet a certificate's thumbprint in SHA-1 using one of the certificate utilities:\n\n```java\nString sha1 = CertUtil.getThumbprint(certificate, \":\", HashType.SHA_1);\n```\n\nProgrammatically access different git properties from when the library was built:\n\n```java\nString buildVersion = SimpleSSLContext.getBuildInfo().getGitBuildVersion();\n```\n\n### Working example\nThis example creates a custom SSLContext with a truststore for `https://untrusted-root.badssl.com` and applies it to a native HttpClient instance. To begin, download the certificate to trust with the following command as one approach:\n\n```bash\nopenssl s_client -connect untrusted-root.badssl.com:443 \u003e untrusted-root.badssl.com.cer\n```\n\nCreate a maven project with the simple-ssl library added to it, and configure the `main` method with the following statements:\n\n```java\npublic static void main(String[] args)\n{\n    var ctx = SimpleSSLContext.newPEMContextBuilder()\n            .withPublicKey(Path.of(\"untrusted-root.badssl.com.cer\"))\n            .build();\n\n    var client = HttpClient.newBuilder()\n            .sslContext(ctx) // Comment this out to see it fail.\n            .build();\n\n    var request = HttpRequest.newBuilder()\n            .uri(URI.create(\"https://untrusted-root.badssl.com\"))\n            .build();\n\n    var response = client.send(request, BodyHandlers.ofString());\n\n    System.out.println(response.body());\n}\n```\n\nIf all goes well, the connection should succeed since the untrusted certificate has been trusted in the truststore that was dynamically created from the supplied PEM formatted certificate. For more ideas around usage, have a look at the different unit and integration tests available in this repository.\n\n## Documentation\nReview Simple SSL's [API documentation](https://stevenjdh.github.io/simple-ssl/apidocs) for technical content containing details about methods, classes, return types, arguments, and more to effectively use and integrate the library as part of a solution. This is a work in progress (WIP), so more content will be added slowly as time permits.\n\n## GPG integrity check\nI have digitally signed all releases and associated artifacts as required by the Maven Central Repository. To make use of this for integrity checks, download my public key from the Ubuntu Key Server into your keyring using the following command:\n\n```bash\ngpg --keyserver keyserver.ubuntu.com --recv-keys 2631EDD2F6035B6B03A590147C7EF877C4E5B44E\n```\n\nThen, download the associated *.asc file of the package you want to verify, and issue the following command to perform the check:\n\n```bash\ngpg --verify simple-ssl-1.0.0.jar.asc simple-ssl-1.0.0.jar\n```\n\nThere should be a good signature response in the output if the integrity check passed. For more information, see [Verify dependencies using PGP](http://branchandbound.net/blog/security/2012/08/verify-dependencies-using-pgp/), and if not already installed, see [GnuPG Binary Releases](https://gnupg.org/download/index.html) for the needed OS.\n\n## Contributing\nThanks for your interest in contributing! There are many ways to contribute to this project. Get started [here](https://github.com/StevenJDH/.github/blob/main/docs/CONTRIBUTING.md).\n\n## Do you have any questions?\nMany commonly asked questions are answered in the FAQ:\n[https://github.com/StevenJDH/simple-ssl/wiki/FAQ](https://github.com/StevenJDH/simple-ssl/wiki/FAQ)\n\n## Community contact\nFeel free to contact me with any questions you may have, and I'll make sure to answer them as soon as possible!\n\n| Platform  | Link        |\n|:----------|:------------|\n| 💬 Instant Message Chat (preferred) | [![Discord Banner](https://discord.com/api/guilds/851210657318961233/widget.png?style=banner2)](https://discord.gg/VzzzjetTkT)\n\nAnnouncements of new releases and other topics of interest will be shared via the preferred channel.\n\n## Want to show your support?\n\n|Method          | Address                                                                                   |\n|---------------:|:------------------------------------------------------------------------------------------|\n|PayPal:         | [https://www.paypal.me/stevenjdh](https://www.paypal.me/stevenjdh \"Steven's Paypal Page\") |\n|Cryptocurrency: | [Supported options](https://github.com/StevenJDH/StevenJDH/wiki/Donate-Cryptocurrency)    |\n\n\n// Steven Jenkins De Haro (\"StevenJDH\" on GitHub)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstevenjdh%2Fsimple-ssl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstevenjdh%2Fsimple-ssl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstevenjdh%2Fsimple-ssl/lists"}