安全多方计算（MPC）从入门到精通：JUGO－IDE及SDK

简介：在上一节《安全多方计算（MPC）从入门到精通：Frutta语言》中，已经介绍了Frutta语言语法相关的内容，在本节中，我们将介绍JUGO－IDE及SDK。
1.什么是JUGO-IDE
　　JUGO-IDE是JUGO技术产品面向开发者提供的用来编写MPC算法的开发工具，结合Frutta谷歌浏览器插件，开发者无需搭建任何环境就可以快速编写、编译、运行和发布算法。
　　通过使用JUGO-IDE，开发者可使用Frutta语言编写算法，并通过JUGO-IDE编译成可在JUGO技术产品上执行的电路文件和java模板文件。
2.支持语言
　　Frutta语言。
　　Frutta作为类C的高级语言，可以将编写的计算逻辑在JUGO-IDE生成电路文件和java模板文件，并在JUGO技术产品中执行计算。
3.开发环境
　　操作系统windows（后续支持linux），chrome浏览器（需先安装Frutta谷歌浏览器插件）
　　第一步，请下载Frutta谷歌浏览器插件的安装包
　　第二步，在Chrome浏览器中启用开发者模式，然后点击按钮“加载已解压的扩展程序”，选择插件所在的文件夹即可。
注意：由于该插件暂未上传Google插件商店，所以只能以开发者模式运行。开启开发者模式，由于是以开发者模式运行该插件的，Chrome浏览器会弹出“请停用以开发者模式运行的扩展程序”的提示，此时点击“取消”才可以继续使用Frutta谷歌浏览器插件。

一、界面
1.启动页
1）JUGO-IDE启动页默认包含一个欢迎页和一个算法工程，开发者可根据需要进行增删。
2）开发者在未登录JUGO技术产品的情况下首次进入JUGO-IDE启动页的时候，即会自动弹出登录弹窗，提供了登录、忘记密码、注册等功能入口。开发者登录后才可以使用JUGO-IDE提供的访问算法库、发布算法的功能。当然，开发者也可以点击“暂不登录”关闭该登录弹窗继续使用MPC-IDE，不会对工程编译等功能造成影响。
3）JUGO-IDE启动时，编辑区默认打开JUGO-IDE欢迎页，该页面中提供了JUGO-IDE、Frutta、JUGO技术产品、MPC的简单介绍和详情页面链接，开发者可以点击“详情”去往详情页面进行深入了解。

2.菜单栏
1）文件管理
　　功能描述：提供“新建工程、新建文件、导入本地文件、导出到本地、保存当前文件、保存所有文件、删除当前文件”等功能。
　　操作示例：

• 新建工程：点击头部“工具栏文件--新建工程”，会弹窗创建算法工程弹窗，开发者输入算法名称后，即在当前文件管理器中新建一个算法工程。
  
• 算法工程目录结构：
• libraries: 引用的算法存放目录；
• bin: 当前算法工程编译成功生成的java模板文件的存放目录；
• Include: 算法工程头文件存放目录；
• Resource: 算法工程源文件存放目录；
• main.wir: 当前算法工程入口文件
  　注意：当前算法工程的编译入口文件为“main.wir”。 如果选中其它文件点击编译，JUGO-IDE会自动定位到当前选中文件所属的算法工程，并编译该算法工程中的“main.wir”。如果需要编译其它文件，需要在“main.wir”中引入该文件后再点击“编译”。
• 新建文件：点击头部“工具栏文件--新建文件”，即在当前工程目录下新建一个Untitled1.wir文件，并自动在编辑区打开。
  　　功能限制：IDE当前文件系统中至少有一个工程。
• 导入本地文件：点击头部工具栏“文件--导入本地文件”，选择某一文件后该文件即被导入进JUGO-IDE文件管理器，并自动在编辑区打开。
  　　功能限制：IDE当前文件系统中至少有一个工程。
• 导出到本地：点击头部工具栏“文件--导出到本地”，会将IDE中当前选中的文件或文件夹导出到本地，文件夹的格式为“文件夹名”.rar，文件的格式和当前选中的文件在IDE中的格式保持一致。
  　　功能限制：需要在IDE中选中文件或文件夹。
