[FAB-7750] Documentation for FAB-5664

This change-set updates the documentation to describe
the functionality introduced by FAB-5664
to tell apart fabric network nodes as clients and peers.

Change-Id: Ifac62951c6c635c83ff5c88a4bb2e5c43bfdbd6f
Signed-off-by: Angelo De Caro <adc@zurich.ibm.com>

Author: adecaro

docs/source/endorsement-policies.rst

@@ -25,12 +25,14 @@ boolean expressions over principals.
 
 A principal is described in terms of the MSP that is tasked to validate
 the identity of the signer and of the role that the signer has within
-that MSP. Currently, two roles are supported: **member** and **admin**.
+that MSP. Four roles are supported: **member**, **admin**, **client**, and **peer**.
 Principals are described as ``MSP``.\ ``ROLE``, where ``MSP`` is the MSP
-ID that is required, and ``ROLE`` is either one of the two strings
-``member`` and ``admin``. Examples of valid principals are
+ID that is required, and ``ROLE`` is one of the four strings
+``member``, ``admin``, ``client`` and ``peer``. Examples of valid principals are
 ``'Org0.admin'`` (any administrator of the ``Org0`` MSP) or
-``'Org1.member'`` (any member of the ``Org1`` MSP).
+``'Org1.member'`` (any member of the ``Org1`` MSP),
+``'Org1.client'`` (any client of the ``Org1`` MSP), and
+``'Org1.peer'`` (any peer of the ``Org1`` MSP).
 
 The syntax of the language is:
 
@@ -72,5 +74,14 @@ This command deploys chaincode ``mycc`` with the policy ``AND('Org1.member',
 'Org2.member')`` which would require that a member of both Org1 and Org2 sign
 the transaction.
 
+Notice that, if the identity classification is enabled (see `MSP Documentation <http://hyperledger-fabric.readthedocs.io/en/latest/msp.html>`_),
+one can use the PEER role to restrict endorsement to only peers.
+
+For example:
+
+::
+
+    peer chaincode instantiate -C <channelid> -n mycc -P "AND('Org1.peer', 'Org2.peer')"
+
 .. Licensed under Creative Commons Attribution 4.0 International License
    https://creativecommons.org/licenses/by/4.0/

docs/source/msp.rst

@@ -117,15 +117,8 @@ and a file:
    CA's certificate
 3. (optional) a folder ``intermediatecerts`` to include PEM files each
    corresponding to an intermediate CA's certificate
-4. (optional) a file ``config.yaml`` to include information on the
-   considered OUs; the latter are defined as pairs of
-   ``<Certificate, OrganizationalUnitIdentifier>`` entries of a yaml array
-   called ``OrganizationalUnitIdentifiers``, where ``Certificate`` represents
-   the relative path to the certificate of the certificate authority (root or
-   intermediate) that should be considered for certifying members of this
-   organizational unit (e.g. ./cacerts/cacert.pem), and
-   ``OrganizationalUnitIdentifier`` represents the actual string as
-   expected to appear in X.509 certificate OU-field (e.g. "COP")
+4. (optional) a file ``config.yaml`` to configure the supported Organizational Units
+   and identity classifications (see respective sections below).
 5. (optional) a folder ``crls`` to include the considered CRLs
 6. a folder ``keystore`` to include a PEM file with the node's signing key;
    we emphasise that currently RSA keys are not supported
@@ -154,6 +147,67 @@ the peer or orderer process is restarted. In subsequent releases we aim to
 offer online/dynamic reconfiguration (i.e. without requiring to stop the node
 by using a node managed system chaincode).
 
+Organizational Units
+--------------------
+
+In order to configure the list of Organizational Units that valid members of this MSP should
+include in their X.509 certificate, the ``config.yaml`` file
+needs to specify the organizational unit identifiers. Here is an example:
+
+::
+
+   OrganizationalUnitIdentifiers:
+     - Certificate: "cacerts/cacert1.pem"
+       OrganizationalUnitIdentifier: "commercial"
+     - Certificate: "cacerts/cacert2.pem"
+       OrganizationalUnitIdentifier: "administrators"
+
+The above example declares two organizational unit identifiers: **commercial** and **administrators**.
+An MSP identity is valid if it carries at least one of these organizational unit identifiers.
+The ``Certificate`` field refers to the CA or intermediate CA certificate path
+under which identities, having that specific OU, should be validated.
+The path is relative to the MSP root folder and cannot be empty.
+
+Identity Classification
+-----------------------
+
+The default MSP implementation allows to further classify identities into clients and peers, based on the OUs
+of their x509 certificates.
+An identity should be classified as a **client** if it submits transactions, queries peers, etc.
+An identity should be classified as a **peer** if it endorses or commits transactions.
+In order to define clients and peers of a given MSP, the ``config.yaml`` file
+needs to be set appropriately. Here is an example:
+
+::
+
+   NodeOUs:
+     Enable: true
+     ClientOUIdentifier:
+       Certificate: "cacerts/cacert.pem"
+       OrganizationalUnitIdentifier: "client"
+     PeerOUIdentifier:
+       Certificate: "cacerts/cacert.pem"
+       OrganizationalUnitIdentifier: "peer"
+
+As shown above, the ``NodeOUs.Enable`` is set to ``true``, this enables the identify classification.
+Then, client (peer) identifiers are defined by setting the following properties
+for the ``NodeOUs.ClientOUIdentifier`` (``NodeOUs.PeerOUIdentifier``) key:
+ a. ``OrganizationalUnitIdentifier``: Set this to the value that matches the OU that
+ the x509 certificate of a client (peer) should contain.
+ b. ``Certificate``: Set this to the CA or intermediate CA under which client (peer) identities
+ should be validated. The field is relative to the MSP root folder. It can be empty, meaning
+ that the identity's x509 certificate can be validated under any CA defined in the MSP configuration.
+
+When the classification is enabled, MSP administrators need
+to be clients of that MSP, meaning that their x509 certificates need to carry
+the OU that identifies the clients.
+Notice also that, an identity can be either a client or a peer.
+The two classifications are mutually exclusive. If an identity is neither a client nor a peer,
+the validation will fail.
+
+Finally, notice that for upgraded environments the 1.1 channel capability
+needs to be enabled before identify classification can be used.
+
 Channel MSP setup
 -----------------
 

docs/source/policies.rst

@@ -299,23 +299,28 @@ message defined as follows:
 
 ::
 
-    message MSPRole {
-        string msp_identifier = 1;
+   message MSPRole {
+       string msp_identifier = 1;
 
-        enum MSPRoleType {
-            MEMBER = 0; // Represents an MSP Member
-            ADMIN  = 1; // Represents an MSP Admin
-        }
+       enum MSPRoleType {
+           MEMBER = 0; // Represents an MSP Member
+           ADMIN  = 1; // Represents an MSP Admin
+           CLIENT = 2; // Represents an MSP Client
+           PEER = 3; // Represents an MSP Peer
+       }
 
-        MSPRoleType Role = 2;
-    }
+       MSPRoleType role = 2;
+   }
 
 The ``msp_identifier`` is set to the ID of the MSP (as defined by the
-MSPConfig proto in the channel configuration for an org) which will
-evaluate the signature, and the ``Role`` is set to either ``MEMBER`` or
-``ADMIN``. The ``MEMBER`` role will match any certificate issued by the
-MSP, while the ``ADMIN`` role will match only certificates which are
-enumerated as admin certificates in the MSP definition.
+``MSPConfig`` proto in the channel configuration for an org) which will
+evaluate the signature, and the ``Role`` is set to either ``MEMBER``,
+``ADMIN``, ``CLIENT`` or ``PEER``. In particular
+
+1. ``MEMBER`` matches any certificate issued by the MSP.
+2. ``ADMIN`` matches certificates enumerated as admin in the MSP definition.
+3. ``CLIENT`` (``PEER``) matches certificates that carry the client (peer) Organizational unit
+(see `MSP Documentation <http://hyperledger-fabric.readthedocs.io/en/latest/msp.html>`_)
 
 Constructing an ImplicitMetaPolicy
 ----------------------------------