This recipe explains how to utilize SSL/TLS Client Authentication in Repose.

SSL/TLS provides an encrypted link between the client and the server, and is the standard for sending private data over the internet. You may want to enable SSL/TLS Client Authentication if part of your infrastructure is in a different datacenter to ensure only cross service traffic can reach your service.

Background

SSL/TLS Client Authentication is being used more and more for communications between different enclaves. This addition to the server based SSL/TLS handshake involves the Client presenting credentials to the Server in the same manner as the Server does to the Client. If the credentials presented by the Client are not trusted, then the Server will sever the connection just as the Client would have if the situation was reversed. Since a Client initiates contact with the Server, the Server’s credentials are simply to validate it is who the Client was trying to contact. This is accomplished through Certificate Authorities (CA) and the Trust Hierarchies built into the Public Key Infrastructure (PKI). Even though you can optionally add a particular Server’s credentials directly into a Client so that it will implicitly trust a particular Server essentially bypassing the distributed trust mechanism in favor of a more direct one, this is the only way to build a relationship for a Client to a Server.

Generate and Install the Certificate

In the following steps, the client will refer to the entity sending the request, and the server will refer to the entity receiving the request. If you are setting up client authentication for requests inbound to Repose, then the entity sending the request is the client and Repose is the server. If you are setting up client authentication for requests outbound from Repose to the origin service, then Repose is the client and the origin service is the server.

Generate the client key and certificate

Using the JDK provided keytool generate the certificate that the client will use.

$ keytool -genkeypair -keystore client.jks -storepass password -keypass password -alias client -keyalg RSA -keysize 2048 -validity 36500 -sigalg SHA256withRSA

Export the client certificate

Again, using the keytool export the certificate.

$ keytool -exportcert -keystore client.jks -storepass password -keypass password -alias client -file client.cer

Import the client certificate into the server keystore

Using the keytool import client certificate into the server keystore.

$ keytool -importcert -keystore server.jks -storepass password -keypass password -alias client -file client.cer

Client to Repose Authentication

With your certificates in the right spot it’s time to turn authentication on for Valve. This is achieved with a simple tweak to the container.cfg.xml.

Partial container.cfg.xml
<deployment-config>
    ...
    <ssl-configuration>
        <keystore-filename>server.jks</keystore-filename> (1)
        <keystore-password>password</keystore-password> (2)
        <key-password>password</key-password> (3)
    </ssl-configuration>
</deployment-config>
1 The path and filename of the server keystore that you imported the certificate into above. This path is based off of the Repose configuration directory, but absolute pathing is supported.
2 The password for the keystore that you imported the certificate into.
3 The password you used for the key/certificate itself when importing it into the keystore.
If you are using the WAR deployment and not Valve, you will have to consult the documentation for your container to determine how to turn on client authentication.

Repose to Origin Service

To turn on authenticated communication to your origin service, you’ll need to tweak the default pool in your HTTP Connection Pool service config. There is nothing stopping you from similarly tweaking any of your other pools if you have a need to use client authentication in other outbound communication.

Partial http-connection-pool.cfg.xml
<pool id="default"
      default="true"
      ...
      keystore-filename="client.jks" (1)
      keystore-password="password" (2)
      key-password="password"/> (3)
1 The path and filename of the client keystore that you created above. This path is based off of the Repose configuration directory, but absolute pathing is supported.
2 The password for the keystore that you created.
3 The password for the key/certificate you created.

Further Information

  • If one side of the communication is not JVM based you may need your certificate in a different format.

    • The keytool page may offer some assistance, as well as going into depth on the many options available for the commands used above.

    • The Jetty documentation offers some assistance in using OpenSSL when alternative formats are needed as well.

  • For more information on what options are available when setting up Valve look here.

  • For more information about the http client connection pool look here.