• 保存/全部保存：点击头部工具栏“文件--保存”，会保存当前文件；点击头部工具栏“文件--全部保存”，会保存文件管理器中的所有文件；
  　　功能限制：当前窗口中有需要保存的文件
• 删除：点击头部工具栏“文件--删除”，会删除当前编辑区窗口打开的文件；
  　　功能限制：当前有选中的文件
  2）编辑操作
  　　功能描述：提供对当前文件“撤销、恢复、复制、剪切、粘贴、查找、替换、格 式化、在文件中查找、在文件中替换”等常规功能。
  　　操作示例：
  　　在文件中查找/替换：点击头部工具栏“编辑--在文件中查找/替换”，左侧边栏会弹出搜索窗口，实现全局关键字的查找/替换功能。
  　　功能限制：当前编辑区窗口中有打开的文件
  3）帮助
  　　功能描述：提供对操作员的帮助文档。
  　　操作示例：
• 欢迎使用：点击头部工具栏“帮助--欢迎使用”，即会回到JIDE的欢迎页面，该页面中提供了JIDE的简介及使用的大致流程。
• 帮助文档：点击头部工具栏“帮助--帮助文档”，即会跳转到JUGO技术产品的文档中心，文档中心中包含了比较详细的开发流程。
  
  3.工具栏
  1）文件管理
  　　功能描述：控制文件管理器的展开或收起。
  　　操作步骤：文件管理器窗口默认展开，点击左侧工具栏“文件管理 ”控制文件管理器窗口的展开与收起
  
  2）全局搜索
  　　功能描述：提供全局的搜索、替换功能。
  　　操作步骤：
  　　第一步：点击左侧工具栏“搜索”按钮，调出全局搜索功能窗口；
  　　第二步：输入关键字即可即时出现搜索结果，关键字支持区分字母大小写、全字匹配、正则表达式；
  　　第三步：点击搜索结果自动跳转到当前文件；
  　　第四步：替换操作支持单个替换和全部替换，输入替换内容后，可以选择单个替换和全部替换；
  
  3）运行算法
  　　功能描述：对进行编译成功的电路文件进行测试运行。
  　　操作步骤：
  　　第一步：点击左侧工具栏“运行 ”按钮，调出运行算法面板；
  
  　　第二步：如果当前选中的工程没有编译成功，则提示没有数据；
  　　第三步：如果当前选中的工程已经编译成功，则可输入输入项运行该算法；
  　　第四步：运行成功，则会在输出栏提示运行成功并输入运行结果；
  
  　　第五步：运行成功后，即可看到运行结果，格式如“name:value”，”name”即为当前运行的算法代码中的输出变量的名称，”value”为算法代码中输出变量的值。
  4）算法库
  　　功能描述：所有已上传到算法中心的算法，都可在算法库中调用，点击图标进入算法库页面。
  　　操作步骤：
  　　注意：进入算法库需要用户已登录，未登录状态则需要进行登录。
  　　第一步：点击左侧工具栏“算法库 ”按钮，调出算法库面板；算法列表中展示每一个算法的名称、简介和发布者，支持关键字搜索算法；
  　　第二步：点击某一个算法，即跳往该算法的详情界面，开发者可以了解到算法更多的信息，并提供了下载该算法的功能入口。
  　　功能限制：需要开发者登录之后才能访问，如果开发者未登录，IDE会自动弹出登录弹窗提示开发者登录。
  
  3.编辑区
  1）语法检查
  　　功能描述：对当前编辑的文件执行“保存”或者“编译”的操作时，会进行语法检查，错误的地方有红色叉号标识，鼠标悬浮在该行文字上时会显示具体的错误信息。
  
  2）查找/替换
  　　功能描述：输入关键字进行查找/替换，支持区分字母大小写、全字匹配、正则表达式。搜索结果支持上一个、下一个定位操作，替换操作支持单个替换和当前编辑区文件全部替换操作。
  3）多个窗口展示
  　　功能描述：编辑区打开文件过多时，隐藏的部分文件可在右侧“更多文件”入口打开。
  　　操作步骤：点击右侧更多文件“...”标识，即可调出文件列表，其中加黑显示的是已经在编辑区显示的文件，灰色显示的是隐藏的文件；
  
  4）窗口右键操作
  　　功能描述：提供“关闭、关闭其他、关闭右侧、关闭未更改、关闭所有”功能。
  　　操作步骤：选中某一文件名，单击右键即可调出右键操作菜单。
  
  5）文件状态标识
  　　功能描述：每个文件名称左侧出现红色小圆点图标，则表示该文件更改后尚未保存；出现绿色小圆点图标，则表示该文件已保存。
  二、快捷键

