Fix POC HE mode, add HE step-by-step example (#2255)

* fix POC HE mode, add HE sbs * change poc start to markdown
NVIDIA · Jan 4, 2024 · 51022c7 · 51022c7
1 parent ce4108a
commit 51022c7
Show file tree

Hide file tree

Showing 3 changed files with 228 additions and 2 deletions.
diff --git a/examples/hello-world/step-by-step/cifar10/sag_he/sag_he.ipynb b/examples/hello-world/step-by-step/cifar10/sag_he/sag_he.ipynb
@@ -0,0 +1,225 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "514c47e2-420d-4af4-9bf0-cac337c51c39",
+   "metadata": {},
+   "source": [
+    "# SAG workflow with Homomorphic Encryption\n",
+    "\n",
+    "In this example, we will demonstrate how to use homomorphic encryption (HE)\n",
+    "by building on the previous [FedAvg with SAG workflow](../sag/sag.ipynb#title) example using the CIFAR10 datset.\n",
+    "\n",
+    "## Homomorphic Encryption\n",
+    "\n",
+    "Homomorphic encryption is a form of encryption that allows computations to be performed on encrypted data, which is especially useful for preserving privacy in a federated learning setting.\n",
+    "FLARE uses the [TenSEAL](https://github.com/OpenMined/TenSEAL) library to enable homomorphic encryption operations on tensors in the provided FLARE [HE implementation](https://github.com/NVIDIA/NVFlare/tree/main/nvflare/app_opt/he).\n",
+    "\n",
+    "## Job Configuration\n",
+    "\n",
+    "On the client side, to configure homomorphic encryption we must add the following HE filters in config_fed_client.conf:\n",
+    "\n",
+    "- `HEModelDecryptor`: Data filter to decrypt incoming Shareable objects using HE.\n",
+    "- `HEModelEncryptor`: Result filter to encrypt outgoing Shareable objects using HE.\n",
+    "\n",
+    "On the server side, we configure components with HE support in config_fed_server.conf:\n",
+    "\n",
+    "- `HEModelShareableGenerator`: This ShareableGenerator converts between Shareable and Learnable objects using HE.\n",
+    "- `HEInTimeAccumulateWeightedAggregator`: Filter to encrypt Shareable object using HE.\n",
+    "- `HEModelSerializeFilter`: Used to serialize TenSEAL encrypted server models for use with HE support.\n",
+    "\n",
+    "Let's use the Job CLI to create the job from the sag_pt_he template:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8276090f-4598-4a41-b8b3-4b73e21e0694",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! nvflare config -jt ../../../../../job_templates"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "de430380",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! nvflare job create -j /tmp/nvflare/jobs/cifar10_sag_pt_he -w sag_pt_he -sd ../code/fl -force"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5fd8e88f",
+   "metadata": {},
+   "source": [
+    "We can take a look at the client and server configurations and make any changes as desired:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "369c5501",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! cat /tmp/nvflare/jobs/cifar10_sag_pt_he/app/config/config_fed_client.conf"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d223847b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! cat /tmp/nvflare/jobs/cifar10_sag_pt_he/app/config/config_fed_server.conf"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "83cc8869",
+   "metadata": {},
+   "source": [
+    "## Prepare Data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8f63bf0f",
+   "metadata": {},
+   "source": [
+    "Make sure the CIFAR10 dataset is downloaded with the following script:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "17323f61",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! python ../data/download.py --dataset_path /tmp/nvflare/data/cifar10"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d71f3c9f-8185-47d3-8658-40f7b16699c5",
+   "metadata": {},
+   "source": [
+    "## Run the Job using POC mode\n",
+    "\n",
+    "First ensure that the TenSEAL dependency is installed:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "395eec58",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! pip install nvflare[HE]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8ba25168",
+   "metadata": {},
+   "source": [
+    "To support HE, we need the provision process to generate and write the TenSEAL homomorphic encryption contexts for the server and client.\n",
+    "Currently the simulator does not support HE, however we can use the POC command `-he` option to prepare the HE supported POC workspace with the `HEBuilder`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "648fb34b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! nvflare poc prepare -he"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8bcd8acd",
+   "metadata": {},
+   "source": [
+    "Start the FLARE system in POC mode in another terminal with ```nvflare poc start -ex [email protected]```\n",
+    "\n",
+    "Finally we can submit our HE configured job:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b8c56201",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! nvflare job submit -j /tmp/nvflare/jobs/cifar10_sag_pt_he"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d8e02b36",
+   "metadata": {},
+   "source": [
+    "Once you are finished with the example, you can shutdown and clean the POC system:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c6cf89ad",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! nvflare poc stop"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9a6f427d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! nvflare poc clean"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b19da336",
+   "metadata": {},
+   "source": [
+    "As an additional resource, see the [CIFAR10 Real World Example](https://github.com/NVIDIA/NVFlare/tree/main/examples/advanced/cifar10/cifar10-real-world) for creating a secure workspace for HE using provisioning instead of POC mode."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "nvflare_example",
+   "language": "python",
+   "name": "nvflare_example"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/examples/tutorials/setup_poc.ipynb b/examples/tutorials/setup_poc.ipynb
@@ -698,7 +698,8 @@
     "tags": []
    },
    "source": [
-    "Notice:  ```path: nvflare.lighter.impl.he.HEBuilder``` is added to the YAML file"
+    "Notice:  ```path: nvflare.lighter.impl.he.HEBuilder``` is added to the YAML file.\n",
+    "Also note the importance of the order of the builders, as the `HEBuilder` must be configured before the `SignatureBuilder` to ensure the tenseal context files are signed."
    ]
   },
   {

diff --git a/nvflare/tool/poc/poc_commands.py b/nvflare/tool/poc/poc_commands.py
@@ -366,7 +366,7 @@ def add_he_builder(use_he: bool, project_config: OrderedDict):
             "path": "nvflare.lighter.impl.he.HEBuilder",
             "args": {},
         }
-        project_config["builders"].append(he_builder)
+        project_config["builders"].insert(-1, he_builder)
 
     return project_config