Enable TLS for Secure Connections¶
When operating in a production environment, it is strongly recommended to enable Transport Layer Security (TLS) for each Flower component to ensure secure communication.
Note
For testing purposes, you can generate your own self-signed certificates. The Enable SSL connections page contains a section that will guide you through the process.
Note
Because Flower containers, by default, run with a non-root user app
, the mounted
files and directories must have the proper permissions for the user ID 49999
.
For example, to change the user ID of all files in the certificates/
directory,
you can run sudo chown -R 49999:49999 certificates/*
.
If you later want to delete the directory, you can change the user ID back to the
current user ID by running sudo chown -R $USER:$(id -gn) certificates
.
By default, the ServerApp is executed as a subprocess within the SuperLink Docker container, and the ClientApp is run as a subprocess within the SuperNode Docker container. You can learn more about the different process modes here: Run ServerApp or ClientApp as a Subprocess.
To enable TLS between the SuperLink and SuperNode, as well as between the SuperLink and the flwr
CLI, you will need a PEM-encoded root certificate, private key, and certificate chain.
SuperLink
Assuming all files we need are in the local superlink-certificates
directory,
we can use the flag --volume
to mount the local directories into the SuperLink container:
$ docker run --rm \
--volume ./superlink-certificates/:/app/certificates/:ro \
<superlink-image> \
--ssl-ca-certfile certificates/ca.crt \
--ssl-certfile certificates/server.pem \
--ssl-keyfile certificates/server.key \
<additional-args>
Understanding the command
docker run
: This tells Docker to run a container from an image.--rm
: Remove the container once it is stopped or the command exits.--volume ./superlink-certificates/:/app/certificates/:ro
: Mount thesuperlink-certificates
directory in the current working directory of the host machine as a read-only volumeat the/app/certificates
directory inside the container.This allows the container to access the TLS certificates that are stored in the certificatesdirectory.<superlink-image>
: The name of your SuperLink image to be run.--ssl-ca-certfile certificates/ca.crt
: Specify the location of the CA certificate fileinside the container.Thecertificates/ca.crt
file is a certificate that is used to verify the identity of theSuperLink.--ssl-certfile certificates/server.pem
: Specify the location of the SuperLink’sTLS certificate file inside the container.Thecertificates/server.pem
file is used to identify the SuperLink and to encrypt thedata that is transmitted over the network.--ssl-keyfile certificates/server.key
: Specify the location of the SuperLink’sTLS private key file inside the container.Thecertificates/server.key
file is used to decrypt the data that is transmitted overthe network.
SuperNode
Note
If you’re generating self-signed certificates and the ca.crt
certificate doesn’t
exist on the SuperNode, you can copy it over after the generation step.
$ docker run --rm \
--volume ./superlink-certificates/ca.crt:/app/ca.crt/:ro \
<supernode-image> \
--root-certificates ca.crt \
<additional-args>
Understanding the command
docker run
: This tells Docker to run a container from an image.--rm
: Remove the container once it is stopped or the command exits.--volume ./superlink-certificates/ca.crt:/app/ca.crt/:ro
: Mount theca.crt
file from thesuperlink-certificates
directory of the host machine as a read-onlyvolume at the/app/ca.crt
directory inside the container.<supernode-image>
: The name of your SuperNode image to be run.--root-certificates ca.crt
: This specifies the location of the CA certificate fileinside the container.Theca.crt
file is used to verify the identity of the SuperLink.
In isolation mode process
, the ServerApp and ClientApp run in their own processes.
Unlike in isolation mode subprocess
, the SuperLink or SuperNode does not attempt to
create the respective processes; instead, they must be created externally.
It is possible to run only the SuperLink in isolation mode subprocess
and the
SuperNode in isolation mode process
, or vice versa, or even both with isolation mode
process
.
SuperLink and ServerApp
To enable TLS between the SuperLink and SuperNode, as well as between the SuperLink and the flwr
CLI, you will need a PEM-encoded root certificate, private key, and certificate chain.
Assuming all files we need are in the local superlink-certificates
directory, we can
use the flag --volume
to mount the local directory into the SuperLink container:
$ docker run --rm \
--volume ./superlink-certificates/:/app/certificates/:ro \
flwr/superlink:1.13.1 \
--ssl-ca-certfile certificates/ca.crt \
--ssl-certfile certificates/server.pem \
--ssl-keyfile certificates/server.key \
--isolation process \
<additional-args>
Understanding the command
docker run
: This tells Docker to run a container from an image.--rm
: Remove the container once it is stopped or the command exits.--volume ./superlink-certificates/:/app/certificates/:ro
: Mount thesuperlink-certificates
directory in the current working directory of the hostmachine as a read-only volume at the/app/certificates
directory inside the container.This allows the container to access the TLS certificates that are stored in the certificatesdirectory.flwr/superlink:1.13.1
: The name of the image to be run and the specifictag of the image. The tag1.13.1
represents a specific version of the image.--ssl-ca-certfile certificates/ca.crt
: Specify the location of the CA certificate fileinside the container.Thecertificates/ca.crt
file is a certificate that is used to verify the identity of theSuperLink.--ssl-certfile certificates/server.pem
: Specify the location of the SuperLink’sTLS certificate file inside the container.Thecertificates/server.pem
file is used to identify the SuperLink and to encrypt thedata that is transmitted over the network.--ssl-keyfile certificates/server.key
: Specify the location of the SuperLink’sTLS private key file inside the container.Thecertificates/server.key
file is used to decrypt the data that is transmitted overthe network.--isolation process
: Tells the SuperLink that the ServerApp is created by separateindependent process. The SuperLink does not attempt to create it.
Start the ServerApp container:
$ docker run --rm \
<serverapp-image> \
--insecure \
<additional-args>
Understand the command
docker run
: This tells Docker to run a container from an image.--rm
: Remove the container once it is stopped or the command exits.<serverapp-image>
: The name of your ServerApp image to be run.--insecure
: This flag tells the container to operate in an insecure mode, allowingunencrypted communication. Secure connections will be added in future releases.
SuperNode and ClientApp
Note
If you’re generating self-signed certificates and the ca.crt
certificate doesn’t
exist on the SuperNode, you can copy it over after the generation step.
Start the SuperNode container:
$ docker run --rm \
--volume ./superlink-certificates/ca.crt:/app/ca.crt/:ro \
flwr/supernode:1.13.1 \
--root-certificates ca.crt \
--isolation process \
<additional-args>
Understanding the command
docker run
: This tells Docker to run a container from an image.--rm
: Remove the container once it is stopped or the command exits.--volume ./superlink-certificates/ca.crt:/app/ca.crt/:ro
: Mount theca.crt
file from thesuperlink-certificates
directory of the host machine as a read-only volume at the/app/ca.crt
directory inside the container.flwr/supernode:1.13.1
: The name of the image to be run and the specifictag of the image. The tag1.13.1
represents a specific version of the image.--root-certificates ca.crt
: This specifies the location of the CA certificate fileinside the container.Theca.crt
file is used to verify the identity of the SuperLink.--isolation process
: Tells the SuperNode that the ClientApp is created by separateindependent process. The SuperNode does not attempt to create it.
Start the ClientApp container:
$ docker run --rm \
<clientapp-image> \
--insecure \
<additional-args>
Understand the command
docker run
: This tells Docker to run a container from an image.--rm
: Remove the container once it is stopped or the command exits.<clientapp-image>
: The name of your ClientApp image to be run.--insecure
: This flag tells the container to operate in an insecure mode, allowingunencrypted communication. Secure connections will be added in future releases.
Append the following lines to the end of the pyproject.toml
file and save it:
[tool.flwr.federations.local-deployment-tls]
address = "127.0.0.1:9093"
root-certificates = "../superlink-certificates/ca.crt"
The path of the root-certificates
should be relative to the location of the
pyproject.toml
file.
Note
You can customize the string that follows tool.flwr.federations.
to fit your
needs. However, please note that the string cannot contain a dot (.
).
In this example, local-deployment-tls
has been used. Just remember to replace
local-deployment-tls
with your chosen name in both the
tool.flwr.federations.
string and the corresponding flwr run .
command.