三、编写流程
1.文件格式
1) 输入文件格式
　　JUGO-IDE目前支持所有格式文件的编辑，但是编译功能仅限于.wir格式的文件。
2) 输出文件格式
　　在JUGO-IDE中对一个.wir格式的文件进行编译将生成一个.gc格式的电路文件和一个.java格式的java模板文件；.gc文件可通过“导出”按钮导出到本地，.java文件放置于工程“bin”目录，可通过菜单栏或者工具栏中“导出到本地”功能导出到本地，.java文件可在java-sdk中使用。
2.自动补全
　　功能描述：JUGO-IDE编辑区在输入过程中即时显示自动补全提示。
3.编程
　　功能描述：JUGO-IDE编辑区提供查找、替换、代码格式化、字体放大、字体缩小、撤销、恢复等常用功能。
　　流程：编辑--保存--编译
　　错误类型反馈：
1）开发者在执行保存操作时，如果代码中有语法错误，错误的地方行号处有红色叉号标识，鼠标悬浮在该行文字上时会显示具体的错误信息。
2）开发者在执行编译操作时，如果编译出错，IDE输出区域会有红色的错误信息输出，点击错误信息，编辑区会自动打开当前发生错误的文件。
　　措施：开发者在执行保存或者编译时如果有错误信息提示，需要重新编辑文件纠错后再执行保存或者编译操作。

4.运行
　　功能描述：JUGO-IDE编辑区提供“查找、替换、代码格式化、字体放大、字体缩小、撤销、恢复”等常用功能。
　　流程：当前工程编译成功后执行运行
　　错误类型反馈：
1）当前项目没有编译成功

措施：开发者需要先对当前工程进行编译，编译成功后才能运行算法。
2）无效参数

措施：当前项目编译成功后运行的时候，会对输入参数进行类型和范围校验，存在不合法的参数时无法点击“运行”按钮。
5.发布
　　功能限制：
1）需要开发者登录。
2）当前项目编译成功并通过了运行测试。
用途：开发者可将已通过运行测试的算法发布到JUGO技术产品的算法库中，算法库是JUGO技术产品的算法仓库，开发者使用JUGO-IDE发布的算法会生成一个唯一的算法ID，通过这个算法ID可以下载该算法，并通过JUGO-SDK使用该算法。

6.算法库
　　功能限制：需要开发者登录。
　　用途：开发者可以访问到JUGO技术产品的算法中心的所有算法。算法列表中展示每一个算法的名称、简介和发布者，支持关键字搜索算法；点击某一个算法，即跳往该算法的详情界面，开发者可以了解到算法更多的信息，并提供了下载该算法的功能入口。

7.导出
功能描述：开发者可以通过导出功能将JUGO-IDE中当前选中的文件或文件夹导出到本地，文件夹的格式为“文件夹名”.rar，文件的格式和当前选中的文件在IDE中的格式保持一致。
1.什么是JUGO-SDK
　　JUGO-SDK是JUGO技术产品面向开发者提供的安全多方计算应用开发工具包。
　　开发者通过使用JUGO-SDK与其他JUGO技术产品，可以高效快速的开发MPC（安全多方计算）应用。每个集成了SDK的应用将作为计算节点接入到计算网络中。应用调用SDK可以实现安全多方计算以满足业务需求。
　　此文档面向开发者介绍如何使用JUGO-SDK及其相关注意事项。同时，阅读此文档的开发者需要具备分布式系统中间件（Ice）的基础知识——JUGO-SDK使用RPC协议进行数据传输，使用了Ice中的Glacier2进行防火墙穿透。

