Developing with TLS¶

When an Elastic MDS deployment serves TLS, your application connects to it the same way as before, with one setting that says "use TLS". This page covers that setting for JMS, JDBC and browser clients, how trust and client certificates are configured, and what to do about the errors you may meet. The deployment side is in Deployment: TLS.

Audience: Java developers, and browser-application developers. No prior TLS configuration knowledge assumed.

The short version¶

• Set TLS to required in your client. Everything else follows: the handshake, certificate and host-name checks, and TLS on every connection the session makes, including the push, refresh and pub-sub connections it is redirected to.
• If the server's certificate comes from a public certificate authority, or from an authority your JVM already trusts, that is all you need.
• If the server's certificate comes from your own authority, tell the client which certificates to trust with a trust store.
• If the server asks for a client certificate (mutual TLS), give the client a key store.

TLS from JMS¶

JMS reads its TLS settings from system properties:

Pass them on the command line:

java -Dcom.metafluent.jms.client.Properties.Tls=required \
     -cp "bin/SimpleSubscriberApplication.jar:lib/*" \
     com.metafluent.examples.simplesub.SimpleSubscriber \
     -connect mf-session:8900 -context com.metafluent.jms_context.mds RDF.VOD.L

or set them in code before you create the connection. A factory's own property overrides replace the system properties, which suits an application that holds several factories with different settings:

import java.util.Properties;
import com.metafluent.jms.client.JavaxTopicConnectionFactory;

// Application-wide, as system properties
System.setProperty("com.metafluent.jms.client.Properties.Tls", "required");
System.setProperty("com.metafluent.jms.client.Properties.TrustStore", "/etc/myapp/ca.pem");

JavaxTopicConnectionFactory factory = new JavaxTopicConnectionFactory("mf-session:8900");

// Or per factory: these replace the system properties for this factory
Properties overrides = new Properties();
overrides.setProperty("com.metafluent.jms.client.Properties.Tls", "required");
overrides.setProperty("com.metafluent.jms.client.Properties.TrustStore", "/etc/myapp/ca.pem");
factory.setPropertyOverrides(overrides);

Trust and key store settings go together with Tls=required; giving them without it is reported as an error, so a mistyped mode never leaves TLS switched off unnoticed.

TLS from JDBC¶

The JDBC driver takes the same settings as connection properties, with the prefix com.metafluent.jdbc., or as URL parameters without the prefix:

The shortest form is a URL parameter:

jdbc:metafluent://mf-session:8900?tls=required

Or in code, with a trust store for your own authority and a client certificate:

Properties props = new Properties();
props.setProperty("com.metafluent.jdbc.user", "guest");
props.setProperty("com.metafluent.jdbc.tls", "required");
props.setProperty("com.metafluent.jdbc.trust-store", "/etc/myapp/ca.pem");
props.setProperty("com.metafluent.jdbc.key-store", "/etc/myapp/client.p12");
props.setProperty("com.metafluent.jdbc.key-store-password", System.getenv("CLIENT_P12_PASSWORD"));

try (Connection conn = DriverManager.getConnection("jdbc:metafluent://mf-session:8900", props)) {
    // query as usual
}

When a setting appears both as a URL parameter and as a connection property, the URL parameter wins.

The browser JavaScript client over wss://¶

A browser client connects to a server's WebSocket listener with a wss:// address in place of ws://:

wss://mds.example.com:8750

The browser checks the server's certificate against its own trust store, so a certificate from a public CA works as it stands. For an internal authority, install that authority's certificate in the browser or the operating system's trust store, as for any other internal HTTPS site. The certificate must name the host in the address, and a page served over HTTPS connects to wss:// addresses.

Trust and client-certificate setup¶

Trust. The client verifies the server's certificate chain and its host name on every TLS connection.

• With no trust settings, the JVM's default trust applies: its list of public certificate authorities, or whatever javax.net.ssl.trustStore names. A server certificate from a public CA needs no client configuration.
• With a trust store setting, the certificates in that file are the ones trusted. Give your own authority's certificate (a PEM bundle is the simplest form).

Client certificate. When the deployment runs mutual TLS, the server asks the client to prove its identity. Give the client a key store holding its certificate and private key (PKCS12 or JKS) with the KeyStore and KeyStorePassword settings above. The client presents it when the server asks, and your operator issues it from the authority the server trusts.

Errors and what to do¶

TLS failures are reported with the host and port, in the form TLS handshake with <host:port> failed: <reason>.

Where to go next¶

• Architecture: TLS - the listener modes and how clients are directed to TLS endpoints.
• Deployment: TLS - how your operator turns TLS on, and migrates clients with offered mode.
• JMS Application Development - the JMS guide.
• JDBC Application Development - the JDBC guide.
• Configuration: TLS - the server-side settings.