Skip to main content

Sodot Relay Server

This is Sodot relay server, an on-premises solution for Sodot's relay services.

Architecture​

The on-prem solution comes in the form a dedicated docker image which should be run on your organization's computing infrastructure. This guide assumes the existence of a docker image execution engine available. Most common cloud service providers offer such services (e.g. ECS on AWS, Azure Container Services on Azure, Google run jobs on GCP).

Installation Process​

The installation process is made of the following steps:

  1. Collecting installation parameters
  2. Obtaining a TLS certificate
  3. Allocating computing resources
  4. Running the server
  5. Modify existing code
  6. Testing the server

1. Collecting Parameters​

At this step you should collect the following pieces of information, listed down below. At the end of each bullet we put in parantheses a capitalized name which will be used to refer to the value being set throughout the rest of the paper.

  1. The endpoint URL of your hosted (URL_ENDPOINT).
  2. The dockerhub token which you should obtain from Sodot team (DOCKERHUB_TOKEN).

2. (Optional) Obtaining a TLS certificate​

You should obtain a TLS cerificate for the URL_ENDPOINT domain. The TLS certificate comes in two separate files:

  1. The certificate itself, which is considered public a non-sensitive.
  2. The matching private key for this certificate which must be kept secret at all times.

Notice: The TLS certificate should be generated for the exact URL_ENDPOINT.

Optional:
If you do not specify the --chain-path and --key-path arguments shown below, then the server will start listening for HTTP connections on port 80. The SDKs will still require a TLS connection to the relay server, so in this case you must set up your own TLS server that will proxy requests to the docker container running the relay server.

3. (Optional) Determining a room ID prefix​

The relay server can be configured to set room IDs with a predetermined prefix. This is often found useful when setting up multiple relay containers behind a load balancer. Then, a load balancer can be configured to route parties accessing the same room id towards the same container. The prefix is made of exactly eight hexadecimal characters (0-9,a-f, only lowercase letters). This prefix is determined by providing the --room-id-prefix command line argument.

Example

To set the prefix to 1a2b3c4d, pass the --room-id-prefix 1a2b3c4d argument.

4. (Optional) Setting preconfigured API keys​

A relay server may be configured to accept a set of preconfigured API keys. A preconfigured API key has no expiration date, but can be revoked at any point. A preconfigured API key is provided via the --api-key command line argument. To provide moultiple keys, provide the --api-key for each API key. When the --api-key API_KEY argument is provided, the API_KEY value is encoded as KEY,NAME where KEY is the base16 encoding of a 16-byte value and NAME is the name of the API key.

Example

To set a 16-byte API key with the following hexadecimal representation: 00112233445566778899aabbccddeeff with the name AdminKey pass the --api-key ABEiM0RVZneImaq7zN3u/w==,AdminKey.

tip

A hexadecimal srting can be base64-encoded in bash-like shells using the following command.

$ echo -n '00112233445566778899aabbccddeeff' | xxd -r -p | base64
ABEiM0RVZneImaq7zN3u/w==

5. Allocating computing resources​

At this step you should be allocating the necessary computing resources to run the docker image on your premises. Within the allocated computing resource you should log-in to dockerhub. If docker is being run within a dedicated virtual machine this can be easily done via:

docker login -u sodot -p <DOCKERHUB_TOKEN>

In other settings you may have to configure the storage of the token within a dedicated secrets manager. Therefore, this step depends on your cloud provider.

6. Running the server​

At this step you should execute the server. The container image's is located within dockerhub under sodot/sodot-relay-server and should be fetched from this official repository only. The server is expecting port 443 (HTTPS) to be exported and should therefore be configured according in your setting. The docker image itself expects two parameters (in this order) which sould be provided during execution:

  1. A path (within the docker instance) to the TLS certificate.
  2. A path (within the docker instance) to the TLS private key.

The files must resides within the instance upon execution and can be fed into the instance via various methods such as:

  1. Mouting a docker volume containing the specified files (using the -v flag).
  2. Using docker secret management API provided by your computing environment.

Optional: You may specify the RUST_LOG environment variable to specify the verbosity of the logging generated by the relay server. By default (i.e. without specifying any value), no logs will be generated. This can be specified, for example, using the -e RUST_LOG=<level> flag provided during execution of the docker run command. The <level> parameter can be any of: debug, trace, info, warn, error.

Example: In the following we provide an example of executing the docker image using the standard docker CLI. We use the following parameters:

  • The cerficiate is stored at /home/user/fullchain.pem and will be mounted on /root/fullchain.pem within the docker instance.
  • The private key is stored at /home/user/privkey.pem and will be mounted on /root/privkey.pem within the docker instance.
  • We want the API keys generated to be stored at /home/user/relay and will mount on /opt/relay, the file path provided should be on a persistent storage device that is backed up.
  • We enable logs with info level of verbosity.
docker run -e RUST_LOG=info \
           -v /home/user/fullchain.pem:/root/fullchain.pem \
           -v /home/user/privkey.pem:/root/privkey.pem \
           -v /home/user/relay:/opt/relay
           -p 443:443 \
           -d \
           --name sodot-relay \
           -t sodot/sodot-relay-server \
           /sodot-relay-server \
                --chain-path /root/fullchain.pem \
                --key-path /root/privkey.pem \
                --api-key KEY1,NAME1 \
                --api-key KEY2,NAME2 \
                --room-id-prefix 0a1b2c3d
tip

During development the server can be given the --insecure-api-keys-not-enforced flag to disable all API key checks.

7. Modify Existing Code​

By default, the Ecdsa,Ed25519,StatefulEcdsa and StatefulEd25519 classes are routed to a Sodot owned relay server and may be provided with an additional parameter specifying the URL of the on-prem relay server.

For instace, consider the const ecdsa = new Ecdsa() constructor call. Calling it should now be made with the extra parameter of URL_ENDPOINT like so:

    const ecdsa = new Ecdsa(URL_ENDPOINT);

The same holds for the calling to any of the following constructors:

    const ed25519 = new Ed25519(URL_ENDPOINT);
    const ecdsa = new StatefulEcdsa(URL_ENDPOINT);
    const ed25519 = new StatefulEd25519(URL_ENDPOINT);

As shown in the API reference here

8. Setting up API keys​

Once your server is running it will print a secret management token.
You may use this token to create, list and revoke API keys. You may optionally set a custom secret token by providing the --secret_auth flag with a custom value when running your container.

Creating an API Key
Send a GET request to:

https://<URL_ENDPOINT>/createkey/<key_name>/<expiration_timestamp>/<SECRET_TOKEN>

An expiration time of 0 will mean the API key will be valid forever.

List All API Keys
Send a GET request to:

https://<URL_ENDPOINT>/rooms/<SECRET_TOKEN>

Note that under "Licenses" all keys will be listed.

Revoking an API Key
Send a GET request to:

https://<URL_ENDPOINT>/revokekey/<key_name>/<SECRET_TOKEN>

This will revoke the key key_name.

9. Testing the server​

At this point all code should be working and therefore you should be able to successfully execute all your test cases.

Optional (Recommended): It may be useful to set up a separate on-premises relay server that is dedicated for testing and experiment your code in "Debug Mode".