.. _communication_security: Communication Security ====================== NVIDIA FLARE provides multiple options for securing communications between the FL Server and clients, allowing flexibility to meet different IT infrastructure requirements. Connection Security Options =========================== FLARE supports three types of connection security: mTLS (Mutual TLS) ----------------- This is the default and most secure option, using mutual TLS (2-way SSL). PKI credentials in the startup kits are used for client/server connections, ensuring both parties authenticate each other. TLS (One-way SSL) ----------------- In this mode, only server authentication is required. Client certificates are not needed for establishing the connection, but a Root Cert is required to validate the server. You can provide a custom root cert for validating the server. Clear ----- Messages are not encrypted. This is typically used when the server is deployed behind a secure proxy, and the communication between the proxy and the server is already protected. .. _byoconn: BYOConn (Bring Your Own Connectivity) ===================================== FLARE supports custom connectivity solutions that meet the following requirements: * Clients must be able to reach the server (directly or through proxies) * The communication path must ensure message confidentiality and integrity * Messages must be explicitly authenticated Message Authentication ====================== In FLARE 2.5 and above, all messages are explicitly authenticated: 1. Clients login to the server first, authenticating with credentials from their startup kits 2. Upon successful validation, the server issues a token and signature 3. All subsequent messages include the client name, token, and signature as headers 4. The server validates these headers for every message This authentication applies to ALL messages through the Server, regardless of origin (FL clients, 3rd-party systems, or the server itself). Configuration ============= Connection security can be configured at both project and participant levels using the `connection_security` and `custom_ca_cert` properties. Example Configuration: .. code-block:: yaml api_version: 3 name: test25 description: NVIDIA FLARE sample project yaml file connection_security: tls custom_ca_cert: /path/of/customRoot.pem participants: - name: server type: server org: nvidia fed_learn_port: 8002 admin_port: 8003 connection_security: clear - name: site-1 type: client org: nvidia In this example: * Project default is "tls" since it is specified at the project level * Server uses "clear" (behind secure proxy) * Clients use "tls" to connect to the proxy * `custom_ca_cert` is used for proxy server validation The `custom_ca_cert` property is only used for server authentication when making a TLS connection. If not specified, the root CA cert generated by the provisioning system will be used. If `connection_security` is not specified, the default will be mTLS. When to Use Custom CA Certificates ---------------------------------- Customers may implement their connectivity using some proxies that will sit between FL Clients and the FL Server. FL Clients only directly connect to the proxy server, which then connects to the FL Server. Typically FL Clients will use one-way SSL to connect to the proxy server. In this case, the `custom_ca_cert` is the CA cert used by the proxy server. Multi-Address Support of FL Server ================================== Previously, the FL Server had a single address that must be used for all FL clients to access. Another limitation was that the server address must be specified as a domain name - IP addresses were not supported. Furthermore, the domain name also had to be specified as the name of the server in provisioning configuration. Since the name is set to the common name of the server's certificate, it could not exceed 63 characters. This made it impossible to use domain names longer than 63 characters. Flare 2.6 will support multiple addresses for the FL Server. In this case, the FL Server can expose multiple addresses that can be used for FL clients to connect. Depending on the customer's IT policies, different FL clients may use different addresses. For example, the FL Server may provide two addresses, one accessible from the internet, and another accessible that is accessible only from the internal network. Server address can be specified as a domain name or an IP address. Example Configuration: .. code-block:: yaml participants: - name: server type: server org: nvidia fed_learn_port: 8002 admin_port: 8003 host_names: [localhost, 127.0.0.1] default_host: localhost # connection_security: clear - name: red type: client org: nvidia connect_to: 127.0.0.1 - name: blue type: client org: nvidia connect_to: localhost In this example, the FL Server defines additional two host names using the host_names property: `localhost` (a domain name) and `127.0.0.1` (an IP address). To be backward compatible, the name of the server is treated as the default address if the default_host property is not explicitly defined. In this example, the default address is explicitly defined as `localhost`. Addresses specified with the `host_names` property are limited to 255 characters. Three clients are defined here: red, blue, and silver. The `connect_to` property specifies the address to use for the client. Of course, the specified address must be available from the server. In this example, client "red" will connect to 127.0.0.1; client "blue" will connect to "localhost"; client "silver" will connect to the default address of the server, which is "localhost". The admin client will connect to 127.0.0.1. For this configuration to work, the IT Administrator of the FL Server must ensure that the specified addresses are actually accessible. Connection Security and secure_train Flag ========================================= The `secure_train` flag and connection security are independent but related: * Connection Security specifies how connections are made (Clear, TLS, or mTLS) * If not explicitly specified, connection security defaults based on `secure_train`: - `secure_train=True`: Use mTLS - `secure_train=False`: Use clear * This default behavior is maintained for backward compatibility, as these two settings were previously treated as one * `secure_train` applies project-wide and cannot vary by site * Connection Security can vary by site to accommodate different network setups * `secure_train` also enables privacy protection features (e.g., loading privacy resources from the site's local folder) * The `secure_train` flag is always set to True, except when using the Simulator Connection Security is site-specific, allowing different settings for different sites as long as connections can be established properly. For example: * Server may use "clear" connection security * Site-1 may use TLS * Site-2 may use mTLS This flexibility is particularly useful in BYOConn (Bring Your Own Connectivity) scenarios where customers may use proxies between the Server and sites. In such cases: * Sites don't directly connect to the Server * Each site can have its own connection security setting appropriate for its connection to its proxy * The customer must ensure proper connection security setup between sites and their respective proxies Important Notes =============== * All sites must protect their startup kits securely * Never share tokens and signatures with others * The IT infrastructure must allow necessary ports to be opened * Server addresses must be properly configured and accessible * Custom CA certificates must be properly managed and secured