TLS Configuration

Mixed TLS and outgoing HTTPS Connections

In case of clients connecting to SwiftMQ by using our self-signed or another trusted certificate and SwiftMQ Streams performing outgoing HTTPS requests (e.g. REST), the trusted CA certs from the JRE need to be imported in SwiftMQ's client.truststore with the following command:

CODE

keytool -importkeystore -srckeystore $JAVA_HOME/lib/security/cacerts -srcstorepass changeit \
        -destkeystore certs/client.truststore -deststorepass secret

SwiftMQ running on Docker does this automatically during startup.

AMQP

The AMQP Swiftlet uses a connection template that can be associated with an AMQP listener. There is one connection template called ssl that has the JSSE socket factory predefined:

XML

  <connection-templates>
    <connection-template name="ssl" socketfactory-class="com.swiftmq.net.JSSESocketFactory"/>
  </connection-templates>

This is used to create an AMQPS (secure) listener on standard port 5671:

XML

  <listener name="amqps" connection-template="ssl" port="5671">
    <host-access-list/>
  </listener>

JMS

The JMS Swiftlet defines the secure socket factory directly at the listener element. This creates a secure JMS listener on port 4004 and automatically creates a connection factory ssl@router and registers it in JNDI:

XML

  <listener name="ssl" port="4004" socketfactory-class="com.swiftmq.net.JSSESocketFactory">
    <connection-factories>
      <connection-factory name="ssl@router"/>
    </connection-factories>
    <host-access-list/>
  </listener>

MQTT

The MQTT Swiftlet uses a connection template that can be associated with an MQTT listener. There is one connection template called tls that has the JSSE socket factory predefined:

XML

  <connection-templates>
    <connection-template name="default"/>
    <connection-template name="tls" socketfactory-class="com.swiftmq.net.JSSESocketFactory"/>
  </connection-templates>

This is used to create an MQTTS (secure) listener on port 2883:

XML

  <listener name="tls" connection-template="tls" port="2883">
    <host-access-list/>
  </listener>

Routing

Listener

From a TLS standpoint, the router with the listener is the server. The listener element defines the secure socket factory directly at the listener element. This creates a TLS routing listener on port 4104:

XML

  <listener name="tls" port="4104" socketfactory-class="com.swiftmq.net.JSSESocketFactory">
    <host-access-list/>
  </listener>

Connector

From a TLS standpoint, the router with the connector is the client. The connector element defines the secure socket factory directly at the connector element. This creates a TLS connector to connect to a routing listener on port 5104:

XML

<connectors>
  <connector name="tls" hostname="localhost" port="5104" socketfactory-class="com.swiftmq.net.JSSESocketFactory"/>
</connectors>

X.509 Certificates

SwiftMQ self-signed Certificate

The SwiftMQ distribution (router and client) already contains a self-signed certificate under the cert/directory that works out of the box. This certificate is intended for testing only. For production use please generate your own self-signed certificate or purchase one from a trusted CA.

Create your own self-signed Certificate or use a certificate from a trusted Certificate Authority (CA)

Please consult the official documentation on how to create your own self-signed certificates or import CA certificates with keytool. Note that the key length must be 2048 or more if you generate your own certificate!

Key Store

The key store is located under the cert/ directory. The filename is server.keystore. The default password is secret. The key store includes SwiftMQ's self-signed certificate.

Trust Store

The trust store is located under the cert/ directory. The filename is client.truststore. The default password is secret. The trust store includes SwiftMQ's self-signed certificate.

PEM Files

There are also 2 PEM files that can be used at the router as an alternative to using the key/trust stores. They contain SwiftMQ's self-signed certificate and private key.

Authentication Modes

One Way

With one-way authentication, the TLS server (the router or, with routing connections, the router with the routing listener) uses the certificate from the key store and presents it to the client. The client checks its trust store and if it finds the certificate, a secure connection can be established. So with one-way authentication, the server authenticates the client.

Two Way

With two-way authentication, the TLS server authenticates at the clients, and thereafter the client authenticates at the server. So both sides must trust each other in order to establish a secure connection. This means both sides need access to the key and trust store.

SwiftMQ Client

Up to Release 11.2.0

Set the following system property:

CODE

-Dswiftmq.jsse.anoncipher.enabled=false

If you use one-way authentication, you only need the trust store referenced:

CODE

-Djavax.net.ssl.trustStore=../certs/client.truststore -Djavax.net.ssl.trustStorePassword=secret

If you use two-way authentication, you need both key and trust store referenced:

CODE

-Djavax.net.ssl.keyStore=../certs/server.keystore -Djavax.net.ssl.keyStorePassword=secret

Release 12.0.0+

If you use one-way authentication, you only need the trust store referenced:

CODE

-Djavax.net.ssl.trustStore=../certs/client.truststore -Djavax.net.ssl.trustStorePassword=secret

If you use two-way authentication, you need both key and trust store referenced:

CODE

-Djavax.net.ssl.keyStore=../certs/server.keystore -Djavax.net.ssl.keyStorePassword=secret

SwiftMQ Router

Up to Release 11.2.0

Set the following system property:

CODE

-Dswiftmq.jsse.anoncipher.enabled=false

If you use one-way authentication, you only need the key store referenced:

CODE

-Djavax.net.ssl.keyStore=../certs/server.keystore -Djavax.net.ssl.keyStorePassword=secret

If you use two-way authentication, you need both key and trust store referenced:

CODE

-Djavax.net.ssl.trustStore=../certs/client.truststore -Djavax.net.ssl.trustStorePassword=secret

You also need to set this system property to enable client authentication (two-way):

CODE

-Dswiftmq.jsse.clientauth.enabled=true

Release 12.0.0+

If you use one-way authentication, you only need the key store referenced:

CODE

-Djavax.net.ssl.keyStore=../certs/server.keystore -Djavax.net.ssl.keyStorePassword=secret

If you use two-way authentication, you need both key and trust store referenced:

CODE

-Djavax.net.ssl.trustStore=../certs/client.truststore -Djavax.net.ssl.trustStorePassword=secret

You also need to set this system property to enable client authentication (two-way):

CODE

-Dswiftmq.tls.clientauth.enabled=true

If you want to use PEM files instead of key/trust store, reference it with:

CODE

-Dswiftmq.tls.cert.file=<filename> -Dswiftmq.tls.privatekey.file=<filename>