在Fabric中使用私有数据

官方文档：Using Private Data in Fabric

This tutorial will demonstrate the use of Private Data Collections (PDC) to provide storage and retrieval of private data on the blockchain network for authorized peers of organizations. The collection is specified using a collection definition file containing the policies governing that collection.

本教程将演示如何使用私有数据集（PDC）为组织的有权限的peer在区块链网络上提供私有数据的存储和检索。使用包含定义该PDC策略的集合定义文件来管理PDC。

The information in this tutorial assumes knowledge of private data stores and their use cases. For more information, check out Private data.

本教程中的信息假定您了解私有数据存储及其使用案例。有关更多信息，请查看Private data。

The tutorial will take you through the following steps to practice defining, configuring and using private data with Fabric:

本教程将指导您完成以下步骤，以练习定义、配置和使用Fabric私有数据：

1. Asset transfer private data sample use case 资产转移私有数据样例使用方法
2. Build a collection definition JSON file 构建一个集合定义JSON文件
3. Read and Write private data using chaincode APIs 使用chaincode API读写私有数据
4. Deploy the private data smart contract to the channel 部署私有数据智能合约到通道
5. Register identities 注册身份
6. Create an asset in private data 在私有数据集中创建资产
7. Query the private data as an authorized peer 通过有权限的peer查询私有数据
8. Query the private data as an unauthorized peer 通过没有权限的peer查询私有数据
9. Transfer the Asset 交易在私有数据集中的资产
10. Purge Private Data 清除私有数据
11. Using indexes with private data 对私有数据使用索引
12. Additional resources 额外资源

This tutorial will deploy the asset transfer private data sample to the Fabric test network to demonstrate how to create, deploy, and use a collection of private data. You should have completed the task Install Samples, Binaries, and Docker Images.

这个教程会部署 asset transfer private data sample到Fabric的测试网络来演示如何创建、部署以及使用PDC。

Asset transfer private data sample use case（资产转移私有数据样例使用方法）

This sample demonstrates the use of three private data collections, assetCollection, Org1MSPPrivateCollection & Org2MSPPrivateCollection to transfer an asset between Org1 and Org2, using following use case:

这个样例使用以下用例演示使用三个私有数据集（PDC）来在Org1和Org2组织之间交易资产；这三个PDC为：assetCollection, Org1MSPPrivateCollection & Org2MSPPrivateCollection 。

A member of Org1 creates a new asset, henceforth referred as owner. The public details of the asset, including the identity of the owner, are stored in the private data collection named assetCollection. The asset is also created with an appraised value supplied by the owner. The appraised value is used by each participant to agree to the transfer of the asset, and is only stored in owner organization’s collection. In our case, the initial appraisal value agreed by the owner is stored in the Org1MSPPrivateCollection.

组织Org1的一个成员创建一个新的资产，并拥有这个资产。公共的资产详情，包括拥有者的身份被存储在称作 assetCollection的私有数据集中。资产所有者也会为这个资产创建一个评估价值，通道上的每个参与者都使用这个评估价值来同意资产转让，并且它仅存储在所有者组织的集合中。在我们的案例中，所有者确认的初始评估值存储在Org1MSPPrivateCollection中。

To purchase the asset, the buyer needs to agree to the same appraised value as the asset owner. In this step, the buyer (a member of Org2) creates an agreement to trade and agree to an appraisal value using smart contract function 'AgreeToTransfer'. This value is stored in Org2MSPPrivateCollection collection. Now, the asset owner can transfer the asset to the buyer using smart contract function 'TransferAsset'. The 'TransferAsset' function uses the hash on the channel ledger to confirm that the owner and the buyer have agreed to the same appraised value before transferring the asset.

要购买资产，购买者需要同意与资产所有者相同的评估价值。在此步骤中，买方（Org2的成员）使用智能合约的“AgreeToTransfer”方法来创建交易协议并同意评估价值。此值存储在Org2MSPPrivateCollection集合中。现在资产的拥有者可以通过智能合约中的'TransferAsset'方法来交易资产了。 'TransferAsset' 方法在转让资产之前先使用通道账本上的hash来验证买卖双方已经对相同的评估价格达成了一致。

Before we go through the transfer scenario, we will discuss how organizations can use private data collections in Fabric.

在此之前，我们将讨论组织如何在Fabric中使用私有数据集合。

Build a collection definition JSON file（构建一个集合定义JSON文件）

Before a set of organizations can transact using private data, all organizations on channel need to build a collection definition file that defines the private data collections associated with each chaincode. Data that is stored in a private data collection is only distributed to the peers of certain organizations instead of all members of the channel. The collection definition file describes all of the private data collections that organizations can read and write to from a chaincode.

在一组组织可以使用私有数据进行交易之前，通道上的所有组织需要构建一个集合定义文件，这个文件定义与每个链码关联的私有数据集合。存储在私有数据集合中的数据仅分发给相同组织的peer节点，而不是分发给通道的所有成员。集合定义文件描述了组织可以通过链码读写的所有私有数据集。

Each collection is defined by the following properties:

• name: Name of the collection.
• policy: Defines the organization peers allowed to persist the collection data.
• requiredPeerCount: Number of peers required to disseminate the private data as a condition of the endorsement of the chaincode
• maxPeerCount: For data redundancy purposes, the number of other peers that the current endorsing peer will attempt to distribute the data to. If an endorsing peer goes down, these other peers are available at commit time if there are requests to pull the private data.
• blockToLive: For very sensitive information such as pricing or personal information, this value represents how long the data should live on the private database in terms of blocks. The data will live for this specified number of blocks on the private database and after that it will get purged, making this data obsolete from the network. To keep private data indefinitely, that is, to never purge private data, set the blockToLive property to 0.
• memberOnlyRead: a value of true indicates that peers automatically enforce that only clients belonging to one of the collection member organizations are allowed read access to private data.
• memberOnlyWrite: a value of true indicates that peers automatically enforce that only clients belonging to one of the collection member organizations are allowed write access to private data.
• endorsementPolicy: defines the endorsement policy that needs to be met in order to write to the private data collection. The collection level endorsement policy overrides to chaincode level policy. For more information on building a policy definition refer to the Endorsement policies topic.

所有的集合都是用下面的属性来定义：

• name: 集合名称
• policy: 定义允许持久化集合数据的组织的peer节点。
• requiredPeerCount: 传播私有数据所需的peer数目，以作为对链码的认可
• maxPeerCount: 为了数据冗余，当前合法peer将尝试向其分发数据的其他peer的数量。如果一个合法的peer挂了，如果有请求拉私有数据的请求，则这些其他peer在提交时可用。
• blockToLive: 对于如价格或个人信息这类非常敏感的信息，此值表示数据应在私有数据库的块上保存的时间。数据将在私有数据库块上保留指定的时间，然后清除，使该数据从网络上过时。要无限期保留私有数据，即从不清除私有数据，请将blockToLive属性设置为0。
• memberOnlyRead: 值为true表示peer节点自动强制只有属于集合成员组织的客户端才允许读取私有数据。
• memberOnlyWrite:值为true表示peer节点自动强制只有属于集合成员组织的客户端才允许写入私有数据。
• endorsementPolicy: 定义了写入私有数据集合需要满足的认可策略。集合级别的背书策略会覆盖chaincode级别的策略。有关构建策略定义的更多信息，请参考 Endorsement policies主题。

The same collection definition file needs to be deployed by all organizations that use the chaincode, even if the organization does not belong to any collections. In addition to the collections that are explicitly defined in a collection file, each organization has access to an implicit collection on their peers that can only be read by their organization. For an example that uses implicit data collections, see the Secured asset transfer in Fabric.

所有使用同一个chaincode的组织都要部署相同的集合定义文件，即使这个组织不属于任何集合。除了在集合文件中显式定义的集合之外，每个组织都可以访问其peer节点上的隐式集合，这些隐式集合只能由其组织读取。使用隐式数据集的例子可以看Secured asset transfer in Fabric。

The asset transfer private data example contains a collections_config.json file that defines three private data collection definitions: assetCollection, Org1MSPPrivateCollection, and Org2MSPPrivateCollection.

资产转移私有数据的示例包含一个collections_config.json文件，该文件定义了三个私有数据集合定义：assetCollection, Org1MSPPrivateCollection, and Org2MSPPrivateCollection。

// collections_config.json

