From be6dbe28d5d9f172b25faed58f999c5d33d1a656 Mon Sep 17 00:00:00 2001 From: Angelo De Caro Date: Tue, 13 Feb 2018 14:08:16 +0100 Subject: [PATCH] [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 --- docs/source/endorsement-policies.rst | 19 ++++++-- docs/source/msp.rst | 72 ++++++++++++++++++++++++---- docs/source/policies.rst | 31 +++++++----- 3 files changed, 96 insertions(+), 26 deletions(-) diff --git a/docs/source/endorsement-policies.rst b/docs/source/endorsement-policies.rst index 232d04405e1..5686f0f4bad 100644 --- a/docs/source/endorsement-policies.rst +++ b/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 `_), +one can use the PEER role to restrict endorsement to only peers. + +For example: + +:: + + peer chaincode instantiate -C -n mycc -P "AND('Org1.peer', 'Org2.peer')" + .. Licensed under Creative Commons Attribution 4.0 International License https://creativecommons.org/licenses/by/4.0/ diff --git a/docs/source/msp.rst b/docs/source/msp.rst index 0b7e575dee5..8a15aa762e5 100644 --- a/docs/source/msp.rst +++ b/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 - ```` 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 ----------------- diff --git a/docs/source/policies.rst b/docs/source/policies.rst index 1aa5b1df1af..8fd51348c12 100644 --- a/docs/source/policies.rst +++ b/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 `_) Constructing an ImplicitMetaPolicy ----------------------------------