Skip to content

Commit

Permalink
[FAB-7750] Documentation for FAB-5664
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
adecaro committed Feb 16, 2018
1 parent ad5d0f7 commit be6dbe2
Show file tree
Hide file tree
Showing 3 changed files with 96 additions and 26 deletions.
19 changes: 15 additions & 4 deletions docs/source/endorsement-policies.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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/
72 changes: 63 additions & 9 deletions docs/source/msp.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
-----------------

Expand Down
31 changes: 18 additions & 13 deletions docs/source/policies.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
----------------------------------
Expand Down

0 comments on commit be6dbe2

Please sign in to comment.