Security in Agile Live

How to set up secure connections in Agile Live

This is a tutorial that describes how to setup and use encryption throughout the Agile Live system.

Connections in the system

There are several types of network connections in the Agile Live system that need encryption to protect them, which is especially important when running productions in a public cloud environment or at least transporting parts of a production’s data over public internet. These connections are:

The HTTP requests to the REST API of the System Controller
The WebSocket connections between the components in the system and the System Controller
The SRT/RIST streams transporting the video and audio from the Ingests to the Production Pipelines.
The TCP control connections used to transport control commands from the Control Panel to the Production Pipeline, and to propagate the commands from the Low Delay pipeline to the High Quality pipeline.

The last two connection types above will always be encrypted. Each stream/connection will be setup with its own uniquely generated encryption key. The REST API and the WebSocket connections between the components and the System Controller, however, require some manual setup by the user.

Warning

Even if encryption of the SRT/RIST stream connections between Ingests and Pipelines and the control connections are enabled automatically when HTTPS is turned off in the System Controller, the encryption keys are passed between the components over unencrypted links where anyone can read them in clear text. This effectively means HTTPS must be enabled in the System Controller to consider the other connections secure as well.

Enable HTTPS in the System Controller

Turning the HTTP requests of the REST API and the WebSocket connection between the components and the System Controller secure, requires the following steps to be taken:

Get a TLS certificate from a certificate authority
Point out the cert.pem and key.pem provided by your certificate authority in the System Controller config file under https, attributes certificate_file and private_key_file. Also make sure enabled under https is set to true.
Start the System controller and make sure it prints that the API is served using https
Try accessing the REST API using HTTPS to make sure it works as expected

WebSocket connections will automatically be encrypted when HTTPS is turned on.

In case a component trying to connect to the System Controller using HTTPS and fails with the following error message: Failed to connect to System Controller, message: set_fail_handler: 8: TLS handshake failed this is likely because the ACL_SYSTEM_CONTROLLER_IP is not set to the same hostname as the “Common Name” field is set to in the certificate. Set ACL_SYSTEM_CONTROLLER_IP to the same hostname as in the System Controller’s certificate to make it work.

Self-signed certificates

Self-signed certificates can be used by pointing out the cert.pem and key.pem files as above. The components connecting to a System Controller with self-signed certificates must also enable this by setting the environment variable ACL_INSECURE_HTTPS to true.

Note that it is recommended to always use certificates from a certificate authority.

Setting ACL_INSECURE_HTTPS to true means that the components never verify the server certificate. A somewhat more secure way is to let the components trust a custom CA or a self signed certificate. This can be done by copying the custom CA certificate file or self signed certificate to a file readable by the component. Then set the environment variable ACL_CUSTOM_CA_CERT_FILE to the full path of this certificate file.

Pre-shared key (PSK)

Components connecting to the System Controller must authorize themselves to be accepted and connected. When components connect to the System Controller they present a pre-shared key (PSK) to the System Controller, which must match the PSK set in the System Controller for the component to be allowed to connect. The PSK is set in the System Controller’s config file using the psk attribute before it is started. The PSK must be 32 characters long. All components must then connect using the same PSK, by setting the environment variable ACL_SYSTEM_CONTROLLER_PSK before starting the application. In case the user fails to set the PSK before starting the application, it will immediately quit and print an error message.

Warning

In case HTTPS is not enabled in the System Controller, the PSK will be transported over an unencrypted network connection where anyone can read it in clear text!

Authentication in the REST API

The System Controller REST API is protected with Basic Authentication that will require a username and password to access the API endpoints. To configure this, edit the client_auth part of the System Controller’s config file. Choose which username and password should grant access to the REST API and make sure enabled is set to true to actually activate the authentication check. The configured password is tested for strength on start. The System Controller will not start if the password is judged to be too easy to crack with brute-force.

Warning

In case HTTPS is not enable in the System Controller, the username and password will be transported over an unencrypted network connection where anyone can read it!