Skip to content

Configuring TLS/SSL

In this article we discuss how to activate TLS encryption for all traffic in SmartFoxServer, how to create an X.509 certificate that will be deployed on your server and how to test that everything works as expected.

1. SSL or TLS?

SSL and TLS are used interchangeably in this page. They both refer to a secure layer of communication.

2. For live servers only

What we discuss here applies to production or staging servers. Setting up an SSL certificate for a local network is overkill and we do not recommended it.

What's needed

To get started you will need:

  • a live staging/production server where SmartFoxServer 3 is already installed
  • an internet domain that resolves to the live server
  • a valid TLS certificate for said domain, provided by a CA or Certificate Authority, or one of the many resellers
  • the openssl command line utility. You can check if it's already present in your system by running this command: openssl version. If not check the How to get openssl section
  • a JDK 21 or higher installed on your local machine

Server Setup

1. Double check HTTPS is active

By default SmartFoxServer 3 is already configured with HTTPS and WSS activated. You can double check via the AdminTool > Server Settings > Web Server

web server config

2. Activate the Encryption in your Zone

Via the AdminTool > Zone Configurator, select your Zone and activate the Use encryption option.

3. Prepare the TLS certificate

As required in the beginning of this tutorial you should already have acquired the SSL/TLS certificate.

Certificates comes in several different file formats. Typically you will get two or three files:

  • Certificate (.pem / .cer / .crt)
  • Private key (.pem / .key)
  • (optional) Intermediary certificate (.pem / .cer / .crt)

While the file extensions can vary, most of these files are in plain text and contain binary data encoded in Base64.

a) Create a bundle of the main and intermediate certificates

This step can be skipped if you don't have an intermediate certificate. If you do, all you need is to create a new text file with the same extension of your certificates (e.g. bundle.pem) and copy/paste both the primary and intermediate ones into the same file, one after the other.

b) Create a binary file containing all the components of the certificate

Next you'll create a .pfx file containing all the elements of the certificate by using the openssl utility. Open a terminal window and run the following:

openssl pkcs12 -export -out my-cert.pfx \
 -inkey www.mydomain.com.key \
 -in www.mydomain.com.crt \
 -certfile bundle.crt

where:

  • my-cert.pfx is the final output file
  • www.mydomain.com.key is the key file
  • www.mydomain.com.crt is the main certificate file
  • bundle.crt is the bundle file created in step #1

c) Import the .pfx file into a Java keystore file

Next we proceed by creating the .jks keystore file. This is a specific Java file format that stores the certificate in a secure way.

From command line run this:

keytool -importkeystore -srckeystore my-cert.pfx -srcstoretype pkcs12 \
  -destkeystore key-store-name.jks -deststoretype JKS

where:

  • my-cert.pxf is the file we created at step #2
  • key-store-name.jks is our output file

d) Deploy to SmartFoxServer

Finally, last step, we can deploy the generated .jks file to SmartFoxServer 3. From the AdminTool > ServerConfigurator > Web Server scroll down to SSL Certificate and hit the Manage button:

certificate upload dialogue

From there you can select your keystore file, specify the keystore password and upload the certificate.

Last step: restart SmartFoxServer.

4. Verify if the certificate is deployed correctly

To verify that the SSL certificate is working correctly you can point your browser to https//:server-host:8843 and make sure that the lock appears near the domain name. You can additionally click on the lock icon and verify the details of the certificate.

browser test

You can also test the integrity of your certificate using an online SSL diagnostic tool, such as the one provided by Digicert. This is particularly useful to find issues with the SSL certificate chain that may not appear in the browser.

Client API examples

Using encryption on the client side is very simple: regardless of the platform you're using all you need is to set the ConfigData.useSSL flag to true, before starting the connection:

var sfs = new SmartFox();
sfs.AddEventListener(SFSEvent.CONNECTION, OnConnection);

var cfgData = new ConfigData();
cfgData.Host = "myserver.com"
cfgData.UseSSL = true;
sfs.Connect(cfgData);

private void OnConnection(ApiEvent evt)
{
    bool success = (bool) evt.GetParam(EventParam.Success)!;

    if (success)
        Log("Connection successful -- Mode is " + sfs.ConnectionMode);

    else
        Log("Connection failed: " + evt.GetParam(EventParam.ErrorMessage));        
}

How to test locally with SSL

SmartFoxServer 3 comes with a pre-installed self-signed certificate that can be used for this purpose, with one limitation: clients will likely refuse to accept the certificate as it's not signed by a CA (Certificate Authority).

This limitation can be locally overcome on platforms such as .Net/Unity/Godot, Java, and Swift by using the use ConfigData.AllowUnsafeSSL flag.

For example:

var cfgData = new ConfigData();
cfgData.Host = "localhost"
cfgData.UseSSL = true;
cfgData.AllowUnsafeSSL = true;
// etc...

sfs.Connect(cfgData);

This allows the client to connect to the localhost using SSL without incurring a security Exception.

What about HTML/JS?

This is a bit more complex since the JS runtime is the browser and there are many of them. Generally speaking browsers will not accept a self-signed certificate and even if you force them to accept it, the WebSocket connection will likely fail.

One possible solution is to use an open source tool such as mkcert to create a local CA in your system, then generate a new certificate to be used with SmartFoxServer for local tests.

The procedure is as follows:

  • install mkcert
  • use the command mkcert -install to add the CA to your system
  • use the command mkcert localhost 127.0.0.1 ::1 to generate a new certificate
  • take the resulting .pem files (certificate and private key) and build the keystore as explained in this article
  • deploy the new keystore
  • restart SmartFoxServer

Now you should be able to connect to your localhost using HTTPS and WSS.

How to get openssl

If your system does not come with the openssl command line utility pre-installed you can install it manually:

  • if you are on Linux or macOS it's probably already installed in your system. To double check run the openssl version command. In case you don't have it you should search and install it via your OS package manager.

  • if you are on Windows we recommend these two options: