互联互通接口标准v1.2.0更新

互联互通API接口规范/1.管理层接口/隐私计算互联互通管理层API.md

@@ -60,7 +60,7 @@
 **文档版本**
 
 ```
-v1.1.0
+v1.2.0
 ```
 
 ## 2 通用报文头规范及公共出参
@@ -381,6 +381,7 @@ x-mprac-token-set：多方资源访问控制的许可凭证
 | ⇥ ⇥ description     | string        |        |        | 数据集描述                                                   |
 | ⇥ ⇥ name            | string        |        | true   | 数据集名称                                                   |
 | ⇥ ⇥ owner           | string        |        | true   | 数据属主（机构 id）                                          |
+| ⇥ ⇥ join_columns | string | |  | 求交任务匹配键 |
 | ⇥ ⇥ column_metas    | array<object> |        |        | 列元数据，与字段排序保持一致。列表查询时可选，明细查询时必选 |
 | ⇥ ⇥ ⇥ name         | string        |        | true   | 字段名/特征名                                                |
 | ⇥ ⇥ ⇥ data_type    | string        |        | true   | 字段类型，枚举值：如 varchar、int、double（参考 SQL）        |
@@ -424,6 +425,7 @@ x-mprac-token-set：多方资源访问控制的许可凭证
 | ⇥ description     | string        |        |        | 数据集描述                                                   |
 | ⇥ name            | string        |        | true   | 数据集名称                                                   |
 | ⇥ owner           | string        |        | true   | 数据属主（机构 id）                                          |
+| ⇥ label_columns | string | |  | 字段列 |
 | ⇥ ⇥ column_metas | array<object> |        | true   | 列元数据，与字段排序保持一致。列表查询时可选，明细查询时必选 |
 | ⇥ ⇥ name         | string        |        | true   | 字段名/特征名                                                |
 | ⇥ ⇥ data_type    | string        |        | true   | 字段类型，枚举值：如 varchar、int、double（参考 SQL）        |

互联互通API接口规范/2.控制层接口/隐私计算互联互通控制层API.md

@@ -48,7 +48,7 @@
 **文档版本**
 
 ```
-v1.1.0
+v1.2.0
 ```
 
 ## 2 通用报文头规范及公共出参
@@ -572,7 +572,7 @@ x-mprac-token-set：  required 多方资源访问控制的许可凭证，用于
 
 ### 3.7 查询作业状态-调度方
 
-> GET /v1/interconn/schedule/job/status_all
+> POST /v1/interconn/schedule/job/status_all
 
 **接口描述**
 

互联互通API接口规范/3.算法组件层接口/隐私计算互联互通算法组件层API.md

@@ -49,7 +49,7 @@
 **文档版本**
 
 ```
-v1.1.0
+v1.2.0
 ```
 
 ## 2 算法组件自描述文件
@@ -577,20 +577,21 @@ x-mprac-token-set：  required 多方资源访问控制的许可凭证，用于
 
 调度层生成存储服务的配置信息，并通过环境变量 env 下发给算法组件层：
 
-1. S3 存储：s3://{host}:{port}?username={username}&password={password}
+1. S3 存储：s3://{host}:{port}?username={username}&password={password}&bucket={bucket_name}
 
 | **字段** | **说明**          |
 | -------- | ----------------- |
 | host     | s3 服务的 ip 地址 |
 | port     | s3 服务的服务端口 |
 | username | s3 服务的用户名   |
 | password | s3 服务的用户密码 |
+| bucket   | s3 服务的桶名称   |
 
 **示例：**
 
-system.storage=s3://192.168.1.1:9000?username=admin&password=123456
+system.storage=s3://192.168.1.1:9000?username=admin&password=123456&bucket=storage
 
-2. HDFS 存储：hdfs://{host}:{port}?username={username}&password={password}
+2. HDFS 存储：hdfs://{host}:{port}?username={username}&password={password}&dir={dir}
 
 | **字段** | **说明**            |
 | -------- | ------------------- |
@@ -601,7 +602,7 @@ system.storage=s3://192.168.1.1:9000?username=admin&password=123456
 
 **示例：**
 
-system.storage=hdfs://192.168.1.1:9000?username=admin&password=123456
+system.storage=hdfs://192.168.1.1:9000?username=admin&password=123456&dir=storage
 
 3. NFS 存储和本地存储：file://XXX//XXX
 
@@ -619,25 +620,25 @@ system.storage=file:///opt/iopy/
 
 数据集 meta：s3://{bucket_name}/{namespace}/{name}/metadata
 
-| **字段**    | **说明**                    |
-| ----------- | --------------------------- |
-| bucket_name | s3 桶名，目前固定为 storage |
-| namespace   | 数据集所属库名              |
-| name        | 数据集名称                  |
-| parition    | 数据集分区序号              |
+| **字段**    | **说明**       |
+| ----------- | -------------- |
+| bucket_name | s3 桶名        |
+| namespace   | 数据集所属库名 |
+| name        | 数据集名称     |
+| parition    | 数据集分区序号 |
 
 2. HDFS 存储：
 
 数据集：hdfs://{dir}/{namespace}/{name}/data_{partition}
 
 数据集 meta：hdfs://{dir}/{namespace}/{name}/metadata
 
-| **字段**  | **说明**                         |
-| --------- | -------------------------------- |
-| dir       | 存储一级目录，目前固定为 storage |
-| namespace | 数据集所属库名                   |
-| name      | 数据集名称                       |
-| parition  | 数据集分区序号                   |
+| **字段**  | **说明**       |
+| --------- | -------------- |
+| dir       | 存储一级目录   |
+| namespace | 数据集所属库名 |
+| name      | 数据集名称     |
+| parition  | 数据集分区序号 |
 
 3. NFS 存储和本地存储：
 

互联互通API接口规范/4.传输层接口/隐私计算互联互通传输层API.md

@@ -15,6 +15,11 @@
       - [3.2.3 快速获取数据接口](#323-快速获取数据接口)
       - [3.2.4 会话释放接口](#324-会话释放接口)
   - [4 传输编程接口（可选）](#4-传输编程接口可选)
+  - [5 传输层序列化规则](#5-传输层序列化规则)
+    - [5.1 南北向接口序列化](#51-南北向接口序列化)
+    - [5.2 东西向接口序列化](#52-东西向接口序列化)
+      - [5.2.1 透传模式](#521-透传模式)
+      - [[5.2.2 封装模式]](#522-封装模式)
 
 
 ## 1 整体框架
@@ -28,7 +33,7 @@
 **文档版本**
 
 ```
-v1.1.0
+v1.2.0
 ```
 
 ## 2 节点间通信接口
@@ -303,3 +308,151 @@ c) 会话释放：释放会话资源，可选。
 ## 4 传输编程接口（可选）
 
 该接口为可选接口，主要涉及算法调用传输 sdk 的具体接口实现，详细内容可以参见[传输相关参考实现](./examples/传输相关参考实现.md)
+
+## 5 传输层序列化规则
+
+传输层序列化分为南北向以及东西向接口，HTTP1.1、GRPC协议实现其一即可
+
+### 5.1 南北向接口序列化
+
+算法模块与传输模块南北向接口集成需按照如下序列化方案
+
+- HTTP序列化
+
+  HTTP协议序列化/反序列化方案可通过头字段Content-Type进行设置，支持列表如下
+
+  > 注：使用protobuf序列化时protobuf格式参考南北向GRPC协议格式
+
+|          Content-Type          | 序列化方式 |
+| :----------------------------: | :--------: |
+|       application/json*        |    json    |
+|    application/x-protobuf*     |  protobuf  |
+|   application/xml、text/xml    |    xml     |
+| application/x-msgpack、msgpack |  msgpack   |
+|       application/x-yaml       |    yaml    |
+|        application/toml        |    toml    |
+|     application/form-data      |    form    |
+
+> *必选
+
+- GRPC序列化
+
+  GRPC协议使用protobuf进行序列化/反序列化，protobuf格式如下
+
+```protobuf
+syntax = "proto3";
+
+package org.ppc.ptp;
+option go_package = "github.com/be-io/mesh/ptp";
+option java_package = "io.bfia.ptp";
+
+// PTP Private transfer protocol
+// 通用报头名称编码，4层无Header以二进制填充到报头，7层以Header传输
+// x-ptp-tech-provider-code:    required 厂商编码
+// x-ptp-trace-id:              required 链路追踪ID
+// x-ptp-token                  required 认证令牌
+// x-ptp-session-id             required 通信会话号，全网唯一
+// x-ptp-target-node-id         required 接收端节点编号，全网唯一
+// x-ptp-target-inst-id         optional 接收端机构编号，全网唯一
+
+message PeekInbound {
+  string topic = 1;                   // optional 会话主题，相同信道具有唯一性，用于同一信道的传输隔离
+}
+
+message PopInbound {
+  string topic = 1;                   // optional 会话主题，相同信道具有唯一性，用于同一信道的传输隔离
+  int32 timeout = 2;                  // optional 阻塞超时时间，默认120s
+}
+
+message PushInbound{
+  string topic = 1;                   // optional 会话主题，相同信道具有唯一性，用于同一信道的传输隔离
+  bytes payload = 2;                  // 二进制报文
+  map<string, string> metadata = 3;   // optional 保留参数，用于扩展性
+}
+
+message ReleaseInbound {
+  string topic = 1;                   // optional 会话主题，相同信道具有唯一性，用于同一信道的传输隔离
+  int32 timeout = 2;                  // optional 阻塞超时时间，默认120s
+}
+
+message TransportOutbound {
+  map<string, string>  metadata = 1;  // 可选，预留扩展，Dict，序列化协议由通信层统一实现
+  bytes payload = 2;                  // 二进制报文
+  string code = 3;                    // 状态码
+  string message = 4;                 // 状态说明
+}
+
+service PrivateTransferTransport {
+  rpc peek (PeekInbound) returns (TransportOutbound);
+  rpc pop (PopInbound) returns (TransportOutbound);
+  rpc push (PushInbound) returns (TransportOutbound);
+  rpc release (ReleaseInbound) returns (TransportOutbound);
+}
+```
+
+### 5.2 东西向接口序列化
+
+传输模块东西向接口序列化有透传模式和封装模式两种方式，通过头字段x-ptp-version进行限定
+
+#### 5.2.1 透传模式
+
+头字段设置x-ptp-version=1时东西向接口为透传模式，传输模块直接透传南北向接口收到的消息给合作方东西向接口，不做任何额外处理
+
+#### 5.2.2 封装模式
+
+头字段x-ptp-version不为1或者未包含该字段时，东西向接口为封装模式，传输模块对南北向接口接收到的消息进行二次序列化后转发给合作方东西向接口，该模式可兼容v1.1.0及之前版本标准的传输模块
+
++ HTTP序列化
+
+  HTTP序列化/反序列化方案与南北向HTTP序列化方式保持一致
+
+  > 注：使用protobuf序列化时protobuf格式参考东西向GRPC协议protobuf格式
+
++ GRPC序列化
+
+  GRPC协议使用protobuf进行序列化/反序列化，protobuf格式如下
+
+```protobuf
+syntax = "proto3";
+
+package org.ppc.ptp;
+option go_package = "github.com/be-io/mesh/ptp";
+option java_package = "io.bfia.ptp";
+
+// PTP Private transfer protocol
+// 通用报头名称编码，4层无Header以二进制填充到报头，7层以Header传输
+// x-ptp-version             required 协议版本
+// x-ptp-tech-provider-code  required 厂商编码
+// x-ptp-trace-id            required 链路追踪ID
+// x-ptp-token               required 认证令牌
+// x-ptp-uri                 required 互联互通资源定位符，为跨节点实际请求的资源路径，用于兼容多协议
+// x-ptp-source-node-id      required 发送端节点编号
+// x-ptp-target-node-id      required 接收端节点编号
+// x-ptp-source-inst-id      required 发送端机构编号
+// x-ptp-target-inst-id      required 接收端机构编号
+// x-ptp-session-id          required 通信会话号，全网唯一
+
+// 通信传输层输入报文编码
+message Inbound {
+  map<string, string>  metadata = 1;   // 报头，可选，预留扩展，Dict，序列化协议由通信层统一实现
+  bytes payload = 2;                   // 报文，上层通信内容承载，序列化协议由上层基于SPI可插拔
+}
+
+// 通信传输层输出报文编码
+message Outbound {
+  map<string, string>  metadata = 1;  // 报头，可选，预留扩展，Dict，序列化协议由通信层统一实现
+  bytes payload = 2;                  // 报文，上层通信内容承载，序列化协议由上层基于SPI可插拔
+  string code = 3;                    // 状态码
+  string message = 4;                 // 状态说明
+}
+
+// 互联互通如果使用异步传输协议作为标准参考，Header会复用metadata传输互联互通协议报头，且metadata中会传输异步场景下的消息相关属性
+// 互联互通如果使用其他协议作为参考标准，Header会复用metadata传输互联互通协议报头
+// 互联互通如果使用GRPC作为参考标准，Header会复用HTTP2的报头传输互联互通协议报头
+
+service PrivateTransferProtocol {
+  rpc transport (stream Inbound) returns (stream Outbound);
+  rpc invoke (Inbound) returns (Outbound);
+}
+```
+

互联互通API接口规范/5.开放算法协议/examples/开放算法协议ECDH-PSI算法实现示例.md

@@ -1,4 +1,5 @@
 目前已经针对ECDH-PSI协议部分，隐语社区进行了开源实现，相关实现代码见：
-https://github.com/secretflow/psi/blob/main/psi/ecdh/ecdh_psi.cc
+- 握手协议： https://github.com/secretflow/interconnection-impl/blob/main/ic_impl/algo/psi/v2/psi_handler_v2.cc
+- 算法实际运行：https://github.com/secretflow/psi/blob/main/psi/psi/core/ecdh_psi.cc
 
 该实现结果已与洞见，华控，工商银行等公司等完成联调互通的实践。

互联互通API接口规范/5.开放算法协议/隐私计算互联互通开放算法协议.md

@@ -10,7 +10,6 @@
     - [2.2 算法握手响应](#22-算法握手响应)
       - [2.2.1 接口描述](#221-接口描述)
       - [2.2.2 消息定义](#222-消息定义)
-      - [](#)
       - [2.2.3 请求参数](#223-请求参数)
     - [2.3 算法运行数据](#23-算法运行数据)
       - [2.3.1 接口描述](#231-接口描述)
@@ -50,7 +49,7 @@ ECDH-PSI 算法整体框架如下图所示，共包括五个步骤：
 **文档版本**
 
 ```
-v1.1.0
+v1.2.0
 ```
 
 ## 2 算法层接口

互联互通API接口规范/6.TEE统一远程证明协议/README.md

@@ -9,7 +9,7 @@
 1. 《隐私计算互联互通 TEE 统一远程证明 API》：提供 TEE 互联互通统一远程证明的统一证明服务接口实现参考。[隐私计算互联互通 TEE 统一远程证明 API](./隐私计算互联互通TEE统一远程证明API.md)
 2. 《隐私计算互联互通 TEE 统一远程证明规范》：提供 TEE 互联互通统一远程证明模型、统一远程证明报告的接口、报告格式、校验规则、基于远程证明的安全通道建立流程、TEE 应用数据统一封装格式、TEE 应用和系统层面互联互通要求等参考。[隐私计算互联互通 TEE 统一远程证明规范](./隐私计算互联互通TEE统一远程证明指引.md)
 
-开发者可以通过参考《隐私计算互联互通 TEE 统一远程证明 API》实现《隐私计算互联互通 TEE 统一远程证明规范》文档中的“中心化的远程证明代理验证服务”，通过统一验证服务接口实现异构 TEE 的互联互通。
+开发者可以通过参考《隐私计算互联互通可信执行环境（TEE）统一远程证明API》实现《隐私计算互联互通可信执行环境（TEE）统一远程证明对接指引》文档中的“中心化的远程证明代理验证服务”，通过统一验证服务接口实现异构 TEE 的互联互通。
 
 ## 联系人信息
 

互联互通集成对接指引/互联互通集成对接指引.md

@@ -143,6 +143,7 @@ DAG 与 conf 规范详见控制层，具体参见 3.1.2.1 节。
 
 管理层需要同步适配控制层，对流程中的组件编排和作业的参数配置这两个具体计算执行时依赖的静态描述信息进行统一规范，支撑数据平面对计算资源进行统一调度。
 
+
 <div align="center">
     <img src="./figure/管理面关系图.png">
 </div>
@@ -1328,7 +1329,7 @@ s3.Object(bucket_name="storage", key="{}-{}".format(namespace, name))
 ```yaml
 -env:
   name: system.storage
-  value: s3://IP:port?username=XXX&password=XXX
+  value: s3://IP:port?username=XXX&password=XXX&bucket=XXX
 ```
 
 ```python
@@ -1510,7 +1511,7 @@ x-ptp-target-node-id         required 接收端节点编号，全网唯一
 x-ptp-source-inst-id         optional 发送端机构编号，全网唯一
 x-ptp-target-inst-id         optional 接收端机构编号，全网唯一
 请求体:
-透传二进制报文，不做特殊处理
+根据头字段x-ptp-version以及Content-Type进行序列化处理
 
 响应体:
 透传二进制报文，不做特殊处理
@@ -1733,4 +1734,6 @@ SDK 需要配置一个环境变量或启动参数 `MESH_ADDRESS`，该地址为
 - [HTTP1.x-传输模块到传输模块接口.swagger.json](https://github.com/be-io/mesh/blob/master/specifications/api/mesh.x.swagger.json)
 - [HTTP1.x-容器到传输模块接口.swagger.json](https://github.com/be-io/mesh/blob/master/specifications/api/mesh.y.swagger.json)
 
-## 附录
+# 附录
+
+暂无