[FAB-17135] Document private data enhancements in v2.0

Document private data enhancements in v2.0 including:
- collection level endorsement policy
- implicit org-specific collections
- inclusion of private data in events
- memberOnlyWrite property

Signed-off-by: David Enyeart <enyeart@us.ibm.com>

docs/source/endorsement-policies.rst

@@ -17,29 +17,35 @@ of endorsements and that they are from the expected sources (both of these are
 specified in the endorsement policy). The endorsements are also checked to make
 sure they're valid (i.e., that they are valid signatures from valid certificates).
 
-Two ways to require endorsement
--------------------------------
+Multiple ways to require endorsement
+------------------------------------
 
 By default, endorsement policies are specified in the chaincode definition,
 which is agreed to by channel members and then committed to a channel (that is,
 one endorsement policy covers all of the state associated with a chaincode).
 
-However, there are cases where it may be necessary for a particular state (a
-particular key-value pair, in other words) to have a different endorsement policy.
-This **state-based endorsement** allows the default chaincode-level endorsement
-policies to be overridden by a different policy for the specified keys.
+For private data collections, you can also specify an endorsement policy
+at the private data collection level, which would override the chaincode
+level endorsement policy for any keys in the private data collection, thereby
+further restricting which organizations can write to a private data collection.
 
-To illustrate the circumstances in which these two types of endorsement policies
+Finally, there are cases where it may be necessary for a particular public
+channel state or private data collection state (a particular key-value pair,
+in other words) to have a different endorsement policy.
+This **state-based endorsement** allows the chaincode-level or collection-level
+endorsement policies to be overridden by a different policy for the specified keys.
+
+To illustrate the circumstances in which the various types of endorsement policies
 might be used, consider a channel on which cars are being exchanged. The "creation"
 --- also known as "issuance" -- of a car as an asset that can be traded (putting
 the key-value pair that represents it into the world state, in other words) would
 have to satisfy the chaincode-level endorsement policy. To see how to set a
 chaincode-level endorsement policy, check out the section below.
 
-If the car requires a specific endorsement policy, it can be defined either when
-the car is created or afterwards. There are a number of reasons why it might
-be necessary or preferable to set a state-specific endorsement policy. The car
-might have historical importance or value that makes it necessary to have the
+If the key representing the car requires a specific endorsement policy, it can be
+defined either when the car is created or afterwards. There are a number of reasons
+why it might be necessary or preferable to set a state-specific endorsement policy. The
+car might have historical importance or value that makes it necessary to have the
 endorsement of a licensed appraiser. Also, the owner of the car (if they're a
 member of the channel) might also want to ensure that their peer signs off on a
 transaction. In both cases, **an endorsement policy is required for a particular
@@ -116,8 +122,8 @@ that they can be written to be updated automatically with channel membership.
 
 If you specify an endorsement policy using the ``—-signature-policy`` flag or
 the SDK, you will need to update the policy when organizations join or leave the
-channel. A new organization added to the channel after instantiation will be
-able to query a chaincode (provided the query has appropriate authorization as
+channel. A new organization added to the channel after the chaincode has been defined
+will be able to query a chaincode (provided the query has appropriate authorization as
 defined by channel policies and any application level checks enforced by the
 chaincode) but will not be able to execute or endorse the chaincode. Only
 organizations listed in the endorsement policy syntax will be able sign
@@ -162,14 +168,39 @@ For example:
     'Org2.member'), AND('Org1.member', 'Org3.member'), AND('Org2.member',
     'Org3.member'))``.
 
+Setting collection-level endorsement policies
+---------------------------------------------
+Similar to chaincode-level endorsement policies, when you approve and commit
+a chaincode definition, you can also specify the chaincode's private data collections
+and corresponding collection-level endorsement policies. If a collection-level
+endorsement policy is set, transactions that write to a private data collection
+key will require that the specified organization peers have endorsed the transaction.
+
+You can use collection-level endorsement policies to restrict which organization
+peers can write to the private data collection key namespace, for example to
+ensure that non-authorized organizations cannot write to a collection, and to
+have confidence that any state in a private data collection has been endorsed
+by the required collection organization(s).
+
+The collection-level endorsement policy may be less restrictive or more restrictive
+than the chaincode-level endorsement policy and the collection's private data
+distribution policy.  For example a majority of organizations may be required
+to endorse a chaincode transaction, but a specific organization may be required
+to endorse a transaction that includes a key in a specific collection.
+
+The syntax for collection-level endorsement policies exactly matches the syntax
+for chaincode-level endorsement policies --- in the collection configuration
+you can specify an ``endorsementPolicy`` with either a ``signaturePolicy`` or
+``channelConfigPolicy``. For more details see :doc:`private-data-arch`.
+
 .. _key-level-endorsement:
 
 Setting key-level endorsement policies
 --------------------------------------
 
-Setting regular chaincode-level endorsement policies is tied to the lifecycle of
-the corresponding chaincode. They can only be set or modified when instantiating
-or upgrading the corresponding chaincode on a channel.
+Setting regular chaincode-level or collection-level endorsement policies is tied to
+the lifecycle of the corresponding chaincode. They can only be set or modified when
+defining the chaincode on a channel.
 
 In contrast, key-level endorsement policies can be set and modified in a more
 granular fashion from within a chaincode. The modification is part of the