[
   {
   "name": "assetCollection",
   "policy": "OR('Org1MSP.member', 'Org2MSP.member')",
   "requiredPeerCount": 1,
   "maxPeerCount": 1,
   "blockToLive":1000000,
   "memberOnlyRead": true,
   "memberOnlyWrite": true
   },
   {
   "name": "Org1MSPPrivateCollection",
   "policy": "OR('Org1MSP.member')",
   "requiredPeerCount": 0,
   "maxPeerCount": 1,
   "blockToLive":3,
   "memberOnlyRead": true,
   "memberOnlyWrite": false,
   "endorsementPolicy": {
       "signaturePolicy": "OR('Org1MSP.member')"
   }
   },
   {
   "name": "Org2MSPPrivateCollection",
   "policy": "OR('Org2MSP.member')",
   "requiredPeerCount": 0,
   "maxPeerCount": 1,
   "blockToLive":3,
   "memberOnlyRead": true,
   "memberOnlyWrite": false,
   "endorsementPolicy": {
       "signaturePolicy": "OR('Org2MSP.member')"
   }
   }
]

The policy property in the assetCollection definition specifies that both Org1 and Org2 can store the collection on their peers. The memberOnlyRead and memberOnlyWrite parameters are used to specify that only Org1 and Org2 clients can read and write to this collection.

assetCollection定义中的policy属性指定Org1和Org2都可以在其peer节点上存储集合。 memberOnlyRead 和 memberOnlyWrite 参数被用于指定只有Org1和Org2的客户端可以读写这个集合。

The Org1MSPPrivateCollection collection allows only peers of Org1 to have the private data in their private database, while the Org2MSPPrivateCollection collection can only be stored by the peers of Org2. The endorsementPolicy parameter is used to create a collection specific endorsement policy. Each update to Org1MSPPrivateCollection or Org2MSPPrivateCollection needs to be endorsed by the organization that stores the collection on their peers. We will see how these collections are used to transfer the asset in the course of the tutorial.

Org1MSPPrivateCollection 集合只允许Org1的peer节点在他们的私有数据库中拥有私有数据，而Org2MSPPrivateCollection集合只能由Org2的peer节点存储。 endorsementPolicy 参数用于创建特定集合的认可策略。对Org1MSPPrivateCollection或Org2MSPPrivateCollection的每次更新都需要由将集合存储在其peer节点的组织认可。在本教程中，我们将了解如何使用这些集合来转移资产。

This collection definition file is deployed when the chaincode definition is committed to the channel using the peer lifecycle chaincode commit command. More details on this process are provided in Section 3 below.

这个集合定义文件是在使用peer lifecycle chaincode commit command把链码定义提交到通道时被部署的。

Read and Write private data using chaincode APIs（使用chaincode API读写私有数据）

The next step in understanding how to privatize data on a channel is to build the data definition in the chaincode. The asset transfer private data sample divides the private data into three separate data definitions according to how the data will be accessed.

下一步是了解如何在链码中建立数据定义来对通道上的数据进行私有化。资产转移私有数据实例根据访问数据的方式将私有数据分为三个单独的数据定义。

// Peers in Org1 and Org2 will have this private data in a side database
type Asset struct {
       Type  string `json:"objectType"` //Type is used to distinguish the various types of objects in state database
       ID    string `json:"assetID"`
       Color string `json:"color"`
       Size  int    `json:"size"`
       Owner string `json:"owner"`
}

// AssetPrivateDetails describes details that are private to owners

// Only peers in Org1 will have this private data in a side database
type AssetPrivateDetails struct {
       ID             string `json:"assetID"`
       AppraisedValue int    `json:"appraisedValue"`
}

// Only peers in Org2 will have this private data in a side database
type AssetPrivateDetails struct {
       ID             string `json:"assetID"`
       AppraisedValue int    `json:"appraisedValue"`
}

Specifically, access to the private data will be restricted as follows:

• objectType, color, size, and owner are stored in assetCollection and hence will be visible to members of the channel per the definition in the collection policy (Org1 and Org2).
• AppraisedValue of an asset is stored in collection Org1MSPPrivateCollection or Org2MSPPrivateCollection , depending on the owner of the asset. The value is only accessible to the users who belong to the organization that can store the collection.

具体来说，对私有数据的访问将受到以下限制：

• objectType, color, size, and owner 被存储在 assetCollection 因此，根据集合策略中的定义，这些数据对通道上的Org1和Org2是可以访问的。
• 资产的评估价值被存储在 Org1MSPPrivateCollection 或 Org2MSPPrivateCollection 集合中，取决于资产的所有者。只有属于可以存储集合的组织的用户才能访问该评估值。