Cheat sheet for secure connection in Java

The standard Java package that provides an abstraction over secure network communication (certificate management, handshaking and verification) is javax.net.ssl. The most popular protocol which developers have to deal with is the HTTPS. HTTPS is the secure version of the request-response HTTP (RFC 2616) protocol. It can be either implemented over SSL or a more secure and upgraded version – TLS.

The support for various protocol versions and ciphers in Java is implemented in the form of a pluggable security architecture through the means of security providers. By default, at least one security provider is distributed with JRE/JDK and if needed a third-party provider can be added.

For example, at the moment of writing this, Oracle JRE8/JDK8 does not provide support for TLS 1.3, though it is planned for 2020-07-14. Meanwhile, you can enjoy TLS 1.3 on Java 11 and on Azul's Zing/Zulu Java 8 JVMs/JDKs.

Customizing the secure connection

A security provider is injected into the SSLContext which is used for initiating the connection. The default supported protocols can be seen by querying SSLContext parameters SSLContext.getDefault().getSupportedSSLParameters().getProtocols(). To restrict the list only to the chosen protocols, we can use setEnabledProtocols(String[] protocols) method of the SSLContext.

Let's check first what elements are there to initialize the context:

            SSLContext context = SSLContext.getInstance("TLSv1.2");
context.init(keyManagerFactory.getKeyManagers(), trustManagerFactory.getTrustManagers(), null);
         

            KeyStore ks = KeyStore.getInstance("JKS");
char[] password = "changeit".toCharArray();
try (FileInputStream fis = FileInputStream("path/to/keystore")) {
    ks.load(fis, password);
}
         

            KeyManagerFactory kmf = KeyManagerFactory.getInstance(ksAlgorithm);
kmf.init(ks, password);
TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
tmf.init((KeyStore) null); // Default keystore will be used
         

Most of the HTTP clients support customizing the connection through the SSLContext class. In general, the default configuration provided by the JDK/JRE would often suffice when making a secure connection as a client. Unless of course the server also requires a valid certificate from us. In such a case, we will have to prove our identity through the KeyManager.

Some examples of the final link between the secure connection configuration and client/connection classes:

// javax.net.ssl
HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
connection.setSSLSocketFactory(sslContext.getSocketFactory());
connection.setHostnameVerifier(hostnameVerifier);

// org.apache.httpcomponents:httpclient:4.5
CloseableHttpClient httpClient = HttpClientBuilder.create()
    .setSSLContext(sslContext)
    .setHostnameVerifier(hostnameVerifier)
    .build();

// com.squareup.okhttp3:okhttp:4.x
OkHttpClient okHttpClient = OkHttpClient.Builder()
    .sslSocketFactory(sslContext.getSocketFactory(), trustManager)
    .hostnameVerifier(hostnameVerifier)
    .build()

// org.glassfish.jersey.core:jersey-client:2.x
Client jerseyClient = ClientBuilder.newBuilder()
    .sslContext(sslContext)
    .hostnameVerifier(hostnameVerifier)
    .build();

To manage key stores, create CSR (Certificate Signing Request – to be signed by a Certification Authority) we use the keytool command-line program included in JRE/JDK bin directory. For some popular commands, refer to the SSL Shopper's article.

When in doubt why the standard configuration does not work, it's always a good idea to check the validity of the site certificate, domain name, and trust chain unless the certificate is self-signed and imported into the trust store (if so, verify this too).

Often though, on the servers, checking the certificate through the browser isn't a feasible scenario as they're usually run in a headless mode. You can still use some command-line tools like curl or openssl to extract the certificate in such a situation.

Cheers, and stay safe!