Relays

Summary

Relays are special, small network servers operated by Cosnim. Relays are used to accelerate some internal operations such as rosters, which are very small network broadcasts used by instances to exchange the capsules that they and others have created or discovered in storage. The information exchanged does not disclose anything about your actual data - they only carry very small tidbits of continuum mesh information that helps instances operate storage more effectively.

Using relays can improve the speed at which cosnim commands start, the speed at which multiple users become aware of other user’s modifications in a shared continuum, and can significantly reduce the number of queries made to cloud storage providers.

Relays are very easy to operate, and you should consider using them whenever you are running many continuums or large continuums.

Cosnim instances do not need relays to operate, but when configured and running, they can improve the general performance and responsiveness.

Configuration

To run a relay, you first need a machine that is accessible to other users and instances through TCP/IP. This can be a virtual machine, a cloud instance, or any other computer exposed to the network.

Relays are configured in the ‘relays’ section of the configuration file. You need to configure both a client and a server section for relays to operate. You then must identify the relay to use in the ‘relay’ parameter of the ‘continuum’ section and all capsule hubs sections that you wish to leverage relay acceleration (you’ll normally want to use relays in all capsule hubs). See the Configuration Reference for details.

Security

Although relays do not exchange any sensitive information and clients need critical information obtained from encrypted capsules before they can participate in a relay network, you may want to implement additional security controls. You can do this using public-key infrastructure security operated by the relays. Security can be implemented at two levels: SSL/TLS and client authorization.

SSL/TLS

You can encrypt the communication channels themselves using SSL/TLS. To do this, configure both a client and server url that begins with ‘tcps://’ in the client and server subsections of the ‘relays’ section of the configuration.

You will then need to generate a server certificate and private key so that clients can authenticate the server. These are standard SSL/TLS certificates. If you don’t have an existing SSL/TLS infrastructure, you can use the following openssl commands to generate the required certificate authority, keys and server certificates:

 ##--- Generate a root CA private key
 openssl genrsa -out ca.key 4096

 #--- Generate the root CA certificate
 openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 -out ca.crt \
    -subj "/C=CA/ST=Ontario/L=Toronto/O=My Company/OU=Root CA/CN=Root CA"

 #--- Generate the server private key
 openssl genrsa -out server.key 2048

 #--- Generate the server certificate
 openssl req -new -key server.key -out server.csr \
    -subj "/C=CA/ST=Ontario/L=Toronto/O=My Company/OU=Server/CN=localhost"
 openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \
    -CAcreateserial -out server.crt -days 365 -sha256 -extfile server.ext

#--- Generate a certificate bundle the server can use to serve requests
cat server.crt ca.crt > my-server.crt

Then, configure the client section’s ‘ca_cert_file’ parameter to point to the certificate authority certificate. If that was generated with the above openssl commands, that would be:

ca-cert_file: ca.crt

Finally, configure the server’s section ‘private_key_file’ and ‘ssl_cert_file’ parameters. If they were generated with the above openssl commands, that would be:

private_key_file: server.key
ssl_cert_file: my-server.crt

Client Authorization

To control which client can connect to a relay, you must use public-key infrastructure. Contrarily to SSL/TLS, relays handle client authorization internally and do not require SSL/TLS to operate. You may, therefore, activate client authorization without using SSL/TLS.

There are two parts to relay client authorization:

1. The client private key; this is used to authenticate the client with the relay server cryptographically.

2. A list of client’s public keys that a relay server will accept for connection.

On the client side, you may use the same private key as the one used for digital signature cascades. You can generate one with the command:

cosnim generate key --key user.name@company.com --type eddsa-255

You then need to export the equivalent public key to that private key to the server. You can do this with the command:

cosnim export key --key user.name@company.com --public --file FILENAME

Finally, import the public key in the relay server’s keychain:

cosnim import key --key user.name@cosnim.com --file FILENAME

The relay server’s ‘auth_keychain’ parameter must be set to enforce client authorization. This identifies the keychain containing the public key of all clients authorized to connect to it. When adding new clients, simply import their public key into the server’s keychain. The relay will automatically fetch the new public keys as they are added.

Starting a relay

Start a Cosnim relay server on the target machine with the following command:

cosnim start relay RELAY_NAME

Relays can stay up and running all the time. They consume minimal resources and do not use any persistent storage, so they can easily run inside static containers or non-persistent cloud instances.

As soon as the relay is started, client instances will automatically connect to it and start sharing information. This process is automatic.