Configuration: TLS¶

This page is the reference for TLS configuration: the profiles file, every setting that uses a profile, and worked examples for the common deployments. All settings default to off, so a deployment that sets none of them runs without TLS. Start with the examples at the end if you want a working result first, and return here for the detail.

Audience: Operator, Architect.

TLS profiles¶

A profile is defined in profiles.json, a JSON array in /app/config/deployment-config/resources/tls/ (see Deployment: TLS). Each entry is one profile, and listeners and connections refer to it by Name.

A profile that accepts connections needs key material. A profile used only to connect needs key material only when the listener it connects to requires a client certificate.

Example: PEM files and a keystore¶

[
  {
    "Name": "public",
    "Certificate": "/app/config/deployment-config/resources/tls/public/tls.crt",
    "PrivateKey": "/app/config/deployment-config/resources/tls/public/tls.key",
    "TrustStore": "/app/config/deployment-config/resources/tls/ca.crt",
    "ClientAuth": "off"
  },
  {
    "Name": "internal",
    "KeyStore": "/app/config/deployment-config/resources/tls/internal.p12",
    "KeyStorePasswordFile": "/app/config/deployment-config/resources/tls/internal.p12.password",
    "TrustStore": "/app/config/deployment-config/resources/tls/ca.crt",
    "ClientAuth": "required"
  }
]

The public profile uses PEM files and asks for no client certificate: suited to applications and browsers. The internal profile uses a PKCS12 keystore with its password in a file and requires client certificates: suited to node-to-node traffic.

A PKCS#1 private key (BEGIN RSA PRIVATE KEY) converts to PKCS#8 with openssl pkcs8 -topk8 -nocrypt -in old.key -out tls.key. Protect a PEM key with file permissions or a Secret; to use a password-protected key, put it in a PKCS12 keystore instead.

Settings¶

Settings go in the component's file under deployment-config/settings/, using the component name as a prefix (see Configuration: Basics). The tables show the setting as it is written inside a component; the full property name is <component>.<setting>.

Values¶

A TLS mode setting takes <mode>[:<profile>]:

An outbound connection takes off or required:<profile>.

Client-facing listeners¶

Components: com.metafluent.blueprint.rtc.refresh.server.tcpip, ...rtc.session.server.tcpip, ...rtc.sql.server.tcpip, ...rtc.pubsub.server.tcpip and ...rtc.push.server.tcpip, plus com.metafluent.blueprint.rtc.entitlements.login.server for the login server.

Example - plaintext on the private network and TLS on the client network, for a TCP listener; wss only for browsers:

com.metafluent.blueprint.rtc.refresh.server.tcpip.tcpipServer.tls=off
com.metafluent.blueprint.rtc.refresh.server.tcpip.tcpipServer.tlsNetworks=client=required:public
com.metafluent.blueprint.rtc.refresh.server.tcpip.webSocketServer.tls=required:public

A network named in tlsNetworks must be one the listener binds; a misspelt name stops the node at start and says so.

API gateway and SSO¶

restServer.tls, restServer.machineTls and internalHttp.tls are all required:<profile> or all off. A node whose three settings disagree stops at start and names the settings. Their profiles may differ.

com.metafluent.blueprint.core.utilities.restServer.tls=required:public
com.metafluent.blueprint.core.utilities.restServer.machineTls=required:internal
com.metafluent.blueprint.network.registry.internalHttp.tls=required:internal

Internal connections¶

The tlsProfileRegistry settings can also be set from the environment: METAFLUENT_TLS_PROFILES_DESCRIPTOR, METAFLUENT_TLS_RELOAD_INTERVAL_SECONDS and METAFLUENT_INTERNAL_HTTP_TLS.

Example - reload every 5 minutes, and keep the profiles file in a custom location:

com.metafluent.blueprint.network.registry.tlsProfileRegistry.descriptorPath=/etc/metafluent/tls/profiles.json
com.metafluent.blueprint.network.registry.tlsProfileRegistry.reloadIntervalSeconds=300

Worked examples¶

wss for browser clients¶

Browsers connect with secure WebSockets to a server's WebSocket listener. This example serves the refresh server's browser listener over TLS, with a public certificate, and leaves its TCP listener as it is.

profiles.json:

[
  {
    "Name": "public",
    "Certificate": "/app/config/deployment-config/resources/tls/tls.crt",
    "PrivateKey": "/app/config/deployment-config/resources/tls/tls.key",
    "ClientAuth": "off"
  }
]

