[FAB-2094] Documenting MSP Setup & Best Practices

This changeset documents default MSP configuration parameters, and
its setup process on the peer and orderer side.

It also touches how MSP configuration updates take place within a channel, but
this is to be expanded after configuration updates related code is merged.

This changeset also discusses best practices and assumptions associated to
the default MSP considered by the fabric.

Change-Id: Ibe043202567619c7ad91f31ff7f1056b768db5e6
Signed-off-by: Elli Androulaki <lli@zurich.ibm.com>

docs/source/msp.rst

@@ -0,0 +1,281 @@
+Membership Service Providers (MSPs): Setup & Best Practices
+===========================================================
+
+Membership service provider (MSP) is a component that aims to offer an
+abstraction of a membership operation architecture.
+
+In particular, MSP abstracts away all cryptographic mechanisms and protocols
+behind issuing and validating certificates, and user authentication. An
+MSP may define their own notion of identity, and the rules by which those
+identities are governed (identity validation) and authenticated (signature
+generation and verification).
+
+Fabric Blockchain network can be governed by one or more MSPs. In this
+way Fabric offers modularity of membership operations, and interoperability
+across different membership standards and architectures.
+
+In the rest of this document we elaborate on the setup of the MSP
+implementation supported by Fabric, and discuss best practices concerning
+its use.
+
+MSP Configuration
+-----------------
+
+To setup an instance of the MSP, its configuration needs to be specified
+locally at each peer and orderer (to enable peer, and orderer signing),
+and on the channels to enable peer, orderer, client identity validation, and
+respective signature verification (authentication) by and for all channel
+members.
+
+First of all, for each MSP a name needs to be specified to reference that MSP
+in the network, e.g., “org1”, “msp2”, and “org3.divA”. This is the name under
+which membership rules of an MSP representing a consortium, organisation or
+organisation division is to be referenced in a channel. This is also referred
+to as *MSP Identifier*. MSP Identifiers are important to be unique per MSP
+instance. For example, shall two MSP instances with the same identifier are
+detected at the system channel genesis, orderer setup will fail.
+
+In the case of default implementation of MSP, a set of parameters need to be
+specified to allow for identity (certificate) validation and signature
+verification. These parameters are deduced by
+`RFC5280 <http://www.ietf.org/rfc/rfc5280.txt>`_, and include:
+
+    - A list of self-signed (X.509) certificates to constitute the *root of
+    trust*
+    - A list of X.509 certificates to represent intermediate CAs this provider
+    considers for certificate validation; these certificates ought to be
+    certified by exactly one of the certificates in the root of trust;
+    intermediate CAs are optional parameters
+    - A list of X.509 certificates with a verifiable certificate path to
+    exactly one of the certificates of the root of trust to represent the
+    administrators of this MSP; owners of these
+    certificates are authorized to request changes to this MSP configuration
+    (e.g., root CAs, intermediate CAs)
+    - A list of Organizational Units, that valid members of this MSP should
+    include in their X.509 certificate; this is an optional configuration
+    parameter, used when, e.g., multiple organisations leverage the same
+    root of trust, and intermediate CAs, and have reserved an OU field for
+    their members
+    - A list of certificate revocation lists (CRLs) each corresponding to
+    exactly one of the listed (intermediate or root) MSP Certificate
+    Authorities; this is an optional parameter
+
+*Valid* identities for this MSP instance have the form of X.509 certificates
+with a verifiable certificate path to exactly one of the root of trust
+certificates, are not included in any CRL, and *list* one or more of the
+Organizational Units of the MSP configuration in the ``OU`` field of
+their X.509 certificate structure.
+
+In addition to verification related parameters, for the MSP to enable
+the node on which it is instantiated to sign or authenticate, one needs to
+specify:
+    - The signing key used for signing by the node, and
+    - The node' s X.509 certificate, that is a valid identity under the
+    verification parameters of this MSP.
+
+
+How to generate MSP certificates and their signing keys?
+--------------------------------------------------------
+To generate X.509 certificates to feed its MSP configuration, the application
+can use `Openssl <https://www.openssl.org/>`_.
+
+Alternatively one can use ``cryptogen`` tool, whose operation is explained in
+another document.
+
+For fabric-ca related certificate generation, we refer the reader to the
+fabric-ca related documentation (./Setup/ca-setup.rst).
+
+
+MSP setup on the peer & orderer side
+------------------------------------
+
+To set up a local MSP (for either a peer or an orderer), the administrator
+should create a folder e.g., $MY_PATH/mspconfig, which contains six subfolders
+and a file:
+    1. a folder `admincerts` to include PEM files each corresponding to an
+    administrator certificate
+    2. a folder `cacerts` to include PEM files each corresponding to a root
+    CAs certificate
+    3. (optional) a folder `intermediatecerts` to include PEM files each
+    corresponding to an intermediate CAs 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")
+    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
+    7. a folder `signcerts` to include a PEM file with the node's X.509
+    certificate
+
+
+In the configuration file of the node (core.yaml file for the peer, and
+orderer.yaml for the orderer) file, one needs to specify the path to the
+mspconfig folder, and the msp identifier of the node' s MSP. The path to the
+mspconfig folder is expected to be relative to FABRIC_CFG_PATH and is provided
+as the value of parameter ``mspConfigPath`` for the peer, and ``LocalMSPDir``
+for the orderer. The identifier of the node's MSP is provided as value of
+parameter ``localMspId`` for the peer and ``LocalMSPID`` for the orderer.
+These variables can be overriden via the environment using the CORE prefix for
+peer (e.g. CORE_PEER_LOCALMSPID) and the ORDERER prefix for the orderer (e.g.
+ORDERER_GENERAL_LOCALMSPID). Notice that for the orderer setup, one needs to
+generate, and provide to the orderer the genesis block of the system channel.
+The MSP configuration needs of this block are detailed in the next section.
+
+
+*Reconfiguration* of a "local" MSP is only possible manually, and requires that
+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.
+
+
+Channel MSP setup
+-----------------
+At the genesis of the system, verification parameters of all the MSPs that
+appear in the network need to be specified, and included in the system
+channel's genesis block. Recall that MSP verification parameters consist of
+the MSP identifier, the root of trust certificates, intermediate CA and admin
+certificates as well as OU specifications and CRLs.
+The system genesis block is provided to the orderers at their setup phase,
+and allows them to authenticate channel creation requests. Orderers would
+reject the system genesis block, if the latter includes two MSPs with the same
+identifier, and consequently the bootstrapping of the network would fail.
+
+For application channels, the verification components of only the MSPs that
+governs a channel need to reside in the channel's genesis block. We emphasise
+that it is **the responsibility of the application** to ensure that correct
+MSP configuration information is included in the genesis blocks (or the
+most recent configuration block) of a channel prior to instructing one or
+more peers of theirs to join the channel.
+
+When bootstrapping a channel with the help of configtxgen tool, one can
+configure the channel MSPs by including the verification parameters of MSP
+in the mspconfig folder, and setting that path in the relevant section in
+`configtx.yaml`.
+
+*Reconfiguration* of an MSP on the channel, including announcements of the
+certificate revocation lists associated to the CAs of that MSP is achieved
+through the creation of a config_update object by the owner of one of the
+administrator certificates of the MSP. The client application managed by the
+admin would then announce this update o the channels in which this MSP appears.
+
+
+
+Best Practices
+--------------
+
+In this section we elaborate on best practices for MSPs
+configuration in commonly met scenarios.
+
+**1) Mapping between organizations/corporations and MSPs**
+
+We recommend that there is a one-to-one mapping between organizations and MSPs.
+If a different mapping type of mapping is chosen the following needs to be to
+considered:
+
+    - **One organization employing various MSPs.** This corresponds to the
+    case of an organization including a variety of divisions each represented
+    by its MSP, either for management independence
+    reasons, or for privacy reasons. In this case a peer can only be owned by
+    a single MSP, and will not recognize peers with identities from other MSPs
+    as peers of the same organization. The implication of this is that peers
+    may share through gossip organization-scoped data with a set of peers that
+    are members of the same subdivision, and not with the full set of providers
+    constituting the actual organization.
+    - **Multiple organizations using a single  MSP.** This corresponds to a
+    case of a consortium of organisations, that are governed by similar
+    membership architecture. One needs to know here that peers would propagate
+    organization-scoped messages to the peers that have identity under the
+    same MSP regardless of whether they belong to the same actual organization.
+    This is a limitation of granularity of MSP definition, and/or of peer’s
+    configuration. In future versions of Fabric, this can change as we move
+    towards (i) an identity channel that contains all membership related
+    information of the network, (ii) peer notion of “trust-zone” being
+    configurable, a peer’s administrator specifying at peer setup time whose
+    MSP members should be treated by peers as authorized to receive
+    “organization”-scoped messages.
+
+**2) On organization has different divisions (say organizational units), to**
+**which it wants to grant access to different channels.**
+
+Two ways to handle this:
+    -  Define one MSP to accommodate membership for all organization’s
+    members. Configuration of that MSP would consist of a list of root CAs,
+    intermediate CAs and admin certificates, and membership identities would
+    include the organizational unit (OU) a member belongs to. Policies can then
+    be defined to capture members of a specific OU, and these policies may
+    constitute the read/write policies of a channel or endorsement policies of
+    a chaincode. A limitation of this approach, is that gossip peers would
+    consider peers with membership identities under their local MSP as
+    members of the same organization, and would consequently gossip
+    with them organisation-scoped data (e.g., their status).
+    - Defining one MSP to represent each division, i.e., specify for each
+    division a set of certificates, for root CAs, intermediate CAs, and admin
+    Certs, such that there is no overlapping certification path across MSPs.
+    This would mean that, e.g., a different intermediate CA per subdivision
+    is employed. Here the disadvantage is the management of more than one
+    MSPs instead of one, but this circumvents the issue present in approach
+    (1).
+    - Define one MSP for each division by leveraging an OU extension of the
+    MSP configuration.
+
+**3) Separating clients from peers of the same organization.**
+
+In many cases it is required that the “type” of an identity is retrievable
+from the identity itself, e.g., it may be needed that endorsements are
+guaranteed to have derived by peers, and not clients or nodes acting solely
+as orderers.
+
+There is limited support for such requirements.
+
+One way to allow for this separation is to to create a separate intermediate
+CA for each node type, one for clients and one for peers/orderers, and
+configure two different MSPs one for clients, and one for peers/orderers.
+Channels this organization should be accessing, would need to include
+both MSPs, while endorsement policies will leverage only the MSP that
+refers to the peers. This would ultimately result into the organization
+being mapped to two MSP instances, and would have certain consequences
+into the way peers and clients interact.
+
+Gossip would not be drastically impacted as all peers of the same organization
+would still belong to one MSP. Peers restrict the execution of certain
+system chaincodes to, e.g., local MSP based policies. For
+example, peers would only execute “JoinChannel” request if the request is
+signed by the admin of their local MSP who can only be a client (end-user
+should be sitting at the origin of that request). We can go around this
+inconsistency if we accept that the only clients to be members of a
+peer/orderer MSP would be the administrators of that MSP.
+
+Another point to be considered with this approach is that peers
+authorize event registration requests based on membership of request
+originator within their local MSP. Clearly, since the originator of the
+request is a client, the request originator is always doomed to belong
+to a different MSP than the requested peer and the peer would reject the
+request.
+
+
+**4) Admin and CA certificates.** It is important to set MSP admin certificates
+to be different than any of the certificates considered by the MSP for ``root
+of trust``, or intermediate CAs. This is a common (security) practice to
+separate the duties of management of membership components from the issuing of
+new certificates, and/or validation of existing ones.
+
+**5) Blacklisting an intermediate CA.** As mentioned in previous sections,
+reconfiguration of an MSP is achieved by reconfiguration mechanisms (manual
+reconfiguration for the local MSP instances, and via properly constructed
+``config_update`` messages for MSP instances of a channel). Clearly, there are
+two ways to ensure an intermediate CA considered in an MSP is no longer
+considered for that MSP's identity validation:
+    1. Reconfigure the MSP to no longer include the certificate of that
+    intermediate CA in the list of trusted intermediate CA certs. For the
+    locally configured MSP, this would mean that the certificate of this CA is
+    removed from the ``intermediatecerts`` folder.
+    2. Reconfigure the MSP to include a CRL produced by the root of trust
+    which denounces the mentioned intermediate CA's certificate.
+In the current MSP implementation we only support method (1) as it is simpler
+and does not require that the no longer considered intermediate CA is
+blacklisted.