Execute mTLS Calls Using Java

Supposing we have an NGINX instance secured using SSL and mTLS. If you are using Java interacting with a service secured with mTLS, it requires some changes on your codebase. In this tutorial, we shall enable our Java application to use mTLS using different clients.

To get started fast, we can use an existing example of adding mTLS to an NGINX instance. Our java mTLS configuration will use the certificates and keys used to add mTLS to an NGINX.

In order to make SSL configurations for our Java clients, we need to first set up an SSLContext. This simplifies things since that SSLContext can be used for various http clients that are out there.

Since we have the client’s public and private keys, we need to convert the private key from PEM format to DER.

kcs8 -topk8 -inform PEM -outform PEM -in /path/to/generated/client.key -out /path/to/generated/client.key.pkcs8 -nocrypt

By using a local NGINX service for this example, we need to disable the hostname verification.

final Properties props = System.getProperties();
props.setProperty("jdk.internal.httpclient.disableHostnameVerification", Boolean.TRUE.toString());

In other clients, this might need to set up a HostVerifier that accepts all connections.

HostnameVerifier allHostsValid = new HostnameVerifier() {
    public boolean verify(String hostname, SSLSession session) {
        return true;

The next step is to load the client keys into java code and create a KeyManagerFactory.

String privateKeyPath = "/path/to/generated/client.key.pkcs8";
String publicKeyPath = "/path/to/generated/client.crt";
final byte[] publicData = Files.readAllBytes(Path.of(publicKeyPath));
final byte[] privateData = Files.readAllBytes(Path.of(privateKeyPath));
String privateString = new String(privateData, Charset.defaultCharset())
        .replace("-----BEGIN PRIVATE KEY-----", "")
        .replaceAll(System.lineSeparator(), "")
        .replace("-----END PRIVATE KEY-----", "");
byte[] encoded = Base64.getDecoder().decode(privateString);
final CertificateFactory certificateFactory = CertificateFactory.getInstance("X.509");
final Collection<? extends Certificate> chain = certificateFactory.generateCertificates(
        new ByteArrayInputStream(publicData));
Key key = KeyFactory.getInstance("RSA").generatePrivate(new PKCS8EncodedKeySpec(encoded));
KeyStore clientKeyStore = KeyStore.getInstance("jks");
final char[] pwdChars = "test".toCharArray();
clientKeyStore.load(null, null);
clientKeyStore.setKeyEntry("test", key, pwdChars, chain.toArray(new Certificate[0]));
KeyManagerFactory keyManagerFactory = KeyManagerFactory.getInstance("SunX509");
keyManagerFactory.init(clientKeyStore, pwdChars);

In the above snippet:

  • We read the bytes from the files.
  • We created a certificate chain from the public key.
  • We created a key instance using the private key.
  • Created a Keystore using the chain and keys
  • Created a KeyManagerFactory

Now that we have a KeyManagerFactory created we can use it to create an SSLContext.

Due to using self-signed certificates, we need to use a TrustManager that will accept them. In this example, the Trust Manager will accept all certificates presented from the server.

TrustManager[] acceptAllTrustManager = {
                new X509TrustManager() {
                    public X509Certificate[] getAcceptedIssuers() {
                        return new X509Certificate[0];
                    public void checkClientTrusted(
                            X509Certificate[] certs, String authType) {
                    public void checkServerTrusted(
                            X509Certificate[] certs, String authType) {

Then the SSL context initialization.

SSLContext sslContext = SSLContext.getInstance("TLS");
sslContext.init(keyManagerFactory.getKeyManagers(), acceptAllTrustManager, new java.security.SecureRandom());

Let’s use a client and see how it behaves.

HttpClient client = HttpClient.newBuilder()
       HttpRequest exactRequest = HttpRequest.newBuilder()
       var exactResponse = client.sendAsync(exactRequest, HttpResponse.BodyHandlers.ofString())

We shall receive a 404 code (default for that NGINX installation )which means that our request had a successful mTLS handshake.

Now let’s try with another client, the old school synchronous HttpsURLConnection. Pay attention: I use the allHostsValid previously created.

HttpsURLConnection httpsURLConnection = (HttpsURLConnection)   new URL("").openConnection();
InputStream  inputStream = httpsURLConnection.getInputStream();
String result =  new String(inputStream.readAllBytes(), Charset.defaultCharset());

This will throw a 404 error which means that the handshake took place successfully.

So whether you have an async HTTP client or asynchronous one, provided you have the right SSLContext configured you should be able to do the handshake.


Leave a Comment