Execute mTLS Calls Using Java

1. Overview

Security is one of the most important aspects of any software application. It is a non-negotiable aspect. Mutual Transport Layer Security(mTLS) is one of the ways people use to secure their apps. In this article, we’ll learn how to make HTTP calls to a server when mTLS is enabled.

We’ll start with an introduction to mTLS, then we’ll learn how to set up Nginx server with mTLS. Lastly, we’ll use Java clients like HttpsURLConnection and HttpClient to make calls to the server.

 2. What Is mTLS?

Mutual TLS(mTLS) is a security protocol that extends standard TLS by requiring both client and server to present and verify X.509 certificates, enabling two-way authentication. Unlike regular TLS, where only the server proves its identity, mTLS ensures that the client is also verified, making it ideal for high-security environments.

It’s commonly used to secure internal communication between services, authenticate users or devices without passwords, and enforce zero trust security models in micro-services, APIs, and enterprise systems.

3. Setting up Nginx With mTLS

To set up Nginx with mTLS, we’re going to generate the required certificates for the server and client. After the certificates are ready, we’ll configure Nginx with these certificates to enable mTLS.

3.1. Generate Certificates

For mTLS, we need to generate the certificates for the server and the client. We’re going to use self-signed certificates for simplicity. To do this, we’ll need our own certificate authority(CA).

So, let’s set up the certificate authority:

openssl genrsa -des3 -out ca.key 4096
openssl rsa -in ca.key -out ca.key
openssl req -new -x509 -days 3650 -key ca.key -subj "/CN=*.server.hostname" -out ca.crt

The above commands generate a self-signed SSL certificate. First, a 4096-bit RSA private key, viz. ca.key, is created and encrypted using a passphrase with DES3. Then, the passphrase is removed from the key, outputting an unencrypted version of the same key. Finally, a self-signed X.509 certificate ca.crt is generated using the unencrypted private key, valid for ten years, and subject common name set to *.server.hostname. 

Now, our certificate authority(CA) is ready. We can create server and client certificates using this CA. First, let’s create the server private key and certificate.

The first step is to generate the private key:

printf test > server_passphrase.txt
openssl genrsa -des3 -passout file:server_passphrase.txt -out server.key 1024

Just like earlier commands, the above command generates the server private key viz. server.key.

Now, we can generate a certificate signing request(CSR) for the server:

openssl req -new -passin file:server_passphrase.txt -key server.key -subj "/CN=*.server.hostname" -out server.csr

Here, we’ll sign the CSR with the certificate authority that we created earlier:

openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt

Now, the certificate for the server viz. server.crt is ready. Let’s create certificates for the client.

We’re going to use the same CA for the client as well:

printf test > client_passphrase.txt
openssl genrsa -des3 -passout file:client_passphrase.txt -out client.key 2048
openssl rsa -passin file:client_passphrase.txt -in client.key -out client.key
openssl req -new -key client.key -subj "/CN=*.client.hostname" -out client.csr
openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out client.crt

Just like the server, we’ve used the same commands for the client as well to generate keys and certificates. The client.key and client.crt are the private key and certificate, respectively.

3.2. Add mTLS to Nginx

Here, we’re going to configure Nginx with the configurations to serve mTLS requests:

