SecAggPlusWorkflow#

class SecAggPlusWorkflow(num_shares: int | float, reconstruction_threshold: int | float, *, max_weight: float = 1000.0, clipping_range: float = 8.0, quantization_range: int = 4194304, modulus_range: int = 4294967296, timeout: float | None = None)[source]#

Bases: object

The workflow for the SecAgg+ protocol.

The SecAgg+ protocol ensures the secure summation of integer vectors owned by multiple parties, without accessing any individual integer vector. This workflow allows the server to compute the weighted average of model parameters across all clients, ensuring individual contributions remain private. This is achieved by clients sending both, a weighting factor and a weighted version of the locally updated parameters, both of which are masked for privacy. Specifically, each client uploads “[w, w * params]” with masks, where weighting factor ‘w’ is the number of examples (‘num_examples’) and ‘params’ represents the model parameters (‘parameters’) from the client’s FitRes. The server then aggregates these contributions to compute the weighted average of model parameters.

The protocol involves four main stages: - ‘setup’: Send SecAgg+ configuration to clients and collect their public keys. - ‘share keys’: Broadcast public keys among clients and collect encrypted secret

key shares.

  • ‘collect masked vectors’: Forward encrypted secret key shares to target clients and collect masked model parameters.

  • ‘unmask’: Collect secret key shares to decrypt and aggregate the model parameters.

Only the aggregated model parameters are exposed and passed to Strategy.aggregate_fit, ensuring individual data privacy.

Parameters:

  • num_shares (Union[int, float]) – The number of shares into which each client’s private key is split under the SecAgg+ protocol. If specified as a float, it represents the proportion of all selected clients, and the number of shares will be set dynamically in the run time. A private key can be reconstructed from these shares, allowing for the secure aggregation of model updates. Each client sends one share to each of its neighbors while retaining one.

  • reconstruction_threshold (Union[int, float]) – The minimum number of shares required to reconstruct a client’s private key, or, if specified as a float, it represents the proportion of the total number of shares needed for reconstruction. This threshold ensures privacy by allowing for the recovery of contributions from dropped clients during aggregation, without compromising individual client data.

  • max_weight (Optional[float] (default: 1000.0)) – The maximum value of the weight that can be assigned to any single client’s update during the weighted average calculation on the server side, e.g., in the FedAvg algorithm.

  • clipping_range (float, optional (default: 8.0)) – The range within which model parameters are clipped before quantization. This parameter ensures each model parameter is bounded within [-clipping_range, clipping_range], facilitating quantization.

  • quantization_range (int, optional (default: 4194304, this equals 2**22)) – The size of the range into which floating-point model parameters are quantized, mapping each parameter to an integer in [0, quantization_range-1]. This facilitates cryptographic operations on the model updates.

  • modulus_range (int, optional (default: 4294967296, this equals 2**32)) – The range of values from which random mask entries are uniformly sampled ([0, modulus_range-1]). modulus_range must be less than 4294967296. Please use 2**n values for modulus_range to prevent overflow issues.

  • timeout (Optional[float] (default: None)) – The timeout duration in seconds. If specified, the workflow will wait for replies for this duration each time. If None, there is no time limit and the workflow will wait until replies for all messages are received.

Notes

  • Generally, higher num_shares means more robust to dropouts while increasing the computational costs; higher reconstruction_threshold means better privacy guarantees but less tolerance to dropouts.

  • Too large max_weight may compromise the precision of the quantization.

  • modulus_range must be 2**n and larger than quantization_range.

  • When num_shares is a float, it is interpreted as the proportion of all selected clients, and hence the number of shares will be determined in the runtime. This allows for dynamic adjustment based on the total number of participating clients.

  • Similarly, when reconstruction_threshold is a float, it is interpreted as the proportion of the number of shares needed for the reconstruction of a private key. This feature enables flexibility in setting the security threshold relative to the number of distributed shares.

  • num_shares, reconstruction_threshold, and the quantization parameters (clipping_range, quantization_range, modulus_range) play critical roles in balancing privacy, robustness, and efficiency within the SecAgg+ protocol.

Methods

collect_masked_vectors_stage(driver, ...)

Execute the 'collect masked vectors' stage.

setup_stage(driver, context, state)

Execute the 'setup' stage.

share_keys_stage(driver, context, state)

Execute the 'share keys' stage.

unmask_stage(driver, context, state)

Execute the 'unmask' stage.
collect_masked_vectors_stage(driver: Driver, context: LegacyContext, state: WorkflowState) → bool[source]#

Execute the ‘collect masked vectors’ stage.

setup_stage(driver: Driver, context: LegacyContext, state: WorkflowState) → bool[source]#

Execute the ‘setup’ stage.

share_keys_stage(driver: Driver, context: LegacyContext, state: WorkflowState) → bool[source]#

Execute the ‘share keys’ stage.

unmask_stage(driver: Driver, context: LegacyContext, state: WorkflowState) → bool[source]#

Execute the ‘unmask’ stage.