Popularity
2.8
Growing
Activity
7.4
Growing
97
3
17

Programming language: Java
License: Apache License 2.0
Tags: Security     Projects    

SSLContext-Kickstart alternatives and similar libraries

Based on the "Security" category.
Alternatively, view SSLContext-Kickstart alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of SSLContext-Kickstart or a related project?

Add another 'Security' Library

README

Actions Status Security Rating Known Vulnerabilities Coverage Apache2 license Maven Central javadoc Join the chat at https://gitter.im/hakky54/sslcontext-kickstart

SonarCloud

SSLContext Kickstart Tweet

Install library with:

Install with Maven

<dependency>
    <groupId>io.github.hakky54</groupId>
    <artifactId>sslcontext-kickstart</artifactId>
    <version>5.2.3</version>
</dependency>

Install with Gradle

implementation 'io.github.hakky54:sslcontext-kickstart:5.2.3'

Install with Scala SBT

libraryDependencies += "io.github.hakky54" % "sslcontext-kickstart" % "5.2.3"

Install with Apache Ivy

<dependency org="io.github.hakky54" name="sslcontext-kickstart" rev="5.2.3" />

Table of contents

  1. Introduction
  2. Usage
  3. Additional mappers for specific libraries
  4. Tested HTTP Clients

Introduction

SSLContext Kickstart is a library which provides a High-Level Factory class for configuring a http client to communicate over SSL/TLS for one way authentication or two way authentication.

History

As a Java developer I worked for different kinds of clients. Most of the time the application required to call other microservices within the organization or some other http servers. It was required to be HTTPS configured and so I began writing the code which was needed to configure the Http Client to communicate over ssl/tls. And every time I needed to write almost the same code over and over again which is in my opinion very verbose and hard to unit test.

As a developer you need to know how to properly load your file into your application and consume it as a KeyStore instance. Therefor you also need to learn how to properly create a KeyManagerFactory, TrustManagerFactory and SSLContext. Traditional creation of SSLContext can be rewritten if you use a Http Client which relies on libraries of Jetty or Netty and therefor it makes it even more complex. The sslcontext-kickstart library is taking the responsibility of creating an instance of SSLContext from the provided arguments. I wanted to be as easy as possible to use to give every developer a kickstart when configuring their Http Client. So feel free to provide feedback or feature requests. The library also provide other utilities such as [KeyStoreUtils](sslcontext-kickstart/src/main/java/nl/altindag/sslcontext/util/KeyStoreUtils.java), [KeyManagerUtils](sslcontext-kickstart/src/main/java/nl/altindag/sslcontext/util/KeyManagerUtils.java) and [TrustManagerUtils](sslcontext-kickstart/src/main/java/nl/altindag/sslcontext/util/TrustManagerUtils.java). See the javadoc for all the options.

Acknowledgement

I would like to thank Cody A. Ray for his contribution to the community regarding loading multiple Keystores into the SSLContext. The limitation of the JDK is to only support one keystore for the KeyManagerFactory and only one keystore for the TrustManagerFactory. The code snippets which Cody has shared are now available within this library and can be found here: [CompositeX509KeyManager](sslcontext-kickstart/src/main/java/nl/altindag/sslcontext/keymanager/CompositeX509ExtendedKeyManager.java) and [CompositeX509TrustManager](sslcontext-kickstart/src/main/java/nl/altindag/sslcontext/trustmanager/CompositeX509ExtendedTrustManager.java)

The original article can be found here: Codyaray - Java SSL with Multiple KeyStores.

Advantages:

  • No need for low-level SSLContext configuration anymore
  • No knowledge needed about SSLContext, TrustManager, TrustManagerFactory, KeyManager, KeyManagerFactory and how to create it.
  • Above classes will all be created with just providing an identity and a trustStore
  • Load multiple identities/trustStores/keyManagers/trustManagers

Definitions

  • Identity: A KeyStore which holds the key pair also known as private and public key
  • TrustStore: A KeyStore containing one or more certificates also known as public key. This KeyStore contains a list of trusted certificates
  • One way authentication (also known as one way tls, one way ssl): Https connection where the client validates the certificate of the counter party
  • Two way authentication (also known as two way tls, two way ssl, mutual authentication): Https connection where the client as well as the counter party validates the certificate, also known as mutual authentication

Usage

Example configuration

Example configuration with apache http client, or see here for other clients: ClientConfig class

import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import org.json.JSONException;
import org.json.JSONObject;

import nl.altindag.sslcontext.SSLFactory;

public class App {

    public static void main(String[] args) throws IOException, JSONException {
        SSLFactory sslFactory = SSLFactory.builder()
                .withDefaultTrustMaterial()
                .build();

        HttpClient httpClient = HttpClients.custom()
                .setSSLContext(sslFactory.getSslContext())
                .setSSLHostnameVerifier(sslFactory.getHostnameVerifier())
                .build();

        HttpGet request = new HttpGet("https://api.chucknorris.io/jokes/random");

        HttpResponse response = httpClient.execute(request);
        String chuckNorrisJoke = new JSONObject(EntityUtils.toString(response.getEntity())).getString("value");

        System.out.println(String.format("Received the following status code: %d", response.getStatusLine().getStatusCode()));
        System.out.println(String.format("Received the following joke: %s", chuckNorrisJoke));
    }

}

