Network security | Documentation

Secure clients

Diffusion™ 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 server. Terminating at the load balancer can reduce the CPU load on your Diffusion 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 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 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 the Diffusion server . For example, WSS.

Session tokens are generated by using java.security.SecureRandom with the default algorithm supplied by the Java™ environment used to run the Diffusion server . 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 the Diffusion server , 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 the Diffusion server detects the loss of the client connection and the client fails to reconnect to the Diffusion server before the reconnection timeout has elapsed, the Diffusion server closes the session and the session token is no longer valid. If the client reconnects before the reconnection timeout has elapsed, the Diffusion server accepts the new connection using the session token is used as proof of authentication.

Web server configuration

The web server can be configured in your test environment to allow you to deploy and undeploy DAR files by using a web service. By default this capability is not enabled.

For security, if you choose to enable this web service in your production environment, you must restrict access to the diffusion-url/deploy URL by other means. For example, by setting up restrictions in your firewall.

To configure the web server, use the WebServer.xml file. For more information, see WebServer.xml. An example of this file is provided in the /etc directory of the Diffusion installation. The XSD is provided in the /xsd directory of the Diffusion installation.

Connector configuration

If secure connections are required, Diffusion connectors must be configured to support HTTPS, WSS, or a combination of these transports. Any connector can accept secure connections. A connector does not have to be dedicated to only secure connections. To enable secure connections a keystore entry is required in the connector configuration. This informs the connector that it is enabled for secure connections. If HTTPS is required, a keystore section and a web-server entry are also required, even for secure Diffusion clients.

To configure the connectors, use the Connectors.xml file. For more information, see Connectors.xml . An example of this file is provided in the /etc directory of the Diffusion installation. The XSD is provided in the /xsd directory of the Diffusion installation.

Keystores

The default Diffusion 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 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 license file. Do not edit or delete this keystore. Diffusion requires this keystore to verify your Diffusion license.