2.编程语言&开发环境
　　支持语言：JAVA语言。
　　JDK版本：JDK1.8。
　　开发工具：推荐使用 IntelliJ IDEA。
　　开发环境：操作系统window/linux，ICE-3.6
3.调试&运行环境
　　调试环境：由于MPC算法库目前仅支持.so动态库（Linux平台运行），所以开发阶段部分功能可在window上进行调试，完整的计算流程需要在Linux环境上进行。
　　运行环境：目前仅支持运行在Linux环境，推荐：CentOS Linux release 7.2.1511 (Core)。
　　电路文件：后缀格式规定为：.gc

一、集成流程
1、IDE上编写电路算法；
2、编译算法并生成电路文件JAVA包装类；示例查看
3、项目中引入步骤2中的JAVA包装类；
4、集成API，完成应用开发；
二、API列表

三、API详情
1.创建电路实例
　　接口：YourCircuitWrapper circuit=new YourCircuitWrapper();
　　注意：电路文件包装类，仅可实例化一次，建立与代理连接。
　　描述：创建电路实例，并完成链路初始化工作，与JUGO代理服务进行会话连接，后续数据通信都依赖此连接通道进行。
　　参数说明：

返回参数说明：

示例代码：

1. try {
2. YourCircuitWrapper yourCircuit=new YourCircuitWrapper("mycircuitId","admin01","password",NodeCommunicateMode.SERVICE
3. , "ProxyGlacier2/router:tcp -h 192.168.7.167 -p 4502 -t 11000", null, "--Ice.Config=config.conf");
4. } catch (MPCException e) {
5. }
   2.开启计算任务
   　　接口：yourCircuit.doCompute();
   　　注意：调用前请确保成功构建了YourCircuitWrapper实例对象。
   　　描述：通过调用doCompute，可以启动一次计算任务。该接口由任务发起方进行调用，被邀请方无需调用该接口。
   　　参数说明：

　　返回参数说明：

示例代码：

1. try {
2. String[] argsAttach = new String[]{"n=3","m=4"};
3. List<String> takerList = Arrays.asList(new String[]{"admin01","admin02"});
4. List<String> resulReceiverList = Arrays.asList(new String[]{"admin01"});
5. yourCircuit.doCompute("1111", argsAttach, takerList, resulReceiverList);
6. } catch (MPCException e) {
7. e.printStackTrace();
8. }
   3.发起方获取源数据
   　　接口：yourCircuit.setInputCallbackForORG();
   　　注意：此函数用于设置计算发起方的源数据获取方式。
   　　描述：此函数接受一个InputCallback()接口的具体实现, 可自行定义计算源数据的获取逻辑。设置时请注意电路文件定义的数据结构规范，如果是数组则需要保证数组元级及元素个数与预定义的一致。
   　　参数说明：

　　返回参数说明：

示例代码：

1. yourCircuit.setInputCallbackForORG(new InputCallback<Int32[][]>() {
2. @Override
3. public Int32[][] input(String taskId, String algorithmId, String[] args) {
4. return new Int32[2][2];
5. }
6. @Override
7. public void onFailure(Throwable e){
8. // 异常处理
9. }
10. });
    　　说明：
    　　上述示例中假定生成的电路java文件中定义的入参类型为：Int32[][]，一个Int32的二维数组，且元素个数为[2][2]。
    4.收邀方获取源数据
    　　接口：yourCircuit.setInputCallbackForDST();
    　　注意：此函数用于设置受邀发起方的源数据获取方式。
    　　描述：此函数接受一个InputCallback()接口的具体实现, 可自行定义计算源数据的获取逻辑。设置时请注意电路文件定义的数据结构规范，如果是数组则需要保证数组元级及元素个数与预定义的一致。
    　　参数说明：

　　返回参数说明：

示例代码：

