10. 隐私计算使用指南

10.1. 环境部署

10.1.1. TEE环境构建

TEE环境构建主要包括安装 Intel(R) SGX driver、Intel(R) SGX SDK和Intel(R) SGX Platform Software (PSW)。环境构建请参考文档:https://github.com/intel/linux-sgx#build-and-install-the-intelr-sgx-driver

10.1.2. 下载Chainmaker-tee代码

git clone -b v2.0.0 https://git.chainmaker.org.cn/chainmaker/chainmaker-tee.git

10.1.3. 代码编译

10.1.3.1. 编译Enclave

10.1.3.1.1. 根据Enclave.edl生成Enclave_t.c等文件
cd Enclave
/opt/intel/sgxsdk/bin/x64/sgx_edger8r --untrusted ./Enclave.edl --search-path . --search-path /opt/intel/sgxsdk/include --search-path ./openssl/include

/opt/intel/sgxsdk/bin/x64/sgx_edger8r --trusted ./Enclave.edl --search-path . --search-path /opt/intel/sgxsdk/include --search-path ./openssl/include
10.1.3.1.2. 复制Enclave_u.c和Enclave_u.h到gateway/bridge下
手动删除 Enclave_u.h 中的第8行 :  #include "sgx_edger8r.h"
cp Enclave_u.* ../gateway/bridge
cp user_types.* ../gateway/bridge
10.1.3.1.3. 生成cgo代码
cd ../gateway/bridge
go tool cgo bridge.go
10.1.3.1.4. 编译Enclave
cd ../../Enclave
cmake .
make clean
make
10.1.3.1.5. 对libenclave.so进行签名
/opt/intel/sgxsdk/bin/x64/sgx_sign sign -key ./Enclave_private.pem -enclave libenclave.so -out ./enclave.signed.so -config ./Enclave.config.xml

10.1.3.2. 编译隐私计算网关

cd ../gateway
go build

10.1.3.3. 隐私计算网关配置config.yml

# 服务配置信息
settings:
   # web服务配置信息
   application:
      domain: localhost:9090
      host: 0.0.0.0
      ishttps: false # 是否启用https
      name: sgx      # 服务名称
      port: "8081"   # 服务端口号
      concurrency: 10  # 最大并发数
   # SDK客户端配置信息
   config:
      capaths: # 根证书路径,支持多个
         - cert/ca
      chainid: chain1  # 链ID
      conncnt: 1  # 节点连接数
      nodeaddr: 127.0.0.1:12301  # 节点地址,格式:127.0.0.1:12301
      orgid: wx-org1.chainmaker.org # 归属组织
      tlshostname: consensus1.tls.wx-org1.chainmaker.org  # TLS Hostname
      usercttpath: cert/client1.tls.crt  # 客户端用户私钥路径
      userkeypath: cert/client1.tls.key  # 客户端用户证书
   # 日志配置信息
   log:
      compress: 1  # 是否使用gzip压缩,默认不压缩
      level: debug # 日志等级,默认Info
      localtime: 1  # 日志时间戳是否为本地时间戳,默认UTC时间
      maxage: 30 #  最长保存天数,默认不删除
      maxbackups: 300 # 最多备份几个
      maxsize: 1024 # 日志文件大小,默认100M
      path: ./logs/gateway.log # 日志文件名
   # https 配置信息
   ssl:
      key: keystring  # 证书key
      pem: temp/pem.pem # 证书

10.1.4. 环境初始化

  1. 首次运行网关程序时,会导出Enclave可信区证明report文件(out_report.dat)以及证书请求CSR文件(out_csr.pem)

  2. 可参考SDK的使用方法,或使用以下CMC命令调用系统合约将步骤1得到的report信息上链

cmc tee upload_report \
--sdk-conf-path={./testdata/sdk_config.yml(SDK配置文件路径)} \
--report={report路径}
  1. 与上一步骤相似的,可参考SDK的使用方法,或使用以下CMC命令调用系统合约将第三方CA的签名根证书上链

cmc tee upload_ca_cert \
--sdk-conf-path={./testdata/sdk_config.yml(SDK配置文件路径)} \
--ca_cert={根证书地址}
  1. 使用步骤1得到的CSR文件在第三方CA处申请签发TEE证书

  2. 将通过步骤4签发的TEE证书以PEM格式存于文件(in_teecert.pem)并放在网关程序目录下

  3. 重新运行网关程序后会自动校验和加载TEE证书

备注:若Enclave代码版本发生变化,需要再次执行步骤2将更新过的report信息重新上链

10.2. 隐私计算网关接口

网关是用户调用隐私合约的入口,当前使用http接口方式进行调用。网关提供的接口主要包括远程证明、部署合约和调用合约三个接口。所有接口的请求method均使用post方式,参数使用json格式。描述如下:

