Skip to content

How it works

SocketXP IoT Cloud Gateway performs mTLS authetication on all devices that connect to the mTLS gateway port 9444.

The gateway will continue to perform traditional TLS authentication on all devices that connect to the TLS gateway port 9443.

The primary difference between mTLS and traditional TLS is that mTLS requires mutual authentication of both parties(server and client) involved in the communication, while traditional TLS only requires the server to be authenticated and not the client.

Customers who have a need for mTLS authentication can request mTLS authentication using appropriate SocketXP agent side configurations, that will be explained in the sections below.

Mutual TLS gateway port

By default, SocketXP agent will connect to the TLS gateway port 9443. SocketXP agent will not connect to the mTLS gateway port 9444 by default.

You need to use the socketxp agent command line configuration flag --gateway-port to request the agent to connect to the mTLS gateway port 9444 as shown in the example below.

sudo socketxp connect tcp://127.0.0.1:22 --gateway-port 9444 ...

Downloading Certificates

SocketXP CA (Certificate Authority) module can be accessed via the TLS gateway port 9443 only. It is not available over an mTLS channel because then you'll need a certificate to download one, which becomes a "chicken and egg" problem. So SocketXP CA is made available on the traditional TLS gateway port 9443 only, which is still an end-to-end encrypted channel.

Download the server and client certificates from the CA using the "socketxp ca login" command. You need to obtain an auth token from the SocketXP web portal to request a new certificate download.

Server Certificate

You'll need a server or host certificate to register a device with the cloud gateway. The server certificate has a very long validity period. You can periodically renew/rotate the server certificate, if required.

Execute the below CA command to login and download a TLS server certificate from the cloud gateway's CA module.

sudo socketxp ca login <your-auth-token> --server "device123.local.example"

Downloaded device/host certificate from the CA.

Where "device123.local.example" is the internal host name for your device or host machine.

$ ls /var/lib/socketxp/

tls_server.crt  tls_server.key

Client Certificate

You'll need a client or user certificate to connect to a remote device using the SocketXP agent in IoT slave mode. The client certificate has a short validity period(24 hours). You can always obtain a new client certificate, if a certificate expires.

Execute the below CA command to login and download a TLS client certificate from the cloud gateway's CA module.

sudo socketxp ca login <your-auth-token> --client "[email protected]"

Downloaded client certificate from the CA.
Where "[email protected]" is the email ID of the user who wants to connect to an IoT device using the certificate.

$ ls /var/lib/socketxp/

tls_client.crt  tls_client.key

Device Registration (mTLS)

Now that we have downloaded the certificates from the CA, it's time to register the IoT device with the Cloud Gateway, as usual, using the regular socketxp login command.

socketxp login <your-auth-token> --gateway-port 9444 --mtls --cert /var/lib/socketxp/tls_client.crt --key /var/lib/socketxp/tls_client.key

We request the socketxp agent to connect to the mTLS gateway port 9444 (which is a non-default gateway port). We also specify that the agent should connect to the cloud gateway using mTLS authentication using the --mtls flag. We finally provide the TLS server certificate and key required for the mTLS authentication using the --cert and --key flags, respectively.

Connecting Device to the Gateway (mTLS)

Now that we have registered the device with the gateway and obtained a device license (/var/lib/socketxp/device.key), let's try connecting the device to the cloud gateway using the mTLS gateway port 9444.

socketxp connect tcp://127.0.0.1:22 --gateway-port 9444 --mtls --cert /var/lib/socketxp/tls_server.crt --key /var/lib/socketxp/tls_server.key 

Connected to SocketXP Cloud Gateway.
Access the TCP service securely from the web portal or using the SocketXP agent in IoT slave mode.

Configuration File

Here is a sample configuration file to enable mTLS authentication:

$ cat /etc/socketxp/config.json

{
        "gateway_port": 9444,
        "mtls": {
            "enable": true,
            "cert": "/var/lib/socketxp/tls_server.crt",
            "key": "/var/lib/socketxp/tls_server.key"
        },
        "tunnels": [
            {
                    "destination": "tcp://127.0.0.1:22"
            },
            {
                    "destination": "http://127.0.0.1:8080"
            }
        ]

}