Network security | Documentation

Secure clients

Diffusion™ Cloud clients can connect to your solution using Transport Layer Security (TLS) or Secure Sockets Layer (SSL) .

Note: The secure connection can terminate at your load balancer or at your Diffusion Cloud server. Terminating at the load balancer can reduce the CPU load on your Diffusion Cloud servers; the supported protocols will depend on your load balancer.

If you are terminating the secure connection at the server, the available TLS/SSL protocols depend on the implementations provided by the Java installation you are using to run the Diffusion Cloud server. For a given connection, the client and server will negotiate the protocol and cipher suite to use.

Java distributions track security vulnerabilities and enable protocols and cipher suites accordingly. For example, SSL protocols have known vulnerabilities and are typically disabled.

Use the interfaces provided by your Java installation to override the defaults, and enable or disable particular protocols or cipher suites for the server or the Java client. For the Oracle JDK, see the Oracle JDK cryptographic configuration documentation.

The diffusion.tls.protocols and https.cipherSuites system properties used to configure secure connections in previous Diffusion versions are now ignored.

Diffusion has been tested with a range of protocols, including TLSv1.3. For TLSv1.3 support, we recommend running the server using a Java 11 OpenJDK-based distribution. Azul Zing can be used if TLSv1.3 support is required for Java 8 clients.

See System requirements for the Diffusion Cloud server for more information about supported Java distributions.

Session tokens

Diffusion clients use session tokens to authenticate when reconnecting to their existing session. To protect the credentials supplied in the original connection request and the returned session token, ensure that the client uses a secure transport to communicate with Diffusion Cloud . For example, WSS.

Session tokens are generated by using java.security.SecureRandom with the default algorithm supplied by the Java™ environment used to run Diffusion Cloud . Each token is a 24-character string encoded in base-64, representing 18 bytes (144 bits) of random data.

A new session token is generated when a client connects to Diffusion Cloud , is authenticated, and creates a session. The server returns the session token to the client in the connection response. The client library keeps the session token in memory. If the client connection is lost, the client attempts to reconnect and supplies the session token. The server is configured with a reconnection timeout. If Diffusion Cloud detects the loss of the client connection and the client fails to reconnect to Diffusion Cloud before the reconnection timeout has elapsed, Diffusion Cloud closes the session and the session token is no longer valid. If the client reconnects before the reconnection timeout has elapsed, Diffusion Cloud accepts the new connection using the session token is used as proof of authentication.

Keystores

The default Diffusion Cloud installation includes a sample keystore containing a self-signed certificate. This is suitable for development. The certificate will not be trusted by browsers and other clients without additional configuration. If you use TLS in production, you must create a new keystore, using a certificate obtained from a certificate authority.

The following steps use the Java Keytool to create a keystore. The steps can vary depending on your certificate authority. For more information, refer to your certificate authority's documentation.

Generate a key and place it in your keystore.

keytool -genkeypair -alias my_alias -keyalg RSA -keystore keystore_name -keysize

Generate a certificate signing request (CSR) file.

keytool -certreq -keyalg RSA -alias my_alias -file certreq.csr -keystore keystore_name

Send the CSR file to your certificate authority.
Receive the signed certificate from your certificate authority.

Install any intermediate certificates that you require.

keytool -import -trustcacerts -alias intermediate_alias -keystore keystore_name -file intermediate_certificate_file.crt

Install your own certificate. Use the same alias as when you generated the key and the signing request.
```
keytool -import -trustcacerts -alias my_alias -keystore keystore_name -file certificate_file.crt
```

Provided keystores

The etc directory of the Diffusion Cloud directory contains the following keystores:

sample.keystore: This keystore is an example keystore that contains a self-signed certificate. In production, we recommend you create your own keystore that contains a certificate signed by a certificate authority.
licence.keystore: This keystore contains the public key used for the Diffusion Cloud license file. Do not edit or delete this keystore. Diffusion Cloud requires this keystore to verify your Diffusion Cloud license.