SecAggWorkflow#

class SecAggWorkflow(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: SecAggPlusWorkflow

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:

  • 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

  • Each client’s private key is split into N shares under the SecAgg protocol, where N is the number of selected clients.

  • Generally, 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 reconstruction_threshold is a float, it is interpreted as the proportion of the number of all selected clients needed for the reconstruction of a private key. This feature enables flexibility in setting the security threshold relative to the number of selected clients.

  • 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#

Execute the ‘collect masked vectors’ stage.

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

Execute the ‘setup’ stage.

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

Execute the ‘share keys’ stage.

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

Execute the ‘unmask’ stage.