Skip to content

Enabling encryption and authentication via TLS

Requires CLAID v0.6.3 or later

TLS encryption is available from CLAID v0.6.3 onwards.

CLAID features encryption and authentication via TLS for all network communication. Encryption means that all data sent between two CLAID instances is encrypted via TLS. This means that if you use the DataSyncModule, for example, all data will be transferred fully encrypted. Authentication means that only CLAID instances with a valid certificate (known to the "server instance") are allowed to connect. There are two options for using TLS with CLAID:

  1. TLS with Server-based authentication (most common): In this mode, each CLAID instance that wants to connect as client to another CLAID instance configured as server requires the server's certificate. The clients authenticate the server, meaning they can only connect to known-good servers.

    • Advantage: Secure and easy to set up. Only requires to give each client the server's certificate.
    • Disadvantage: If an attacker steals the server's certificate, e.g., by decompiling a CLAID application, the attacker can connect to the server.

  2. Mutual TLS (mTLS): In this mode, a CLAID instance that wants to connect to another CLAID instance requires the server's certificate, while the server needs the client's certificate. Both client and server authenticate each other. This means that the server only accepts connections from known-good clients and the client only connects to known-good servers.

    • Advantage: More secure, as the server can authenticate the client and vice versa. Should a client be compromised, we can revoke the client's certificate without changing the server's certificate and without affecting other clients. We simply prevent the attacker from connecting to the server.
    • Disadvantage: Requires more work to set up, as each client needs to have the server's certificate and the server needs to have the client's certificate.

Option 1: TLS with Server-based authentication (most common)

Server-based authentication is the default TLS mode, and should be sufficient for most use cases and studies. It requires you to generate a server certificate and private key. The server certificate needs to be transferred to each client. The server requires both the private key and the certificate. The private key needs to be stored securely, as it is used to decrypt data sent from the clients. You can generate the key and certificate via OpenSSL:

Generating a self-signed certificate via OpenSSL

You can generate a self-signed certificate via OpenSSL using the command below.

Please note: You need to specify the IP or fully qualified domain name of the server when generating the key! Adapt the 2 placeholders "YOUR_IP" in the command below: 

openssl req -x509 -nodes -newkey rsa:2048 -keyout server.key -out server.crt -days 365 \
    -subj "/CN=YOUR_IP" -addext "subjectAltName = IP:YOUR_IP"
If you provide a wrong IP or domain name, you will get an error saying "No match found for name ..."

The command above will generate a self-signed certificate server.crt and a private key server.key with rsa 2048 bit encryption, which is valid for 365 days. You can also use a higher bit encryption and make the certificate valid for longer or shorter time.

Important: You need to keep the private key server.key in a secure location. If an attacker gains access to the private key, they can impersonate the server and decrypt all data sent to the server.

Next, you will need to activate TLS encryption in the CLAID configuration file.

CLAID configuration file with TLS encryption

Use the following configuration file to set up two hosts, one acting as server and one as client. The client will connect to the server via TLS using server-based authentication. That is, the client only needs to know the server's public certificate, while the server accepts each client that knows the server's public certificate. 

{
    "hosts": [
        {
            "hostname": "Server",
            "server_config": {
                "host_server_address": "your_ip:1337",
                "tls": {
                    "server_public_certificate": "path/to/server.crt",
                    "server_private_key": "path/to/server.key"
                }
            }  
        },
        {
            "hostname": "Smartphone",
            "connect_to": {
                "host": "Server",
                "tls": {
                    "server_public_certificate": "path/to/server.crt"
                }
            },
        }
    ]
}

Update the configuration files on both the Smartphone and your PC/Server. After you have set it up and copied the required certificate/key files, each connection will be encrypted and authenticated. In case of misconfiguration or invalid key files, the CLAID application will exit.

Option 2: Mutual TLS (mTLS) (more secure against malicious intent)

Mutual TLS (mTLS) is more secure against malicious intent, as both client and server authenticate each other. If a client get's compromised, we can revoke the client's certificate from the server, so that it cannot connect to the server anymore.

mTLS requires you to generate a server certificate and private key, as well as a client certificate and private key. The server certificate needs to be transferred to each client, while the client certificate needs to be transferred to the server. The private keys need to be stored securely, as they are used to decrypt data sent from the client/server.

You need too generate two pairs of keys and certificates, one for the server and one for the client. You can use OpenSSL:

Generating a self-signed certificate via OpenSSL

You can generate a self-signed certificate via OpenSSL using the command below.

Please note: You need to specify the IP or fully qualified domain name of the server when generating the key! Adapt the 2 placeholders "YOUR_IP" in the command below: 

openssl req -x509 -nodes -newkey rsa:2048 -keyout server.key -out server.crt -days 365 \
    -subj "/CN=YOUR_IP" -addext "subjectAltName = IP:YOUR_IP"
If you provide a wrong IP or domain name, you will get an error saying "No match found for name ..."

The command above generates a self-signed certificate server.crt and a private key server.key with rsa 2048 bit encryption, which is valid for 365 days. You can also use a higher bit encryption and make the certificate valid for longer or shorter time.

To generate a certificate for the Smartphone, you can use the same command and just replace server with client: 

openssl req -x509 -nodes -newkey rsa:2048 -keyout client.key -out client.crt -days 365

Important: You need to keep the private key server.key in a secure location. If an attacker gains access to the private key, they can impersonate the server and decrypt all data sent to the server.

Important: You need to keep the private key client.key in a secure location. If an attacker gains access to the private key, they can impersonate the client and decrypt all data sent from the server.

Next, distribute the certificates and keys as follows:

  1. Server:

    • Keep the server's private key (server.key) securely on the server.
    • Store the server's public certificate (server.crt) on the server.
    • Obtain and store the client's public certificate (client.crt) on the server.

  2. Client (Smartphone):

    • Obtain and store the server's public certificate (server.crt) on the client.
    • Keep the client's private key (client.key) securely on the client.
    • Store the client's public certificate (client.crt) on the client.

Ensure that private keys are never shared or transmitted over insecure channels. Only public certificates should be exchanged between the server and clients.

After distributing the certificates and keys, update your CLAID configuration file to enable mTLS:

CLAID configuration file with mutual TLS (mTLS) encryption

Use the following configuration file to set up two hosts, one acting as server and one as client. The client will connect to the server via mutual TLS. That is, the client needs to know the server's public certificate, and the server needs to know the client's public certificate. The server accepts each client that knows the server's public certificate and has a client certificate which is known by the server. 

{
    "hosts": [
        {
            "hostname": "Server",
            "server_config": {
                "host_server_address": "your_ip:1337",
                "mutual_tls": {
                    "server_public_certificate": "path/to/server.crt",
                    "server_private_key": "path/to/server.key",
                    "client_public_certificate": "path/to/client.crt",
                }
            }  
        },
        {
            "hostname": "Smartphone",
            "connect_to": {
                "host": "Server",
                "mutual_tls": {
                    "server_public_certificate": "path/to/server.crt",
                    "client_public_certificate": "path/to/client.crt",
                    "client_private_key": "path/to/client.key"
                }
            },
        }
    ]
}

Update the configuration files on both the Smartphone and your PC/Server. After you have set it up and copied the required certificate/key files, each connection will be encrypted and authenticated. In case of misconfiguration or invalid key files, the CLAID application will exit.