update: create ibond flex

MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include *.png
+recursive-include flex *.json

README.md

@@ -0,0 +1,68 @@
+
+FLEX(Federated Learning EXchange，FLEX)是同盾科技AI研究院为知识联邦体系设计并打造的一套标准化的联邦协议。
+FLEX协议约定了联邦过程中参与方之间的数据交换顺序，以及在交换前后采用的数据加解密方法。只要参与各方能够遵守这些约定，就可以安全地加入到联邦中提供数据或使用联邦服务。
+
+FLEX协议包括两层：
+1. 应用协议：这一层协议是面向联邦算法的，为联邦算法提供多方数据交换的应用支撑。
+协议中会约定多方间数据交换的顺序和采用的具体密码算法。联邦过程中采用的通信协议也会被封装在这里。
+2. 公共组件：是上层应用协议所依赖的基础密码算法和安全协议，比如同态加密、秘密分享等。
+
+<div style="text-align: center;">
+
+![FLEX协议总览](doc/pic/FLEX-structure.png)
+</div>
+
+本项目实现了FLEX白皮书中的应用协议和公共组件，其中通信接口使用同盾科技AI研究院自研的Ionic Bond协议接口，本项目仅给出了一种简单实现作为参考。
+
+# 安装教程
+
+FLEX协议可源码直接运行，支持Python3.6以上运行环境，并设置环境变量
+```console
+export PYTHONPATH="/path/to/flex"
+```
+安装基本的依赖库，以Ubuntu系统为例：
+
+`apt install libgmp-dev, libmpfr-dev, libmpc-dev`
+
+`pip install numpy`,`gmpy2`,`pycryptodome`,`scikit_learn`,`py_ecc`,`pandas`
+
+即可运行协议。
+
+用户也可通过FLEX中提供的工具将其安装到系统中.在源码目录运行：
+```console
+pip install .
+```
+进行安装，然后可通过`from flex.api import *`来调用协议。
+
+# 运行测试
+FLEX提供了基本的测试代码，主要用于测试协议中的通信是否正常运行。通常情况下，用户需在三台主机上安装FLEX协议，分别扮演Coordinator, Guest, Host角色，用户需根据实际的主机hostname/ip修改federal_info，然后运行测试程序。FLEX也提供了单机模式，用于在一台机器上模拟测试协议运行。具体的测试说明见[test_intro](doc/test_intro.md)。
+
+# API与文档
+对于上层协议，通过统一的api进行调用，典型的流程是通过make_protocol得到协议实例，使用exchange方法来执行协议。以安全聚合为例：
+```python
+from flex.api import make_protocol
+from flex.constants import OTP_SA_FT
+
+# 初始化
+protocol = make_protocol(OTP_SA_FT, federal_info, sec_param, algo_param)
+# 执行
+protocol.exchange(theta)
+```
+其中，federal_info为联邦参与方信息，sec_param为协议的安全参数，规定了协议中使用的密码方法、密钥长度等，algo_param为算法超参数，也可以为空。Theta是协议执行时的输入，具体的参数说明及协议使用请参考[api_intro](doc/api_intro.md)。
+
+对于公共组件部分，通过flex.crypto中相应的模块api进行调用，如paillier同态加密算法的调用如下：
+```python
+from flex.crypto.paillier.api import generate_paillier_encryptor_decryptor
+
+# 生成加密器和解密器
+pe, pd = generate_paillier_encryptor_decryptor(n_length = 2048)
+# 加密
+en_x = pe.encrypt(x)
+en_y = pe.encrypt(y)
+# 求和
+en_z = en_x + en_y
+# 解密
+z = pd.decrypt(en_z)
+```
+
+各公共组件的具体使用请参考[crypto_intro](doc/crypto_api_intro.md)。

doc/api_intro.md

