Enable TLS connections¶

Transport Layer Security (TLS) ensures the communication between endpoints is encrypted. This guide describes how to establish secure TLS Superlink ↔ SuperNodes as well as User ↔ SuperLink connections.

Note

This guide builds on the Flower App setup presented in Run Flower with the Deployment Engine guide and extends it to replace the use of --insecure in favour of TLS.

Tip

Checkout the Flower Authentication example for a complete self-contained example on how to setup TLS and (optionally) node authentication. Check out the Authenticate SuperNodes guide to learn more about adding an authentication layer to SuperLink ↔ SuperNode connections.

Certificates¶

Using TLS-enabled connections expects some certificates generated and passed when launching the SuperLink, the SuperNodes and when a user (e.g. a data scientist that wants to submit a Run) interacts with the federation via the flwr CLI.

We have prepared a script that can be used to generate such set of certificates. While using these are fine for prototyping, we advice you to follow the standards set in your team/organization and generated the certificates and share them with the corresponding parties. Refer to the Generate TLS certificates section in the example linked at the top of this guide.

# In the example directory, generate the certificates
$ ./generate_cert.sh

This will generate the TLS certificates in a new certificates/ directory. Copy this directory into the directory of your app (e.g. a directory generated earlier via flwr new).

The approach for generating TLS certificates in the context of this example can serve as an inspiration and starting point, but it should not be used as a reference for production environments. Please refer to other sources regarding the issue of correctly generating certificates for production environments. For non-critical prototyping or research projects, it might be sufficient to use the self-signed certificates generated using the scripts mentioned in this guide.

Launching the SuperLink with TLS¶

This section describes how to launch a SuperLink that works on TLS-enabled connections. The code snippet below assumes the certificates/ directory is in the same directory where you execute the command from. Edit the paths accordingtly if that is not the case. When providing certificates, the SuperLink expects a tuple of three certificates paths: CA certificate, server certificate and server private key.

$ flower-superlink \
    --ssl-ca-certfile certificates/ca.crt \
    --ssl-certfile certificates/server.pem \
    --ssl-keyfile certificates/server.key

Connecting the SuperNodes with TLS¶

This section describes how to launch a SuperNode that works on TLS-enabled connections. The code snippet below assumes the certificates/ directory is in the same directory where you execute the command from. To enable TLS, the only change required when launching the SuperNode is replacing --insecure with --root-certificates

$ flower-supernode \
    --root-certificates certificates/ca.crt \
    --superlink 127.0.0.1:9092 \
    --clientappio-api-address 0.0.0.0:9094 \
    --node-config="partition-id=0 num-partitions=2"

Follow the same procedure, i.e. replacing --insecure with --root-certificates, to launch the second SuperNode.

$ flower-supernode \
    --root-certificates certificates/ca.crt \
    --superlink 127.0.0.1:9092 \
    --clientappio-api-address 0.0.0.0:9095 \
    --node-config="partition-id=1 num-partitions=2"

TLS-enabled Flower CLI¶

The Flower CLI (e.g. flwr run command) is the way a user (e.g. a data scientist) can interact with a deployed federation. The Flower CLI commands are processed by the SuperLink and therefore, if it has been configured to only operate on TLS conenction, the requests sent by the Flower CLI need to make use of a TLS certificate. To do so, replace the insecure = true field in the pyproject.toml with a new field that reads the certificate:

pyproject.toml¶

[tool.flwr.federations.local-deployment]
address = "127.0.0.1:9093"
root-certificates = "./certificates/ca.crt"

Note that the path to the root-certificates is relative to the root of the project. Now, you can run the example by executing flwr run:

$ flwr run . local-deployment --stream

Conclusion¶

You should now have learned how to generate self-signed certificates using the given script, start an TLS-enabled server and have two clients establish secure connections to it. You should also have learned how to run your Flower project using flwr run with TLS enabled. All other commands in the Flower CLI will also be TLS-enabled.

Note

Refer to the Run Flower using Docker documentation to learn how to setup a federation where each component runs in its own Docker container. You can make use of TLS and other security features in Flower such as implement a SuperNode authentication mechanism.

Additional resources¶

These additional sources might be relevant if you would like to dive deeper into the topic of certificates: