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. It also explains how to enable TLS on the internal AppIo connections used by SuperExec, ServerApp processes, and ClientApp processes.

Note

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

Astuce

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.

Certificats¶

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. The same certificates can be used for local prototyping when enabling TLS on internal AppIo connections.

We have prepared a script that can be used to generate such set of certificates. While using these is fine for prototyping, we advise you to follow the standards set in your team/organization and to generate 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
$ python generate_creds.py

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).

Avertissement

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. In production, do not reuse the same server certificate and private key for multiple services. A better practice is to use a unique key pair for each service, for example the SuperLink Fleet API, the SuperLink ServerAppIo API, and each SuperNode ClientAppIo API.

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 accordingly if that is not the case. When providing certificates for the Fleet API and Control API, the SuperLink expects a tuple of three certificates paths: CA certificate, server certificate and server private key. The same command can also provide AppIo certificates for the internal ServerAppIo API.

$ flower-superlink \
    --ssl-ca-certfile certificates/ca.crt \
    --ssl-certfile certificates/server.pem \
    --ssl-keyfile certificates/server.key \
    --appio-ssl-ca-certfile certificates/ca.crt \
    --appio-ssl-certfile certificates/server.pem \
    --appio-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 secure the SuperNode ↔ SuperLink connection, replace --insecure with --root-certificates. The same command can also provide AppIo certificates for the internal ClientAppIo API.

$ flower-supernode \
    --root-certificates certificates/ca.crt \
    --appio-ssl-ca-certfile certificates/ca.crt \
    --appio-ssl-certfile certificates/server.pem \
    --appio-ssl-keyfile certificates/server.key \
    --superlink 127.0.0.1:9092 \
    --clientappio-api-address 127.0.0.1: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 \
    --appio-ssl-ca-certfile certificates/ca.crt \
    --appio-ssl-certfile certificates/server.pem \
    --appio-ssl-keyfile certificates/server.key \
    --superlink 127.0.0.1:9092 \
    --clientappio-api-address 127.0.0.1:9095 \
    --node-config="partition-id=1 num-partitions=2"

At this point, you have successfully launched a SuperLink and two SuperNodes with TLS-enabled connections.

Note

The AppIo TLS options configure server-authenticated TLS. They do not configure mutual TLS. The --appio-ssl-ca-certfile file is used by SuperExec and app processes to verify the AppIo server certificate, not as a client certificate. If AppIo TLS is not configured, internal AppIo connections remain unencrypted and should stay inside a trusted network.

TLS for AppIo Connections in « Process » Isolation Mode¶

For details about SuperExec, « process » isolation mode, and « subprocess » isolation mode, see Flower Network Communication.

So far, we’ve been showing you how to enable TLS for AppIo connections when using the default « subprocess » isolation mode. In this mode, SuperLink and SuperNode automatically start their SuperExecs with the correct AppIo TLS options. However, if you want to run SuperExec separately in « process » isolation mode, you need to do a few things differently to enable TLS for the AppIo connections.

First, we need to launch the SuperLink and SuperNode with --isolation=process and with the AppIo TLS options. This tells the SuperLink and SuperNode that the SuperExecs will be launched separately, e.g. by an operator or orchestration system. Next, in order for the SuperExecs to establish TLS connections to the AppIo APIs, we need to provide the AppIo TLS options when launching the SuperExecs. Below is an example command to launch a SuperExec that can establish TLS connections to the ServerAppIo API of the SuperLink:

$ flower-superexec \
    --root-certificates certificates/ca.crt \
    --appio-api-address 127.0.0.1:9091 \
    --plugin-type serverapp

Next, use the same procedure for a ClientApp SuperExec, but pass the SuperNode’s ClientAppIo API address, e.g. 127.0.0.1:9094, and set --plugin-type clientapp.

Now your SuperLink-side SuperExec and SuperNode-side SuperExec can establish TLS connections to their respective AppIo APIs. When using « process » isolation mode, it is the responsibility of the process launcher (e.g. user or orchestrator) to launch the SuperExecs with the correct AppIo TLS options. If you use an orchestration system to launch the SuperExecs, make sure to include the AppIo TLS options in the commands or configuration used by your orchestration system.

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 your Flower Configuration TOML file with a new field that reads the certificate:

config.toml¶

[superlink.local-deployment]
address = "127.0.0.1:9093"
root-certificates = "/absolute/path/to/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

Astuce

You can setup your local-deployment profile as the default so you don’t have to specify it in every Flower CLI command that needs to connect to the SuperLink. For that and more details about the Flower configuration, refer to the the Flower Configuration guide.

Conclusion¶

You should now have learned how to generate self-signed certificates using the given script, start a 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 and how to secure internal AppIo connections. 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¶

Ces sources supplémentaires peuvent être pertinentes si tu souhaites approfondir le sujet des certificats :