10.2.1. 部署合约接口

接口地址:http://x.x.x.x:port/private/deploy,其中x.x.x.x:port为服务地址,用户可以在配置里指定。

请求参数使用go语言描述如下:

// PrivateDeployRequest is the struct of private deploy request args, it will be serialized by json when sending request
type PrivateDeployRequest struct {
    // SignPair include multi sign pairs
    SignPair []*SignInfo           `protobuf:"bytes,1,rep,name=sign_pair,json=signPair,proto3" json:"sign_pair,omitempty"`
    // Payload is the request payload, also the content of generating signatures
    Payload  *PrivateDeployPayload `protobuf:"bytes,2,opt,name=payload,proto3" json:"payload,omitempty"`
}

// SignInfo is one pair of signature and a cert
type SignInfo struct {
  // ClientSign is the signature of payload
	ClientSign string `protobuf:"bytes,1,opt,name=client_sign,json=clientSign,proto3" json:"client_sign,omitempty"`
  // Cert is the certification used to verify the ClientSign
	Cert       string `protobuf:"bytes,2,opt,name=cert,proto3" json:"cert,omitempty"`
}

type PrivateDeployPayload struct {
  // CodeBytes is the the codes of contract
	CodeBytes string `protobuf:"bytes,1,opt,name=code_bytes,json=codeBytes,proto3" json:"code_bytes,omitempty"`
	// PrivateRlpData is the deploy args which is packed by abi
	PrivateRlpData  string   `protobuf:"bytes,2,opt,name=private_rlp_data,json=privateRlpData,proto3" json:"private_rlp_data,omitempty"`
  // Passwd is the encrypted key which is encrypted by Enclave's public key
	Passwd          string   `protobuf:"bytes,3,opt,name=passwd,proto3" json:"passwd,omitempty"`
  // SigAlgo is a reserved field and not used now
  SigAlgo         string   `protobuf:"bytes,4,opt,name=sig_algo,json=sigAlgo,proto3" json:"sig_algo,omitempty"`
  // ContractName is the name of deploying contract
	ContractName    string   `protobuf:"bytes,5,opt,name=contract_name,json=contractName,proto3" json:"contract_name,omitempty"`
  // ContractVersion is the version of deploying contract
	ContractVersion string   `protobuf:"bytes,6,opt,name=contract_version,json=contractVersion,proto3" json:"contract_version,omitempty"`
  // CodeHash is the hash value(sha256) of CodeBytes, it should be hex bytes of hash
	CodeHash        string   `protobuf:"bytes,7,opt,name=code_hash,json=codeHash,proto3" json:"code_hash,omitempty"`
  // OrgId is a slice of orgs which is coordinate with SignInfo's Cert
	OrgId           []string `protobuf:"bytes,8,rep,name=org_id,json=orgId,proto3" json:"org_id,omitempty"` 
	// TimeStamp is the time when the request is built
	TimeStamp       string   `protobuf:"bytes,9,opt,name=time_stamp,json=timeStamp,proto3" json:"time_stamp,omitempty"`
}

10.2.2. 执行隐私计算接口

接口地址:http://x.x.x.x:port/private/compute,其中x.x.x.x:port为服务地址,用户可以在配置里指定。

请求参数使用go语言描述如下:

// PrivateComputeRequest is the struct of private compute request args, it will be serialized by json when sending request
type PrivateComputeRequest struct {
   // SignPair include multi sign pairs
   SignPair []*SignInfo `protobuf:"bytes,1,rep,name=sign_pair,json=signPair,proto3" json:"sign_pair,omitempty"`
   // Payload is the request payload, also the content of generating signatures
   Payload  *Payload    `protobuf:"bytes,2,opt,name=payload,proto3" json:"payload,omitempty"`
}

// SignInfo is one pair of signature and a cert
type SignInfo struct {
  // ClientSign is the signature of payload
	ClientSign string `protobuf:"bytes,1,opt,name=client_sign,json=clientSign,proto3" json:"client_sign,omitempty"`
  // Cert is the certification used to verify the ClientSign
	Cert       string `protobuf:"bytes,2,opt,name=cert,proto3" json:"cert,omitempty"`
}