@@ -0,0 +1,173 @@
+FLEX中目前支持多种类型的应用协议，包括联邦共享、联邦预处理、联邦计算、联邦训练、联邦预测几个大类，具体的协议如下表所示：
+
+| 协议类型 | 协议名 | 协议描述 | 
+| :----- | :----- | :-----   |
+| 联邦共享 |OT_INV|匿踪查询：解决查询过程中如何保护查询请求方用户ID信息不为其它参与方所知|
+| 联邦共享 |SAL |安全对齐：一种简单、高效的样本对齐协议，其目的是计算参与方之间的样本交集|
+| 联邦预处理 |IV_FFS |信息价值特征选择：跨特征联邦场景下的信息价值的计算|
+| 联邦训练 |HE_LINEAR_FT |跨特征联邦线性回归训练：跨特征线性回归训练中计算损失函数|
+| 联邦训练 |HE_OTP_LR_FT1 |跨特征联邦逻辑回归训练：跨特征逻辑回归训练中计算损失函数|
+| 联邦训练 |HE_OTP_LR_FT2 |跨特征联邦逻辑回归训练：跨特征逻辑回归训练中计算损失函数|
+| 联邦训练 |OTP_SA_FT |安全聚合：基于一次一密的安全聚合|
+| 联邦训练 |HE_SA_FT |安全聚合：基于同态加密的的安全聚合|
+| 联邦预测 |HE_LR_FP |跨特征联邦逻辑回归预测：跨特征逻辑回归预测中间结果汇总|
+
+# 协议初始化
+FLEX设计了统一的接口来初始化各类应用协议，通过flex.api中make_protocol方法统一创建。调用方式如下：
+```python
+from flex.api import make_protocol
+from flex.constants import *
+
+protocol = make_protocol(protocol_name, federal_info, sec_param, algo_param)
+```
+
+# 输入
+
+* protocol_name
+
+  protocol_name在flex.constants中统一定义，见上表协议名列，与FLEX白皮书中协议名一致。
+
+* federal_info
+
+  federal_info规定了联邦参与方的信息和本方的信息。其基本格式如下：
+```json
+{
+   "server":        "localhost:6001",
+   "session": 
+   {
+       "role":      "guest",
+       "local_id":  "zhibang-d-014011",
+       "job_id":    "test_job"
+   },
+   "federation": 
+   {
+       "host":          ["zhibang-d-014010"],
+       "guest":         ["zhibang-d-014011"],
+       "coordinator":   ["zhibang-d-014012"]
+   }
+}
+```
+其中，server为本地服务主机和通信协议端口号；federation中规定了本次联邦的所有参与方，分为host, guest和coordinator三种角色，每种角色由多个参与方的id组成；session中规定了本方的角色-role，本地的参与方id-local_id和本次协议的job_id。
+一般地，不同次协议应使用不同的job_id来区分。
+
+在匿踪查询协议OT_INV中，需要在federal_info的session中额外提供identity关键字，identity的值有client和server两种。
+
+* sec_param
+
+  sec_param是协议中与安全相关的参数，规定了协议中使用的加密方式，安全密码的长度等。如线性回归HE_Linear_FT中，安全参数包括同态加密算法名和同态加密密钥长度，如下所示：
+```python
+{
+    "he_algo": "paillier",
+    "he_key_length": 1024
+}
+```
+表示该算法使用paillier同态加密，密钥长度为1024。每种协议的默认安全参数定义在对应协议的实现代码所在文件夹中，以sec_param.json命名。协议初始化时，会先加载默认安全参数，再覆盖以用户自定义参数。
+
+* algo_param
+
+  algo_param是协议中与模型、算法相关的超参数。每种协议的默认超参数定义在对应协议的实现代码所在文件夹中，以algo_param.json命名。协议初始化时，会先加载默认超参数，再覆盖以用户自定义参数。并非每种协议都拥有超参，对于无需超参的协议，可不输入该参数或设置为None。
+
+# 输出
+对于每种协议，根据federal_info中role的不同，make_protocol返回不同的类实例。如当协议名为HE_LINEAR_FT时，make_protocol可返回三种不同的类实例，HELinearFTCoord、HELinearFTGuest和HELinearFTHost，分别对应role为Coordinator、Guest和Host的情况。
+
+| 协议名 | role:coordinator | role:guest | role:host| identity:server | identity:client |
+| :----- | :----- | :----- | :----- | :----- | :----- |
+|OT_INV| | | |OTINVServer|OTINVClient|
+|SAL |SALCoord|SALGuest|SALHost| | |
+|IV_FFS | |IVFFSGuest|IVFFSHost| | |
+|HE_LINEAR_FT |HELinearFTCoord|HELinearFTGuest|HELinearFTHost| | |
+|HE_OTP_LR_FT1 | |HELRGuest|HELRHost| | |
+|HE_OTP_LR_FT2 |HEOTPLRCoord|HEOTPLRGuest|HEOTPLRHost| | |
+|OTP_SA_FT |OTPSAFTCoord|OTPSAFTGuest|OTPSAFTHost| | |
+|HE_SA_FT |HESAFTCoord|HESAFTGuest|HESAFTHost| | |
+|HE_LR_FP |HELRFPCoord|HELRFPGuest|HELRFPHost|
+
+# 示例
+Host端生成FMC协议实例
+```python
+from flex.api import make_protocol
+from flex.constants import FMC
+
+
+federal_info = {
+   "server":        "localhost:6001",
+   "session": 
+   {
+       "role":      "host",
+       "local_id":  "zhibang-d-014010",
+       "job_id":    "test_job"
+   },
+   "federation": 
+   {
+       "host":          ["zhibang-d-014010"],
+       "guest":         ["zhibang-d-014011"],
+       "coordinator":   ["zhibang-d-014012"]
+   }
+}
+
+algo_param = {
+    "mpc_precision": 4
+}
+
+protocol = make_protocol(FMC, federal_info, None, algo_param)
+```
+
+Server端生成OT_INV协议实例
+```python
+from flex.api import make_protocol
+from flex.constants import OT_INV
+
+
+federal_info = {
+    "server": "localhost:6001",
+    "session": {
+        "role": "host",
+        "identity": 'server',
+        "local_id": "zhibang-d-014010",
+        "job_id": 'test_job_100'
+    },
+    "federation": {
+        "host": ["zhibang-d-014010"],
+        "guest": ["zhibang-d-014011"],
+        "coordinator": ["zhibang-d-014012"]
+    }
+}
+
+sec_param = {
+    "symmetric_algo": "aes",
+}
+
+algo_param = {
+    'n': 10,
+    'k': 1
+}
+
+protocol = make_protocol(OT_INV, federal_info, sec_param, algo_param)
+```
+
+# 类方法
+大多数协议的类方法为exchange，每个参与方协同执行exchange方法完成协议。exchange函数的输入参数根据不同的协议和角色而变化。有些协议存在不止一个方法，具体的调用方式请参考各协议的api使用文档。下表列出了各协议中不同角色的方法名称。
+
+| 协议名 | role:coordinator | role:guest | role:host| identity:server | identity:client |
+| :----- | :----- | :----- | :----- | :----- | :----- |
+|OT_INV| | | |exchange|exchange|
+|SAL |align, verify|align, verify|align, verify| | |
+|IV_FFS | |exchange|exchange| | |
+|HE_LINEAR_FT |exchange|exchange|exchange| | |
+|HE_OTP_LR_FT1 | |exchange|exchange| | |
+|HE_OTP_LR_FT2 |exchange|exchange|exchange| | |
+|OTP_SA_FT |exchange|exchange|exchange| | |
+|HE_SA_FT |exchange|exchange|exchange| | |
+|HE_LR_FP |exchange|exchange|exchange|
+
+
+每种协议的具体调用方式见相应的README文档：
+* [OT_INV ](../flex/federated_sharing/invisible_inquiry/ot_inv/README.md)
+* [SAL ](../flex/federated_sharing/sample_alignment/secure_alignment/README.md)
+* [IV_FFS ](../flex/federated_preprocessing/federated_feature_selection/iv_ffs/README.md)
+* [HE_LINEAR_FT ](../flex/federated_training/linear_regression/he_linear_ft/README.md)
+* [HE_OTP_LR_FT1 ](../flex/federated_training/logistic_regression/he_otp_lr_ft1/README.md)
+* [HE_OTP_LR_FT2 ](../flex/federated_training/logistic_regression/he_otp_lr_ft2/README.md)
+* [OTP_SA_FT ](../flex/federated_training/secure_aggregation/otp_sa_ft/README.md)
+* [HE_SA_FT ](../flex/federated_training/secure_aggregation/he_sa_ft/README.md)
+* [HE_LR_FP ](../flex/federated_prediction/logistic_regression/he_lr_fp/README.md)