Response:

Received the following status code: 200
Received the following joke: If a black cat crosses your path, you have bad luck. If Chuck Norris crosses your path, it was nice knowing you.

The SSLFactory provides other useful options, see below for all the returnable values:

import nl.altindag.sslcontext.SSLFactory;
import nl.altindag.sslcontext.model.KeyStoreHolder;

import javax.net.ssl.HostnameVerifier;
import javax.net.ssl.SSLContext;
import javax.net.ssl.X509ExtendedKeyManager;
import javax.net.ssl.X509ExtendedTrustManager;
import java.security.cert.X509Certificate;
import java.util.List;
import java.util.Optional;

public class App {

    public static void main(String[] args) {
        SSLFactory sslFactory = SSLFactory.builder()
                .withIdentityMaterial("keystore.p12", "secret".toCharArray(), "PKCS12")
                .withTrustMaterial("truststore.p12", "secret".toCharArray(), "PKCS12")
                .build();

        SSLContext sslContext = sslFactory.getSslContext();
        HostnameVerifier hostnameVerifier = sslFactory.getHostnameVerifier();
        Optional<X509ExtendedKeyManager> keyManager = sslFactory.getKeyManager();
        Optional<X509ExtendedTrustManager> trustManager = sslFactory.getTrustManager();
        List<X509Certificate> trustedCertificates = sslFactory.getTrustedCertificates();
        List<KeyStoreHolder> identities = sslFactory.getIdentities();
        List<KeyStoreHolder> trustStores = sslFactory.getTrustStores();
    }

}

Other possible configurations

One way authentication with custom trustStore

SSLFactory.builder()
          .withTrustMaterial(trustStore, trustStorePassword)
          .build();

One way authentication while trusting all certificates without validation, not recommended to use at production!

SSLFactory.builder()
          .withTrustingAllCertificatesWithoutValidation()
          .build();

One way authentication with custom secure random and option to validate the hostname within the request against the SAN field of a certificate. If you are using java 11 or newer, than you are also able to use TLSv1.3 as encryption protocol by default.

SSLFactory.builder()
          .withTrustMaterial(trustStore, trustStorePassword)
          .withHostnameVerifier(hostnameVerifier)
          .withSecureRandom(secureRandom)
          .build();

Two way authentication with custom trustStore, hostname verifier and encryption protocol version

SSLFactory.builder()
          .withIdentityMaterial(identity, identityPassword)
          .withTrustMaterial(trustStore, trustStorePassword)
          .withHostnameVerifier(hostnameVerifier)
          .build();

Support for using multiple identity materials and trust materials

SSLFactory.builder()
          .withIdentityMaterial(identityA, identityPasswordA)
          .withIdentityMaterial(identityB, identityPasswordB)
          .withIdentityMaterial(identityC, identityPasswordC)
          .withTrustMaterial(trustStoreA, trustStorePasswordA)
          .withTrustMaterial(trustStoreB, trustStorePasswordB)
          .withTrustMaterial(trustStoreC, trustStorePasswordC)
          .withTrustMaterial(trustStoreD, trustStorePasswordD)
          .build();

Support for using X509ExtendedKeyManager and X509ExtendedTrustManager

X509ExtendedKeyManager keyManager = ...
X509ExtendedTrustManager trustManager = ...

SSLFactory.builder()
          .withIdentityMaterial(keyManager)
          .withTrustMaterial(trustManager)
          .build();

Support for using system trust material (only available for Mac and Windows)

SSLFactory.builder()
          .withSystemTrustMaterial()
          .build();

Using PEM Files

Support for using pem formatted private key and certificates from classpath, any directory or as an InputStream. See [PemUtilsShould](sslcontext-kickstart-for-pem/src/test/java/nl/altindag/sslcontext/util/PemUtilsShould.java) for detailed usages. Add only the dependency below to use this feature, it also includes the core features from the library such as SSLFactory.

<dependency>
    <groupId>io.github.hakky54</groupId>
    <artifactId>sslcontext-kickstart-for-pem</artifactId>
    <version>5.2.3</version>
</dependency>
 * EXAMPLE FILES
 *
 * [some-trusted-certificate.pem]
 * -----BEGIN CERTIFICATE-----
 *             ...
 *             ...
 * -----END CERTIFICATE-----
 *
 * [private-key.pem]
 * -----BEGIN PRIVATE KEY-----
 *             ...
 *             ...
 * -----END PRIVATE KEY-----
 *
 * [private-key.pem]
 * -----BEGIN RSA PRIVATE KEY-----
 *             ...
 *             ...
 * -----END RSA PRIVATE KEY-----
 *
 * [private-key.pem]
 * -----BEGIN ENCRYPTED PRIVATE KEY-----
 *             ...
 *             ...
 * -----END ENCRYPTED PRIVATE KEY-----
 */

Example usage:

X509ExtendedKeyManager keyManager = PemUtils.loadIdentityMaterial("certificate.pem", "private-key.pem");
X509ExtendedTrustManager trustManager = PemUtils.loadTrustMaterial("some-trusted-certificate.pem");

SSLFactory.builder()
          .withIdentityMaterial(keyManager)
          .withTrustMaterial(trustManager)
          .build();

Additional mappers for specific libraries

Some http clients relay on different ssl classes from third parties and require mapping from SSLFactory to those libraries. Below you will find the maven dependency which will provide the mapping and also the SSLFactory library. When using one of the below libraries, it is not required to also explicitly include sslcontext-kickstart.

Netty

Some know http clients which relay on netty libraries are: Spring WebFlux WebClient Netty, Async Http Client and Dispatch Reboot Http Client.

<dependency>
    <groupId>io.github.hakky54</groupId>
    <artifactId>sslcontext-kickstart-for-netty</artifactId>
    <version>5.2.3</version>
</dependency>

Example setup for Spring WebClient with Netty:

import io.netty.handler.ssl.SslContext;
import nl.altindag.sslcontext.SSLFactory;
import nl.altindag.sslcontext.util.NettySslContextUtils;
import org.springframework.http.client.reactive.ReactorClientHttpConnector;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.netty.http.client.HttpClient;

import javax.net.ssl.SSLException;

public class App {

    public static void main(String[] args) throws SSLException {
        SSLFactory sslFactory = SSLFactory.builder()
                .withDefaultTrustMaterial()
                .build();

        SslContext sslContext = NettySslContextUtils.forClient(sslFactory).build();
        HttpClient httpClient = HttpClient.create()
                .secure(sslSpec -> sslSpec.sslContext(sslContext));

        WebClient webClient = WebClient.builder()
                .clientConnector(new ReactorClientHttpConnector(httpClient))
                .build();
    }

}

Jetty

<dependency>
    <groupId>io.github.hakky54</groupId>
    <artifactId>sslcontext-kickstart-for-jetty</artifactId>
    <version>5.2.3</version>
</dependency>

Example setup for Spring WebFlux WebClient Jetty:

import nl.altindag.sslcontext.SSLFactory;
import nl.altindag.sslcontext.util.JettySslContextUtils;
import org.eclipse.jetty.client.HttpClient;
import org.eclipse.jetty.util.ssl.SslContextFactory;
import org.springframework.http.client.reactive.JettyClientHttpConnector;
import org.springframework.web.reactive.function.client.WebClient;

public class App {

    public static void main(String[] args) {
        SSLFactory sslFactory = SSLFactory.builder()
                .withDefaultTrustMaterial()
                .build();

        SslContextFactory.Client sslContextFactory = JettySslContextUtils.forClient(sslFactory);
        HttpClient httpClient = new HttpClient(sslContextFactory);

        WebClient webClient = WebClient.builder()
                .clientConnector(new JettyClientHttpConnector(httpClient))
                .build();
    }

}

Apache

Apache Http Client works with javax.net.ssl.SSLContext, so an additional mapping to their library is not required, see here. However it is still possible to configure the http client with their custom configuration class. you can find below an example configuration for that use case:

<dependency>
    <groupId>io.github.hakky54</groupId>
    <artifactId>sslcontext-kickstart-for-apache</artifactId>
    <version>5.2.3</version>
</dependency>
import nl.altindag.sslcontext.SSLFactory;
import nl.altindag.sslcontext.util.ApacheSslContextUtils;
import org.apache.http.client.HttpClient;
import org.apache.http.conn.socket.LayeredConnectionSocketFactory;
import org.apache.http.impl.client.HttpClients;

public class App {

    public static void main(String[] args) {
        SSLFactory sslFactory = SSLFactory.builder()
                .withDefaultTrustMaterial()
                .build();

        LayeredConnectionSocketFactory socketFactory = ApacheSslContextUtils.toLayeredConnectionSocketFactory(sslFactory);

        HttpClient httpClient = HttpClients.custom()
                .setSSLSocketFactory(socketFactory)
                .build();
    }

}

Tested HTTP Clients

Below is a list of clients which have already been tested with examples, see in the ClientConfig class and the service directory for detailed configuration

Java

Kotlin

Scala

There is a github project available named Mutual-tls-ssl which provides a tutorial containing steps for setting up these four scenarios:

  • No security
  • One way authentication
  • Two way authentication
  • Two way authentication with trusting the Certificate Authority

It will also explain how to create KeyStores, Certificates, Certificate Signing Requests and how to implement it.


*Note that all licence references and agreements mentioned in the SSLContext-Kickstart README section above are relevant to that project's source code only.