type PrivateComputePayload struct {
  // PrivateRlpData is the compute args which is packed by abi
	PrivateRlpData string   `protobuf:"bytes,1,opt,name=private_rlp_data,json=privateRlpData,proto3" json:"private_rlp_data,omitempty"`
  // Passwd is the encrypted key which is encrypted by Enclave's public key
	Passwd         string   `protobuf:"bytes,2,opt,name=passwd,proto3" json:"passwd,omitempty"`
  // SigAlgo is a reserved field and not used now
	SigAlgo        string   `protobuf:"bytes,3,opt,name=sig_algo,json=sigAlgo,proto3" json:"sig_algo,omitempty"`
  // ContractName is the name of deploying contract
	ContractName   string   `protobuf:"bytes,4,opt,name=contract_name,json=contractName,proto3" json:"contract_name,omitempty"`
  // CodeHash is the hash value(sha256) of CodeBytes, it should be hex bytes of hash
	CodeHash       string   `protobuf:"bytes,5,opt,name=code_hash,json=codeHash,proto3" json:"code_hash,omitempty"`
  // OrgId is a slice of orgs which is coordinate with SignInfo's Cert
	OrgId          []string `protobuf:"bytes,6,rep,name=org_id,json=orgId,proto3" json:"org_id,omitempty"`
  // TimeStamp is the time when the request is built
  TimeStamp      string   `protobuf:"bytes,7,opt,name=time_stamp,json=timeStamp,proto3" json:"time_stamp,omitempty"`
}

10.2.3. 远程证明接口

接口地址:http://x.x.x.x:port/private/remote_attestation,其中x.x.x.x:port为服务地址,用户可以在配置里指定。

请求参数使用go语言描述如下:

// RemoteAttestationRequest is the struct of remote attestation request args, it will be serialized by json when sending request
type RemoteAttestationRequest struct {
    // SignPair include multi sign pairs
    SignPair []*SignInfo               `protobuf:"bytes,1,rep,name=sign_pair,json=signPair,proto3" json:"sign_pair,omitempty"`
    // Payload is the request payload, also the content of generating signatures
    Payload  *RemoteAttestationPayload `protobuf:"bytes,2,opt,name=payload,proto3" json:"payload,omitempty"`
}

type RemoteAttestationRequestPayload struct {
   // Challenge is a random data to chanllege the sgx environmet
   Challenge string   `protobuf:"bytes,1,opt,name=challenge,proto3" json:"challenge,omitempty"`
   // OrgId is the orgnization of Cert
   OrgId     []string `protobuf:"bytes,2,rep,name=org_id,json=orgId,proto3" json:"org_id,omitempty"`
}

10.3. 示例参考

10.3.1. 远程证明示例

请参考chainmaker-sgx项目下gateway/tools/test_remote_attestation

10.3.2. 隐私合约部署

请参考chainmaker-sgx项目下gateway/tools/test_tee的call_deploy

10.3.3. 隐私合约调用

请参考chainmaker-sgx项目下gateway/tools/test_tee的call_tee

10.4. 附录——推荐的支持隐私合约的服务器CPU型号

CPU序列号 型号及描述 SGX Enclave最大预留内存
6354 Ice Lake SP XCC Intel Xeon Gold 6345 18c 205W 3.0GHz 64GB
8360Y Ice Lake SP XCC Intel Xeon Platinum 8360Y 36c 250W 2.4GHz 64GB
6348 Ice Lake SP XCC Intel Xeon Gold 6348 28c 235W 2.6GHz 64GB
8380 Ice Lake SP XCC Intel Xeon 8380 40c 270W 2.3GHz 512GB
8368 Ice Lake SP XCC Intel Xeon Platinum 8368 38c 270W 2.4GHz 512GB
8368Q Ice Lake SP XCC Intel Xeon Platinum 8368Q 38c 270W 2.6GHz (liquid cooled) 512GB
8358 Ice Lake SP XCC Intel Xeon Platinum 8358 32c 250W 2.6GHz 64GB
8358P Ice Lake SP XCC Intel Xeon Platinum 8358P 32c 240W 2.6GHz 8GB
8352V Ice Lake SP XCC Intel Xeon Platinum 8352V 36c 195W 2.1GHz 8GB
8351N Ice Lake SP XCC Intel Xeon Platinum 8351N 36c 225W 2.4GHz 64GB
6314U Ice Lake SP XCC Intel Xeon Gold 6314U 32c 205W 2.3GHz 64GB
6338 Ice Lake SP XCC Intel Xeon Gold 6338 32c 205W 2.0GHz 64GB
6338N Ice Lake SP XCC Intel Xeon Gold 6338N 32c 185W 2.2GHz 64GB
8352Y Ice Lake SP XCC Intel Xeon Platinum 8352Y 32c 205W 2.2GHz 64GB
8352S Ice Lake SP XCC Intel Xeon Platinum 8352S 32c 205W 2.2GHz 512GB
6330 Ice Lake SP XCC Intel Xeon Gold 6330 28c 205W 2.0GHz 64GB
6330N Ice Lake SP XCC Intel Xeon Gold 6330N 28c 165W 2.2GHz 64GB
6346 Ice Lake SP XCC Intel Xeon Gold 6346 16c 205W 3.1GHz 64GB