Setting:

com.metafluent.blueprint.rtc.refresh.server.tcpip.webSocketServer.tls=required:public

The certificate names the host the browser connects to, and a certificate from a public CA is trusted by the browser as it stands. Browsers connect to wss://host:port; see Developing with TLS. To keep serving existing ws:// pages during a migration, use offered:public instead; one port then serves ws:// and wss://.

An all-TLS deployment¶

Every connection uses TLS: client APIs, browsers, the mesh, internal reads and the gateway. Two profiles do the work. public presents the certificate to applications and browsers and asks for no client certificate. internal is used between nodes and requires client certificates. Both certificates are issued by the one CA in ca.crt, which every node trusts.

profiles.json:

[
  {
    "Name": "public",
    "Certificate": "/app/config/deployment-config/resources/tls/public/tls.crt",
    "PrivateKey": "/app/config/deployment-config/resources/tls/public/tls.key",
    "TrustStore": "/app/config/deployment-config/resources/tls/ca.crt",
    "ClientAuth": "off"
  },
  {
    "Name": "internal",
    "Certificate": "/app/config/deployment-config/resources/tls/internal/tls.crt",
    "PrivateKey": "/app/config/deployment-config/resources/tls/internal/tls.key",
    "TrustStore": "/app/config/deployment-config/resources/tls/ca.crt",
    "ClientAuth": "required"
  }
]

Settings, for the client-facing servers (repeat for each server you run; the WebSocket line applies to refresh, session, SQL and pub-sub):

com.metafluent.blueprint.rtc.session.server.tcpip.tcpipServer.tls=required:public
com.metafluent.blueprint.rtc.session.server.tcpip.webSocketServer.tls=required:public

Settings, for the fabric mesh:

com.metafluent.blueprint.datafabric.tcpipServer.tls=required:internal
com.metafluent.blueprint.datafabric.server.outboundTls=required:internal
com.metafluent.blueprint.datafabric.server.tlsPeerName=fabric.internal

Settings, for internal reads and sessions between nodes:

com.metafluent.blueprint.rtc.content.common.childResultReaderFactory.tls=required:internal
com.metafluent.blueprint.rtc.query.proxy.authnz.entitlementsContextConnection.tls=required:internal
com.metafluent.blueprint.rtc.content.adapter.mfpubsub.pubsubContent.tls=required:internal

Settings, for the gateway and SSO (all three gateway settings agree):

com.metafluent.blueprint.core.utilities.restServer.tls=required:public
com.metafluent.blueprint.core.utilities.restServer.machineTls=required:internal
com.metafluent.blueprint.network.registry.internalHttp.tls=required:internal
com.metafluent.blueprint.security.rest.sso.sso.tls=required:public

Certificate names: each listener's certificate names the host its clients use; the internal certificate carries fabric.internal for the mesh. The public certificate on the people door must be one the nodes trust, which the shared CA in ca.crt provides, because every node also calls that door.

Mutual TLS for internal connections¶

Keep the client-facing side as it is, and have the nodes authenticate each other with certificates. A listener on the private network requires a client certificate, and the nodes that connect to it present theirs.

Profile internal has "ClientAuth": "required" (as above). Settings, on a server whose private network is named private:

# the private network requires TLS with client certificates; other networks are unchanged
com.metafluent.blueprint.rtc.refresh.server.tcpip.tcpipServer.tlsNetworks=private=required:internal

# nodes reading from that listener use the same profile: trust to verify it, certificate to present
com.metafluent.blueprint.rtc.content.common.childResultReaderFactory.tls=required:internal

A connecting node verifies the listener against the profile's TrustStore and presents the profile's certificate when the listener asks for one. The same pattern covers the mesh: tcpipServer.tls, server.outboundTls and server.tlsPeerName on the data fabric with required:internal.

Start-up messages¶

A node reads and checks every profile and TLS setting when it starts. If something is off, it stops with a message that says what to fix. The common ones:

Where to go next¶

• Deployment: TLS - mounting the files, renewing certificates and migrating from plaintext.
• Architecture: TLS - the modes, mutual TLS and how clients find TLS endpoints.
• Developing with TLS - the client-side settings for JMS, JDBC and browsers.
• Configuration: Reference - the annotated properties for every setting.
• Configuration: Advanced - how a final value is assembled.