http {
    server {
        listen 443 ssl;
        server_name  test.server.hostname;
        ssl_password_file /etc/nginx/certs/server_passphrase.txt;
        ssl_certificate /etc/nginx/certs/server.crt;
        ssl_certificate_key /etc/nginx/certs/server.key;

        ssl_client_certificate /etc/nginx/certs/ca.crt;
        ssl_verify_client on;
        ssl_verify_depth  3;
 
        ssl_protocols             TLSv1 TLSv1.1 TLSv1.2;

        location /ping {
            proxy_pass http://localhost:9091;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
}

This Nginx configuration sets up an HTTPS server on port 443 with mTLS enabled, requiring clients to present valid certificates signed by a trusted CA. It uses server.crt and server.key as the server’s credentials, reads the private key passphrase from passphrase.txt, and verifies client certificates against ca.crt with a verification depth of 3. The /ping endpoint proxies requests to a local service on port 9091, forwarding the original host and client IP headers for context.

4. Add mTLS to Java Clients

Before calling the above-created Nginx Server with mTLS request, we first need to build SSL configurations for our Java clients. So, let’s learn how to build an SSLContext.

4.1. Build SSLContext

Let’s learn how to create SSLContext step by step.

First, we’ll convert the client private key from PEM format to DER:

openssl pkcs8 -topk8 -inform PEM -outform PEM -in client.key -out 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());

The next step is to load the client keys into Java code and create a KeyManagerFactory:

String privateKeyPath = "/etc/crts/client.key.pkcs8";
String publicKeyPath = "/etc/crts/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 code, bytes are read from the certificate and key files to construct a certificate chain from the public key and a private key instance. These are used to create a Java KeyStore containing both the certificate and private key. Finally, a KeyManagerFactory is initialised with the KeyStore to enable secure SSL/TLS communication.

Due to using self-signed certificates, we need to use a TrustManager that will accept them. The following TrustManager 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) {
    }
 }};

Now, we can initialise an SSLContext with the KeyManagerFactory that we created above:

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

4.2. Using Java Clients

Till now, we’ve set up Nginx server with mTLS on and know how to build an SSLContext. Let’s test all these one by one. First of all, we’ll write a unit test to verify the SSLContext:

@Test
public void whenPrivateAndPublicKeysAreGiven_thenAnSSLContextShouldBeCreated(){
    SSLContext sslContext = SslContextBuilder.buildSslContext();
    Assertions.assertThat(sslContext).isNotNull();
}

Since our SSLContext is ready and working, we can now make mTLS calls to Nginx using Java Clients.

Before testing with Java clients, we need to make sure that we’ve our Nginx up and running. Also we’ve to run a server on port 9091 that serves requests on /ping. We can easily create by following this article. Both components are required in order to pass these tests.

We’ll first test with HttpClient:

@Test
public void whenWeExecuteMutualTLSCallToNginxServerWithHttpClient_thenItShouldReturnStatusOK() {
    SSLContext sslContext = SslContextBuilder.buildSslContext();
    HttpClient client = HttpClient.newBuilder()
      .sslContext(sslContext)
      .build();

    HttpRequest exactRequest = HttpRequest.newBuilder()
      .uri(URI.create("https://localhost/ping"))
      .GET()
      .build();

    HttpResponse<String> response = client.sendAsync(exactRequest, HttpResponse.BodyHandlers.ofString())
      .join();
    Assertions.assertThat(response).isNotNull();
    Assertions.assertThat(response.statusCode()).isEqualTo(200);
}

The above test will call Nginx, and it will route /ping to the server that is running at port 9091. We’ll receive a 200 code, which means that our request had a successful mTLS connection.

Now, we’ll test with HttpsURLConnection:

@Test
public void whenWeExecuteMutualTLSCallToNginxServerWithHttpURLConnection_thenItShouldReturnNonNullResponse() {
    SSLContext sslContext = SslContextBuilder.buildSslContext();
    HttpsURLConnection httpsURLConnection = (HttpsURLConnection) new URL("https://127.0.0.1/ping")
      .openConnection();
    httpsURLConnection.setSSLSocketFactory(sslContext.getSocketFactory());
    httpsURLConnection.setHostnameVerifier(HostNameVerifierBuilder.getAllHostsValid());
    InputStream inputStream = httpsURLConnection.getInputStream();
    String response = new String(inputStream.readAllBytes(), Charset.defaultCharset());
    Assertions.assertThat(response).isNotNull();
}

Just like the above test, this will execute the same flow.

5. Conclusion

In this article, we learned about mTLS by setting up a certificate authority and generating certificates for both the server and clients.

We then configured an Nginx server to use mTLS for secure communication. On the client side, we loaded the certificates in a Java application by creating a KeyManagerFactory, TrustManager, and initialising an SSLContext.

Finally, we tested SSLConext and executed mTLS calls with Java clients such as HttpClient and HttpURLConnection.