Private Data Collection Definition

Private Data Collection Definition

A collection definition contains one or more collections, each having a policy definition listing organizations in the collection. It also includes properties used to control dissemination of private data at endorsement time and, optionally, whether data will be purged.

A collection definition is part of a chaincode definition. The collection is approved by channel members, and then deployed when the chaincode definition is committed to the channel. The collection file should be the same for all channel members. To specify a collection definition JSON file, the --collections-config flag is used in approveformyorg and commit commands.

peer lifecycle chaincode commit -o orderer.example.com:7050 --channelID mychannel --name chaincode --version 1.0 --sequence 1 --collections-config collections.json

Collection Definitions are composed of the following properties.

• name

  name is a name of a private data collection. Chaincodes refer to collections by name.

• policy

  policy, i.e., a private data distribution policy, defines which organizations are allowed to persist the collection data on their peers.

  The policy is expressed similar to endorsement policies. Each member that should have rights to persist private data must be included in the OR policy statement, e.g. "OR('Org1MSP.member', 'Org2MSP.member')".

  To support read/write transactions, a private data distribution policy should define a broader set of organizations than the chaincode endorsement policy, as peers must have private data in order to endorse proposed transactions. For example, if we need at least two organizations to endorse a transaction, then at least two organizations on the channel should be included in a private data collection distribution policy.

  The policy field does not specify which organizations are allowed to read or write private data. Access to private data is determined by memberOnlyRead and memberOnlyWrite options (see the description below) and by the chaincode itself. However, organizations that are not included in the policy cannot persist data.

• requiredPeerCount

  requiredPeerCount is the minimum number of peers across authorized organizations that each endorsing peer must successfully disseminate private data to before a peer signs an endorsement and returns a proposal response back to a client.

  Requiring dissemination as a condition of endorsement will ensure that private data is available in the network even if endorsing peers become unavailable. When requiredPeerCount is 0, it means that no distribution is required. However, there may be some distribution if maxPeerCount (see the next element below) is greater than zero. It is not recommended to set the requiredPeerCount value to 0, as it could lead to loss of private data in the network if endorsing peers become unavailable. Typically, you would want to require at least some distribution of private data at the endorsement time to ensure redundancy of private data on multiple peers in the network.

• maxPeerCount

  maxPeerCount is the maximum number of peers across authorized organizations that each endorsing peer will attempt to disseminate private data to.

  If an endorsing peer becomes unavailable between the endorsement time and the commit time, other peers that are collection members, but who did not yet receive private data at the endorsement time, will be able to pull private data from peers this data was disseminated to.

  If maxPeerCount is set to 0, private data is not disseminated at the endorsement time, forcing private data pulls against endorsing peers on all authorized peers at the commit time.

• blockToLive

  blockToLive represents how long private data should live on the side database in terms of blocks.

  For very sensitive data, even parties sharing private data might want—or might be required by government regulations—to periodically “purge” the data on their peers. As a result, a hash of private data is left in a blockchain to serve as immutable evidence.

  In some of these cases, private data only needs to exist on a peer’s private database until it can be replicated into a database external to the peer’s blockchain. The private data might also only need to exist on the peers until the chaincode business process is done with it (the trade is settled, the contract is fulfilled, etc).

  To support these use cases, private data can be purged if it has not been modified for the blockToLive number of blocks. The purged private data cannot be queried from a chaincode and is not available to other requesting peers.

  To keep private data indefinitely, i.e., to never purge private data, set the blockToLive property to 0.

• memberOnlyRead

  memberOnlyRead is a boolean value indicating who is allowed to read private data.

  A value of true indicates that peers automatically enforce that only clients belonging to one of the collection member organizations are provided with read access to private data. If a client from a non-member organization attempts to execute a chaincode function that performs a read of private data, the chaincode invocation is terminated with an error.

  A value of false can be used to encode more granular access control within individual chaincode functions.

• memberOnlyWrite

  memberOnlyWrite is a boolean value indicating who is allowed to write private data.

  A value of true indicates that peers automatically enforce that only clients belonging to one of the collection member organizations are provided with write access to private data. If a client from a non-member organization attempts to execute a chaincode function that performs a write of private data, the chaincode invocation is terminated with an error.

  A value of false can be used to encode more granular access control within individual chaincode functions.

• endorsementPolicy

  endorsementPolicy is an optional endorsement policy that overrides a chaincode level endorsement policy for the collection-related transactions. It can be expressed using either a signature or a channel configuration policy syntax. endorsementPolicy may be the same as the collection distribution policy or may require fewer or additional organization peers.

Below, you can find a JSON file that is a sample of a private data collection definition.

[
   {
       "name": "twoOrgsCollection",
       "policy": "OR('Org1MSP.member', 'Org2MSP.member')",
       "requiredPeerCount": 1,
       "maxPeerCount": 3,
       "blockToLive": 1000,
       "memberOnlyRead": true,
       "memberOnlyWrite": true,
       "endorsementPolicy": {
           "signaturePolicy": "AND('Org1MSP.member', 'Org2MSP.member')"
       }  
   },
   {
       "name": "oneOrgCollection",
       "policy": "OR('Org1MSP.member')",  
       "requiredPeerCount": 1,
       "maxPeerCount": 1,
       "blockToLive": 0,
       "memberOnlyRead": true,
       "memberOnlyWrite": true
   }
]

This example defines two collections. twoOrgsCollection is operated by both Org1 and Org2, while only Org1 is authorized to access oneOrgCollection.

The second collection, however, is redundant. Starting in Hyperledger Fabric 2.0, implicit private per-organization data collections are provided by default. They are used to track chaincode definitions that are approved by an organization. Implicit collections can be also accessed by chaincodes. Each organization-specific implicit collection has a distribution policy and endorsement policy of the matching organization and can be referred to by the _implicit_org_<MSPID> name, e.g. _implicit_org_Org1MSP.