1. yourCircuit.setInputCallbackForDST(new InputCallback<Int32[][]>() {
2. @Override
3. public Int32[][] input(String taskId, String algorithmId, String[] args) {
4. return new Int32[3][3];
5. }
6. @Override
7. public void onFailure(Throwable e){
8. // 异常处理
9. }
10. });
    　　说明：
    　　上述示例中假定生成的电路java文件中定义的入参类型为：Int32[][]，一个Int32的二维数组，且元素个数为[3][3]。因此在回调函数中input的返回一定是[3][3]及的多维数组。
    5.处理计算结果
    　　接口：yourCircuit.setOutputCallback();
    　　注意：N/A。
    　　描述：设置一个回调函数，用于处理获取到的结果。该结果返回的数据类型与电路文件算法电路的返回类型一致。
    　　参数说明：

　　返回参数说明

示例代码：

1. yourCirciut.setOutputCallback(new OutputCallback<Int32>(Int32.class) {
2. @Override
3. public void onResult(String taskId, String algorithmId, int resultCode, Int33 result) {
4. // 处理结果
5. }
6. @Override
7. public void onFailure(Throwable e){
8. // 异常处理
9. }
10. }
    　　注意：示例中的数据类型（Int32）由具体电路文件决定。
    6.处理邀请结果
    　　接口：InvitationManager->invite();
    　　注意：此接口提供了默认实现，如需更改则需要在调用doCompute()前重新进行设置。可调用yourCircuit.setInvitationManager();进行更改。
    　　描述：一个接口，并提供回调函数，当节点收到计算邀请后该回调会被触发，可在回调函数中提供业务逻辑来决定是否同意计算邀请。该接口提供了一个默认实现类（DefaultInvitationManager）
    　　参数说明：

　　返回参数说明：

示例代码：

1. yourCircuit.setInvitationManager(new InvitationManager() {
2. @Override
3. public boolean invite(String taskId, String starter, String algorithmId, int numberOfParticipants, List<String> takersList) {
4. // 这里实现业务逻辑
5. return true;
6. }
7. });
   7.获取本地电路文件
   　　接口：CircuitManager -> getLocal();
   　　注意：如需更改则在调用doCompute前重新进行设置。可调用yourCircuit.setCircuitManagerManager();预先设置。
   　　描述：此接口提供了默认实现类(DefaultCircuitManager)。当需要自定义电路文件路径时可重新提供接口实现。JUGO-SDK默认会根据算法ID(algorithmId)去电路仓库进行下载（由JUGO开发服务平台提供）。
   　　参数说明：

　　返回参数说明：

示例代码：

1. // 示例提供了根据不同ID返回不同文件类型的电路文件
2. yourCircuit.setCircuitManager(new CircuitManager() {
3. @Override
4. public String getLocal(String algorithmId) {
5. if(algorithmId.equals("1")){
6. return "/home/juzhen/work2018/jugo/jugompc/circuits-files/adder_32bit.gc";
7. }
8. if(algorithmId.equals("2")){
9. return "/home/juzhen/work2018/jugo/jugompc/circuits-files/AES-expanded.gc";
10. }
11. return "";
12. }
13. });
    四、JUGO-SDK使用步骤
    1.引入JUGO-SDK
    　　SDK仓库地址
    　　Maven

1.    <dependency>
2.    <groupId>com.juzix.jugo</groupId>
3.    <artifactId>mpc-node-sdk</artifactId>
4.    <version>1.1.0-SNATSHOP</version>
5.    </dependency>`

　　Gradle

1. compile "com.juzix.jugo:mpc-node-sdk:1.1.0-SNATSHOP"
   Jar包引用下载

2.算法动态库
　　底层算法逻辑使用c/c++进行编写，JAVA使用JNI进行调用。目前仅提供了Linux环境下的动态库(.so)，因此测试环节需在Linux完成。下载解压后会得到一个libjuzixmpc.so动态库文件，需要更改配置文件mpc-node-config.conf进行配置 。此操作是必须的，否则无法完成计算操作。

3.配置文件创建
　　JUGO-SDK使用默认方式获取电路文件时需要一些配置信息，如自定义实现了CircuitManager，则无需提供配置文件。此处规定，配置文件名为：mpc-node-config.conf，必须在目录config下。配置文件可位于classes源码目录或者${user.dir}工作目录。如果使用IDEA开发工具，则可将配置文件放置在：${project.dir}/src/main/resources/config/mpc-node-config.conf。
　　文件内容如下：

1.    node {
2.         isDebug=false
3.         # 是否使用Glacier2进行消息路由 false 不使用, true 使用
4.         isRouterModel=false
5.    circuit {
6.    # 电路文件下载地址，此处将IP和port更改为实际地址即可
7.    download.url = "http://xxx:port/file_api/file/download?arithmeticId=%s&user=%s"
8.    # 电路文件本地存储目录
9.    local.dirPath = /home/test/developer/jugompc
10.    }
11.    jni {
12.       # jni调用的动态库文件目录
13.       library.path=/home/test/developer/jnilib
14.    }
15.    }

注：完成以上2步操作基本完成了对JUGO-SDK的集成。请务必注意算法库的文件路经配置正确。
4.配置节点为服务节点
　　在启动一个节点的时，可以将节点作为一个服务节点启动。可直接接收对端（计算比较端）的数据，而不需要通过JUGO代理服务回调传输。在调用API-初始化节点（initContext）时，如果参数mode传入SERVER，则必须进行配置操作。如果传入CALLBACK则可忽略此步骤。
　　当节点需要作为服务节点启动时，需提供服务配置文件，并在初始化时通过参数args传入。
　　服务配置文件：config.node-server

1.    # 当前节点作为服务提供的Endpoints信息
2.    NodeServer.Endpoints=tcp -p 12001
3.    Server.Trace=1
4.    Ice.ThreadPool.Server.Size=10
5.    Ice.ThreadPool.Server.SizeMax=10
6.    Ice.ThreadPool.Client.Size=10
7.    Ice.ThreadPool.Client.SizeMax=10

　　注：在创建电路实例中的
args=new String[]{“--Ice.Config=config.node-server”}
5.配置节点Glacier2
　　注意：如果配置文件mpc-node-config中，isRouterModel=false, 则无需启动节点Glacier2，该模式标识仅使用节点直连进行消息传递而不需要Glacier2进行消息路由。
　　Glacier2是ICE特有的应用层防火墙和路由器，提供了安全校验、消息路由和事务管理等功能。这里为了防止网络造成数据传输阻碍，引入Glacier2进行网络穿透。将节点服务放置在Glacier2之后，由Glacier2进行消息接收并路由到目标服务。
　　Glacier2配置文件：config.glacier2-node-server

1.    #Glacier2实例名
2.    Glacier2.InstanceName=NodeGlacier2
3.    # 客户端访问Endpoints信息
4.    Glacier2.Client.Endpoints=tcp -h 0.0.0.0 -p 4503 -t 12000
5.    Glacier2.Server.Endpoints=tcp
6.    # 会话创建服务地址，此处连接到节点服务的EEndpoings
7.    Glacier2.SessionManager=NodeSessionManager:tcp -h 192.168.7.168 -p 12001
8.    # 权限校验服务地址，此处连接到节点服务的Endpoints
9.    Glacier2.PermissionsVerifier=NodePermissionsVerifier:tcp -h 192.168.7.168 -p 12001
10.    Glacier2.SessionTimeout=30
11.    Glacier2.Server.Buffered=0
12.    Glacier2.Client.Buffered=0
13.    IceSSL.Trace.Security=1
14.    Ice.Trace.Network=1
15.    Ice.Warn.Connections=1
16.    Ice.Trace.Protocol=1
17.    Ice.ThreadPool.Server.Size=10
18.    Ice.ThreadPool.Server.SizeMax=10
19.    Ice.ThreadPool.Client.Size=10
20.    Ice.ThreadPool.Client.SizeMax=10

　　注：配置中为基本的Glacier2信息配置，具体含义请参考ICE详细文档查看。
　　启动Glacier2之前请确保本地已安装Ice并可正常使用。
　　启动Glaicer2命令为：
glacier2router --Ice.Config=./config.glacier2-node-server
　　使用Glacier2后，在调用节点初始化（initContext）时的参数jugoEndpoint=NodeGlacier2/router:tcp -h 127.0.0.1 -p 4503 -t 12000。后续再计算过程中对端节点会通过该Endpoints信息直接调用Glacier2进行数据转发路由到目标服务。
五、返回码一览

更多内容可以参考视频：安全多方计算MPC视频课程

原文地址：http://blog.51cto.com/13701316/2136534