Skip to content

Commit

Permalink
[FAB-17135] Document private data enhancements in v2.0
Browse files Browse the repository at this point in the history 
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>
  • Loading branch information
@denyeart
denyeart committed Dec 9, 2019
1 parent 00eecd1 commit 3e3b0fc
Show file tree
Hide file tree
Showing 3 changed files with 143 additions and 55 deletions.
95 changes: 63 additions & 32 deletions docs/source/endorsement-policies.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
15 changes: 11 additions & 4 deletions docs/source/peer_event_services.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand Down
Loading

0 comments on commit 3e3b0fc

Please sign in to comment.