Introduction
SSLContext Kickstart is a high level library for configuring a http client to communicate over SSL/TLS for one way authentication or two way authentication.
Below is a quick start; more detailed usage information is available here. See the JavaDocs for full documentation and the Test Source for complete examples of usage.
Details on how to depend on this library in your favourite build tool can be found here.
Getting Started
Basic example with Apache Http Client
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 nl.altindag.ssl.SSLFactory; public class App { public static void main(String[] args) throws IOException { 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); } }
The SSLFactory provides different kinds of returnable values, see below for all the options:
import nl.altindag.ssl.SSLFactory; import nl.altindag.ssl.model.KeyStoreHolder; import javax.net.ssl.HostnameVerifier; import javax.net.ssl.SSLContext; import javax.net.ssl.SSLEngine; import javax.net.ssl.SSLParameters; import javax.net.ssl.SSLServerSocketFactory; import javax.net.ssl.SSLSocketFactory; 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(); SSLSocketFactory sslSocketFactory = sslFactory.getSslSocketFactory(); SSLServerSocketFactory sslServerSocketFactory = sslFactory.getSslServerSocketFactory(); SSLEngine sslEngine = sslFactory.getSslEngine(host, port); SSLParameters sslParameters = sslFactory.getSslParameters(); List<String> ciphers = sslFactory.getCiphers(); List<String> protocols = sslFactory.getProtocols(); } }
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
- Apache HttpClient -> Client configuration | Example request
- Apache HttpAsyncClient -> Client configuration | Example request
- Apache 5 HttpClient -> Client configuration | Example request
- Apache 5 HttpAsyncClient -> Client configuration | Example request
- JDK HttpClient -> Client Configuration | Example request
- Old JDK HttpClient -> Client Configuration & Example request
- Netty Reactor -> Client Configuration | Example request
- Jetty Reactive HttpClient -> Client Configuration | Example request
- Spring RestTemplate -> Client Configuration | Example request
- Spring WebFlux WebClient Netty -> Client Configuration | Example request
- Spring WebFlux WebClient Jetty -> Client Configuration | Example request
- OkHttp -> Client Configuration | Example request
- Jersey Client -> Client Configuration | Example request
- Old Jersey Client -> Client Configuration | Example request
- Apache CXF JAX-RS -> Client Configuration | Example request
- Apache CXF using ConduitConfigurer -> Client Configuration | Example request
- Google HttpClient -> Client Configuration | Example request
- Unirest -> Client Configuration | Example request
- Retrofit -> Client Configuration | Example request
- Async Http Client -> Client Configuration | Example request
- Feign -> Client Configuration | Example request
- Methanol -> Client Configuration | Example request
- Vertx Webclient -> Client Configuration | Example request
- gRPC -> Client/Server Configuration & Example request
- ElasticSearch -> RestHighLevelClient Configuration & example request
Kotlin
- Fuel -> Client Configuration & Example request
- Http4k with Apache 4 -> Client Configuration | Example request
- Http4k with Async Apache 4 -> Client Configuration | Example request
- Http4k with Apache 5 -> Client Configuration | Example request
- Http4k with Async Apache 5 -> Client Configuration | Example request
- Http4k with Java Net -> Client Configuration | Example request
- Http4k with Jetty -> Client Configuration | Example request
- Http4k with OkHttp -> Client Configuration | Example request
- Kohttp -> Client Configuration & Example request
- Ktor with Android engine -> Client Configuration | Example request
- Ktor with Apache engine -> Client Configuration | Example request
- Ktor with CIO (Coroutine-based I/O) engine -> Client Configuration | Example request
- Ktor with Okhttp engine -> Client Configuration | Example request
Scala
- Twitter Finagle -> Client Configuration | Example request
- Twitter Finagle Featherbed -> Client Configuration & Example request
- Akka Http Client -> Client Configuration | Example request
- Dispatch Reboot -> Client Configuration & Example request
- ScalaJ / Simplified Http Client -> Client Configuration & Example request
- Sttp -> Client Configuration & Example request
- Requests-Scala -> Client Configuration & Example request
- Http4s Blaze Client -> Client Configuration | Example request
- Http4s Java Net Client -> Client Configuration | Example request
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.