@@ -234,29 +265,29 @@ At commit time, setting a value of a key is no different from setting the
 endorsement policy of a key --- both update the state of the key and are
 validated based on the same rules.
 
-+---------------------+-----------------------------+--------------------------+
-| Validation          | no validation parameter set | validation parameter set |
-+=====================+=============================+==========================+
-| modify value        | check chaincode ep          | check key-level ep       |
-+---------------------+-----------------------------+--------------------------+
-| modify key-level ep | check chaincode ep          | check key-level ep       |
-+---------------------+-----------------------------+--------------------------+
++---------------------+------------------------------------+--------------------------+
+| Validation          | no validation parameter set        | validation parameter set |
++=====================+====================================+==========================+
+| modify value        | check chaincode or collection ep   | check key-level ep       |
++---------------------+------------------------------------+--------------------------+
+| modify key-level ep | check chaincode or collection ep   | check key-level ep       |
++---------------------+------------------------------------+--------------------------+
 
 As we discussed above, if a key is modified and no key-level endorsement policy
-is present, the chaincode-level endorsement policy applies by default. This is
-also true when a key-level endorsement policy is set for a key for the first time
+is present, the chaincode-level or collection-level endorsement policy applies by default.
+This is also true when a key-level endorsement policy is set for a key for the first time
 --- the new key-level endorsement policy must first be endorsed according to the
-pre-existing chaincode-level endorsement policy.
+pre-existing chaincode-level or collection-level endorsement policy.
 
 If a key is modified and a key-level endorsement policy is present, the key-level
-endorsement policy overrides the chaincode-level endorsement policy. In practice,
-this means that the key-level endorsement policy can be either less restrictive
-or more restrictive than the chaincode-level endorsement policy. Because the
-chaincode-level endorsement policy must be satisfied in order to set a key-level
-endorsement policy for the first time, no trust assumptions have been violated.
+endorsement policy overrides the chaincode-level or collection-level endorsement policy.
+In practice, this means that the key-level endorsement policy can be either less restrictive
+or more restrictive than the chaincode-level or collection-level endorsement policies.
+Because the chaincode-level or collection-level endorsement policy must be satisfied in order
+to set a key-level endorsement policy for the first time, no trust assumptions have been violated.
 
 If a key's endorsement policy is removed (set to nil), the chaincode-level
-endorsement policy becomes the default again.
+or collection-level endorsement policy becomes the default again.
 
 If a transaction modifies multiple keys with different associated key-level
 endorsement policies, all of these policies need to be satisfied in order

docs/source/peer_event_services.rst

@@ -10,7 +10,7 @@ ledger, regardless of the channel to which that block pertained, and it was only
 accessible to members of the organization running the eventing peer (i.e., the
 one being connected to for events).
 
-Starting with v1.1, there are two new services which provide events. These services use an
+Starting with v1.1, there are new services which provide events. These services use an
 entirely different design to provide events on a per-channel basis. This means
 that registration for events occurs at the level of the channel instead of the peer,
 allowing for fine-grained control over access to the peer's data. Requests to
@@ -28,6 +28,12 @@ This service sends entire blocks that have been committed to the ledger. If
 any events were set by a chaincode, these can be found within the
 ``ChaincodeActionPayload`` of the block.
 
+* ``DeliverWithPrivateData``
+
+This service sends the same data as the ``Deliver`` service, and additionally
+includes any private data from collections that the client's organization is
+authorized to access.
+
 * ``DeliverFiltered``
 
 This service sends "filtered" blocks, minimal sets of information about blocks
@@ -42,7 +48,7 @@ any events were set by a chaincode, these can be found within the
 How to register for events
 --------------------------
 
-Registration for events from either service is done by sending an envelope
+Registration for events is done by sending an envelope
 containing a deliver seek info message to the peer that contains the desired start
 and stop positions, the seek behavior (block until ready or fail if not ready).
 There are helper variables ``SeekOldest`` and ``SeekNewest`` that can be used to
@@ -53,7 +59,7 @@ include a stop position of ``MAXINT64``.
 .. note:: If mutual TLS is enabled on the peer, the TLS certificate hash must be
           set in the envelope's channel header.
 
-By default, both services use the Channel Readers policy to determine whether
+By default, the event services use the Channel Readers policy to determine whether
 to authorize requesting clients for events.
 
 Overview of deliver response messages
@@ -63,11 +69,12 @@ The event services send back ``DeliverResponse`` messages.
 
 Each message contains one of the following:
 
- * status -- HTTP status code. Both services will return the appropriate failure
+ * status -- HTTP status code. Each of the services will return the appropriate failure
    code if any failure occurs; otherwise, it will return ``200 - SUCCESS`` once
    the service has completed sending all information requested by the ``SeekInfo``
    message.
  * block -- returned only by the ``Deliver`` service.
+ * block and private data -- returned only by the ``DeliverWithPrivateData`` service.
  * filtered block -- returned only by the ``DeliverFiltered`` service.
 
 A filtered block contains: