Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/stevenjdh/simple-ssl
A lightweight library to easily create SSLContext instances from KeyStore and PEM files with different formats.
https://github.com/stevenjdh/simple-ssl
certificate https java keystore pem pkcs1 pkcs12 pkcs8 private-key publick-key rsa ssl sslcontext tls truststore x509
Last synced: 21 days ago
JSON representation
A lightweight library to easily create SSLContext instances from KeyStore and PEM files with different formats.
- Host: GitHub
- URL: https://github.com/stevenjdh/simple-ssl
- Owner: StevenJDH
- License: apache-2.0
- Created: 2021-08-22T03:50:13.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-01-27T16:23:15.000Z (11 months ago)
- Last Synced: 2024-05-01T14:15:08.451Z (8 months ago)
- Topics: certificate, https, java, keystore, pem, pkcs1, pkcs12, pkcs8, private-key, publick-key, rsa, ssl, sslcontext, tls, truststore, x509
- Language: Java
- Homepage:
- Size: 593 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Simple SSL
[](https://github.com/StevenJDH/simple-ssl/actions/workflows/maven-sonar-workflow.yml)
[](https://mvnrepository.com/artifact/io.github.stevenjdh/simple-ssl)
[](https://s01.oss.sonatype.org/content/repositories/snapshots/io/github/stevenjdh/simple-ssl/)
[](https://www.codacy.com/gh/StevenJDH/simple-ssl/dashboard?utm_source=github.com&utm_medium=referral&utm_content=StevenJDH/simple-ssl&utm_campaign=Badge_Grade)
[](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)
[](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)
[](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)
[](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)
[](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)
[](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)
[](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)
[](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)
[](https://sonarcloud.io/dashboard?id=StevenJDH_simple-ssl)
Simple 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.
[](https://www.buymeacoffee.com/stevenjdh)
Releases: [https://github.com/StevenJDH/simple-ssl/releases](https://github.com/StevenJDH/simple-ssl/releases)
## Features
* Load KeyStores/TrustStores in PKCS#12 and JKS formats (*.p12, *.pfx, *.jks, *.ks).
* Load Base64 encoded X.509 certificates and certificate chains (*.pem, *.crt, *.cer, *.pub).
* Load Base64 encoded encrypted/unencrypted private keys in PKCS#1 and PKCS#8 formats (*.pem, *.key).
* Certificate utilities for common tasks.
* Support for overriding to provide different implementations.
## Prerequisites
* Java 17+ ([Temurin/Adopt](https://adoptium.net)) OpenJDK.
* Optional: [Maven](https://maven.apache.org) 3.8.4+ CLI for compiling.
## Installing the library
The following shows you how to set up a maven project to make use of this library for both releases and snapshots.
### Add the dependency
Add the dependency to the project's `pom.xml` file like in any other maven project.
```xml
io.github.stevenjdh
simple-ssl
1.0.0
```
By 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).
### Enable OSSRH Nexus Repository Snapshots
Snapshot 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.
```xml
ossrh-snapshots
OSSRH Nexus Repository Snapshots
https://s01.oss.sonatype.org/content/repositories/snapshots/
false
true
```
Alternatively, 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.
```xml
allow-snapshots
true
ossrh-snapshots
OSSRH Nexus Repository Snapshots
https://s01.oss.sonatype.org/content/repositories/snapshots/
false
true
```
Remember, 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.
### Add GitHub's Apache Maven registry
The 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.
```xml
github
StevenJDH's GitHub Apache Maven Packages
https://maven.pkg.github.com/StevenJDH/simple-ssl
true
true
```
Access 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.
``` xml
github
YOUR_USERNAME
YOUR_AUTH_TOKEN
```
Replace `YOUR_USERNAME` with your GitHub login name, and replace `YOUR_AUTH_TOKEN` with a GitHub generated personal access token from _GitHub_ > _Settings_ > _Developer Settings_ > _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.
## Using the library
As the name implies, the use of the library is simple. See a few examples below to get started.
Generating the default SSLContext:
```java
var ctx = SimpleSSLContext.newSSLContext();
```
Creating an SSLContext from an existing keystore and or truststore using the default PKCS12 format:
```java
var ctx = SimpleSSLContext.newBuilder()
.withKeyStore(path, "password")
.withTrustStore(path, "password")
.build();
```
Creating an SSLContext from a PEM file while changing the default format to JKS, and saving the result:
```java
var ctx = SimpleSSLContext.newPEMContextBuilder()
.withPublicKey(path)
.saveTrustStore(path, "password", KeyStoreType.JKS)
.build();
```
Get a certificate's thumbprint in SHA-1 using one of the certificate utilities:
```java
String sha1 = CertUtil.getThumbprint(certificate, ":", HashType.SHA_1);
```
Programmatically access different git properties from when the library was built:
```java
String buildVersion = SimpleSSLContext.getBuildInfo().getGitBuildVersion();
```
### Working example
This 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:
```bash
openssl s_client -connect untrusted-root.badssl.com:443 > untrusted-root.badssl.com.cer
```
Create a maven project with the simple-ssl library added to it, and configure the `main` method with the following statements:
```java
public static void main(String[] args)
{
var ctx = SimpleSSLContext.newPEMContextBuilder()
.withPublicKey(Path.of("untrusted-root.badssl.com.cer"))
.build();
var client = HttpClient.newBuilder()
.sslContext(ctx) // Comment this out to see it fail.
.build();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://untrusted-root.badssl.com"))
.build();
var response = client.send(request, BodyHandlers.ofString());
System.out.println(response.body());
}
```
If 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.
## Documentation
Review 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.
## GPG integrity check
I 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:
```bash
gpg --keyserver keyserver.ubuntu.com --recv-keys 2631EDD2F6035B6B03A590147C7EF877C4E5B44E
```
Then, download the associated *.asc file of the package you want to verify, and issue the following command to perform the check:
```bash
gpg --verify simple-ssl-1.0.0.jar.asc simple-ssl-1.0.0.jar
```
There 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.
## Contributing
Thanks 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).
## Do you have any questions?
Many commonly asked questions are answered in the FAQ:
[https://github.com/StevenJDH/simple-ssl/wiki/FAQ](https://github.com/StevenJDH/simple-ssl/wiki/FAQ)
## Community contact
Feel free to contact me with any questions you may have, and I'll make sure to answer them as soon as possible!
| Platform | Link |
|:----------|:------------|
| 💬 Instant Message Chat (preferred) | [](https://discord.gg/VzzzjetTkT)
Announcements of new releases and other topics of interest will be shared via the preferred channel.
## Want to show your support?
|Method | Address |
|---------------:|:------------------------------------------------------------------------------------------|
|PayPal: | [https://www.paypal.me/stevenjdh](https://www.paypal.me/stevenjdh "Steven's Paypal Page") |
|Cryptocurrency: | [Supported options](https://github.com/StevenJDH/StevenJDH/wiki/Donate-Cryptocurrency) |
// Steven Jenkins De Haro ("StevenJDH" on GitHub)