github.com/kaituanwang/hyperledger@v2.0.1+incompatible/docs/source/msp.rst (about)

     1  Membership Service Providers (MSP)
     2  ==================================
     3  
     4  The document serves to provide details on the setup and best practices for MSPs.
     5  
     6  Membership Service Provider (MSP) is a Hyperledger Fabric component that offers
     7  an abstraction of membership operations.
     8  
     9  In particular, MSP abstracts away all cryptographic mechanisms and protocols
    10  behind issuing certificates, validating certificates and user authentication. An
    11  MSP may define their own notion of identity, and the rules by which those
    12  identities are governed (identity validation) and authenticated (signature
    13  generation and verification).
    14  
    15  A Hyperledger Fabric blockchain network can be governed by one or more MSPs.
    16  This provides modularity of membership operations, and interoperability
    17  across different membership standards and architectures.
    18  
    19  In the rest of this document we elaborate on the setup of the MSP
    20  implementation supported by Hyperledger Fabric, and discuss best practices
    21  concerning its use.
    22  
    23  MSP Configuration
    24  -----------------
    25  
    26  To setup an instance of the MSP, its configuration needs to be specified
    27  locally at each peer and orderer (to enable peer and orderer signing),
    28  and on the channels to enable peer, orderer, client identity validation, and
    29  respective signature verification (authentication) by and for all channel
    30  members.
    31  
    32  Firstly, for each MSP a name needs to be specified in order to reference that MSP
    33  in the network (e.g. ``msp1``, ``org2``, and ``org3.divA``). This is the name under
    34  which membership rules of an MSP representing a consortium, organization or
    35  organization division is to be referenced in a channel. This is also referred
    36  to as the *MSP Identifier* or *MSP ID*. MSP Identifiers are required to be unique per MSP
    37  instance. For example, shall two MSP instances with the same identifier be
    38  detected at the system channel genesis, orderer setup will fail.
    39  
    40  In the case of default implementation of MSP, a set of parameters need to be
    41  specified to allow for identity (certificate) validation and signature
    42  verification. These parameters are deduced by
    43  `RFC5280 <http://www.ietf.org/rfc/rfc5280.txt>`_, and include:
    44  
    45  - A list of self-signed (X.509) CA certificates to constitute the *root of
    46    trust*
    47  - A list of X.509 certificates to represent intermediate CAs this provider
    48    considers for certificate validation; these certificates ought to be
    49    certified by exactly one of the certificates in the root of trust;
    50    intermediate CAs are optional parameters
    51  - A list of X.509 certificates representing the administrators of this MSP with a
    52    verifiable certificate path to exactly one of the CA certificates of the
    53    root of trust; owners of these certificates are authorized to request changes
    54    to this MSP configuration (e.g. root CAs, intermediate CAs)
    55  - A list of Organizational Units that valid members of this MSP should
    56    include in their X.509 certificate; this is an optional configuration
    57    parameter, used when, e.g., multiple organizations leverage the same
    58    root of trust, and intermediate CAs, and have reserved an OU field for
    59    their members
    60  - A list of certificate revocation lists (CRLs) each corresponding to
    61    exactly one of the listed (intermediate or root) MSP Certificate
    62    Authorities; this is an optional parameter
    63  - A list of self-signed (X.509) certificates to constitute the *TLS root of
    64    trust* for TLS certificate.
    65  - A list of X.509 certificates to represent intermediate TLS CAs this provider
    66    considers; these certificates ought to be
    67    certified by exactly one of the certificates in the TLS root of trust;
    68    intermediate CAs are optional parameters.
    69  
    70  *Valid*  identities for this MSP instance are required to satisfy the following conditions:
    71  
    72  - They are in the form of X.509 certificates with a verifiable certificate path to
    73    exactly one of the root of trust certificates;
    74  - They are not included in any CRL;
    75  - And they *list* one or more of the Organizational Units of the MSP configuration
    76    in the ``OU`` field of their X.509 certificate structure.
    77  
    78  For more information on the validity of identities in the current MSP implementation,
    79  we refer the reader to :doc:`msp-identity-validity-rules`.
    80  
    81  In addition to verification related parameters, for the MSP to enable
    82  the node on which it is instantiated to sign or authenticate, one needs to
    83  specify:
    84  
    85  - The signing key used for signing by the node (currently only ECDSA keys are
    86    supported), and
    87  - The node's X.509 certificate, that is a valid identity under the
    88    verification parameters of this MSP.
    89  
    90  It is important to note that MSP identities never expire; they can only be revoked
    91  by adding them to the appropriate CRLs. Additionally, there is currently no
    92  support for enforcing revocation of TLS certificates.
    93  
    94  How to generate MSP certificates and their signing keys?
    95  --------------------------------------------------------
    96  
    97  To generate X.509 certificates to feed its MSP configuration, the application
    98  can use `Openssl <https://www.openssl.org/>`_. We emphasize that in Hyperledger
    99  Fabric there is no support for certificates including RSA keys.
   100  
   101  Alternatively one can use ``cryptogen`` tool, whose operation is explained in
   102  :doc:`getting_started`.
   103  
   104  `Hyperledger Fabric CA <http://hyperledger-fabric-ca.readthedocs.io/en/latest/>`_
   105  can also be used to generate the keys and certificates needed to configure an MSP.
   106  
   107  MSP setup on the peer & orderer side
   108  ------------------------------------
   109  
   110  To set up a local MSP (for either a peer or an orderer), the administrator
   111  should create a folder (e.g. ``$MY_PATH/mspconfig``) that contains six subfolders
   112  and a file:
   113  
   114  1. a folder ``admincerts`` to include PEM files each corresponding to an
   115     administrator certificate
   116  2. a folder ``cacerts`` to include PEM files each corresponding to a root
   117     CA's certificate
   118  3. (optional) a folder ``intermediatecerts`` to include PEM files each
   119     corresponding to an intermediate CA's certificate
   120  4. (optional) a file ``config.yaml`` to configure the supported Organizational Units
   121     and identity classifications (see respective sections below).
   122  5. (optional) a folder ``crls`` to include the considered CRLs
   123  6. a folder ``keystore`` to include a PEM file with the node's signing key;
   124     we emphasise that currently RSA keys are not supported
   125  7. a folder ``signcerts`` to include a PEM file with the node's X.509
   126     certificate
   127  8. (optional) a folder ``tlscacerts`` to include PEM files each corresponding to a TLS root
   128     CA's certificate
   129  9. (optional) a folder ``tlsintermediatecerts`` to include PEM files each
   130     corresponding to an intermediate TLS CA's certificate
   131  
   132  In the configuration file of the node (core.yaml file for the peer, and
   133  orderer.yaml for the orderer), one needs to specify the path to the
   134  mspconfig folder, and the MSP Identifier of the node's MSP. The path to the
   135  mspconfig folder is expected to be relative to FABRIC_CFG_PATH and is provided
   136  as the value of parameter ``mspConfigPath`` for the peer, and ``LocalMSPDir``
   137  for the orderer. The identifier of the node's MSP is provided as a value of
   138  parameter ``localMspId`` for the peer and ``LocalMSPID`` for the orderer.
   139  These variables can be overridden via the environment using the CORE prefix for
   140  peer (e.g. CORE_PEER_LOCALMSPID) and the ORDERER prefix for the orderer (e.g.
   141  ORDERER_GENERAL_LOCALMSPID). Notice that for the orderer setup, one needs to
   142  generate, and provide to the orderer the genesis block of the system channel.
   143  The MSP configuration needs of this block are detailed in the next section.
   144  
   145  *Reconfiguration* of a "local" MSP is only possible manually, and requires that
   146  the peer or orderer process is restarted. In subsequent releases we aim to
   147  offer online/dynamic reconfiguration (i.e. without requiring to stop the node
   148  by using a node managed system chaincode).
   149  
   150  Organizational Units
   151  --------------------
   152  
   153  In order to configure the list of Organizational Units that valid members of this MSP should
   154  include in their X.509 certificate, the ``config.yaml`` file
   155  needs to specify the organizational unit (OU, for short) identifiers. You can find an example
   156  below:
   157  
   158  ::
   159  
   160     OrganizationalUnitIdentifiers:
   161       - Certificate: "cacerts/cacert1.pem"
   162         OrganizationalUnitIdentifier: "commercial"
   163       - Certificate: "cacerts/cacert2.pem"
   164         OrganizationalUnitIdentifier: "administrators"
   165  
   166  The above example declares two organizational unit identifiers: **commercial** and **administrators**.
   167  An MSP identity is valid if it carries at least one of these organizational unit identifiers.
   168  The ``Certificate`` field refers to the CA or intermediate CA certificate path
   169  under which identities, having that specific OU, should be validated.
   170  The path is relative to the MSP root folder and cannot be empty.
   171  
   172  Identity Classification
   173  -----------------------
   174  
   175  The default MSP implementation allows organizations to further classify identities into clients,
   176  admins, peers, and orderers based on the OUs of their x509 certificates.
   177  
   178  * An identity should be classified as a **client** if it transacts on the network.
   179  * An identity should be classified as an **admin** if it handles administrative tasks such as
   180    joining a peer to a channel or signing a channel configuration update transaction.
   181  * An identity should be classified as a **peer** if it endorses or commits transactions.
   182  * An identity should be classified as an **orderer** if belongs to an ordering node.
   183  
   184  In order to define the clients, admins, peers, and orderers of a given MSP, the ``config.yaml`` file
   185  needs to be set appropriately. You can find an example NodeOU section of the ``config.yaml`` file
   186  below:
   187  
   188  ::
   189  
   190     NodeOUs:
   191       Enable: true
   192       # For each identity classification that you would like to utilize, specify
   193       # an OU identifier.
   194       # You can optionally configure that the OU identifier must be issued by a specific CA
   195       # or intermediate certificate from your organization. However, it is typical to NOT
   196       # configure a specific Certificate. By not configuring a specific Certificate, you will be
   197       # able to add other CA or intermediate certs later, without having to reissue all credentials.
   198       # For this reason, the sample below comments out the Certificate field.
   199       ClientOUIdentifier:
   200         # Certificate: "cacerts/cacert.pem"
   201         OrganizationalUnitIdentifier: "client"
   202       AdminOUIdentifier:
   203         # Certificate: "cacerts/cacert.pem"
   204         OrganizationalUnitIdentifier: "admin"
   205       PeerOUIdentifier:
   206         # Certificate: "cacerts/cacert.pem"
   207         OrganizationalUnitIdentifier: "peer"
   208       OrdererOUIdentifier:
   209         # Certificate: "cacerts/cacert.pem"
   210         OrganizationalUnitIdentifier: "orderer"
   211  
   212  Identity classification is enabled when ``NodeOUs.Enable`` is set to ``true``. Then the client
   213  (admin, peer, orderer) organizational unit identifier is defined by setting the properties of
   214  the ``NodeOUs.ClientOUIdentifier`` (``NodeOUs.AdminOUIdentifier``, ``NodeOUs.PeerOUIdentifier``,
   215  ``NodeOUs.OrdererOUIdentifier``) key:
   216  
   217  a. ``OrganizationalUnitIdentifier``: Is the OU value that the x509 certificate needs to contain
   218     to be considered a client (admin, peer, orderer respectively). If this field is empty, then the classification
   219     is not applied.
   220  b. ``Certificate``: (Optional) Set this to the path of the CA or intermediate CA certificate
   221     under which client (peer, admin or orderer) identities should be validated.
   222     The field is relative to the MSP root folder. Only a single Certificate can be specified.
   223     If you do not set this field, then the identities are validated under any CA defined in
   224     the organization's MSP configuration, which could be desirable in the future if you need
   225     to add other CA or intermediate certificates.
   226  
   227  Notice that if the ``NodeOUs.ClientOUIdentifier`` section (``NodeOUs.AdminOUIdentifier``,
   228  ``NodeOUs.PeerOUIdentifier``, ``NodeOUs.OrdererOUIdentifier``) is missing, then the classification
   229  is not applied. If ``NodeOUs.Enable`` is set to ``true`` and no classification keys are defined,
   230  then identity classification is assumed to be disabled.
   231  
   232  Identities can use organizational units to be classified as either a client, an admin, a peer, or an
   233  orderer. The four classifications are mutually exclusive.
   234  The 1.1 channel capability needs to be enabled before identities can be classified as clients
   235  or peers. The 1.4.3 channel capability needs to be enabled for identities to be classified as an
   236  admin or orderer.
   237  
   238  Classification allows identities to be classified as admins (and conduct administrator actions)
   239  without the certificate being stored in the ``admincerts`` folder of the MSP. Instead, the
   240  ``admincerts`` folder can remain empty and administrators can be created by enrolling identities
   241  with the admin OU. Certificates in the ``admincerts`` folder will still grant the role of
   242  administrator to their bearer, provided that they possess the client or admin OU.
   243  
   244  Channel MSP setup
   245  -----------------
   246  
   247  At the genesis of the system, verification parameters of all the MSPs that
   248  appear in the network need to be specified, and included in the system
   249  channel's genesis block. Recall that MSP verification parameters consist of
   250  the MSP identifier, the root of trust certificates, intermediate CA and admin
   251  certificates, as well as OU specifications and CRLs.
   252  The system genesis block is provided to the orderers at their setup phase,
   253  and allows them to authenticate channel creation requests. Orderers would
   254  reject the system genesis block, if the latter includes two MSPs with the same
   255  identifier, and consequently the bootstrapping of the network would fail.
   256  
   257  For application channels, the verification components of only the MSPs that
   258  govern a channel need to reside in the channel's genesis block. We emphasize
   259  that it is **the responsibility of the application** to ensure that correct
   260  MSP configuration information is included in the genesis blocks (or the
   261  most recent configuration block) of a channel prior to instructing one or
   262  more of their peers to join the channel.
   263  
   264  When bootstrapping a channel with the help of the configtxgen tool, one can
   265  configure the channel MSPs by including the verification parameters of MSP
   266  in the mspconfig folder, and setting that path in the relevant section in
   267  ``configtx.yaml``.
   268  
   269  *Reconfiguration* of an MSP on the channel, including announcements of the
   270  certificate revocation lists associated to the CAs of that MSP is achieved
   271  through the creation of a ``config_update`` object by the owner of one of the
   272  administrator certificates of the MSP. The client application managed by the
   273  admin would then announce this update to the channels in which this MSP appears.
   274  
   275  Best Practices
   276  --------------
   277  
   278  In this section we elaborate on best practices for MSP
   279  configuration in commonly met scenarios.
   280  
   281  **1) Mapping between organizations/corporations and MSPs**
   282  
   283  We recommend that there is a one-to-one mapping between organizations and MSPs.
   284  If a different type of mapping is chosen, the following needs to be to
   285  considered:
   286  
   287  - **One organization employing various MSPs.** This corresponds to the
   288    case of an organization including a variety of divisions each represented
   289    by its MSP, either for management independence reasons, or for privacy reasons.
   290    In this case a peer can only be owned by a single MSP, and will not recognize
   291    peers with identities from other MSPs as peers of the same organization. The
   292    implication of this is that peers may share through gossip organization-scoped
   293    data with a set of peers that are members of the same subdivision, and NOT with
   294    the full set of providers constituting the actual organization.
   295  - **Multiple organizations using a single MSP.** This corresponds to a
   296    case of a consortium of organizations that are governed by similar
   297    membership architecture. One needs to know here that peers would propagate
   298    organization-scoped messages to the peers that have an identity under the
   299    same MSP regardless of whether they belong to the same actual organization.
   300    This is a limitation of the granularity of MSP definition, and/or of the peer’s
   301    configuration.
   302  
   303  **2) One organization has different divisions (say organizational units), to**
   304  **which it wants to grant access to different channels.**
   305  
   306  Two ways to handle this:
   307  
   308  - **Define one MSP to accommodate membership for all organization’s members**.
   309    Configuration of that MSP would consist of a list of root CAs,
   310    intermediate CAs and admin certificates; and membership identities would
   311    include the organizational unit (``OU``) a member belongs to. Policies can then
   312    be defined to capture members of a specific ``OU``, and these policies may
   313    constitute the read/write policies of a channel or endorsement policies of
   314    a chaincode. A limitation of this approach is that gossip peers would
   315    consider peers with membership identities under their local MSP as
   316    members of the same organization, and would consequently gossip
   317    with them organization-scoped data (e.g. their status).
   318  - **Defining one MSP to represent each division**.  This would involve specifying for each
   319    division, a set of certificates for root CAs, intermediate CAs, and admin
   320    Certs, such that there is no overlapping certification path across MSPs.
   321    This would mean that, for example, a different intermediate CA per subdivision
   322    is employed. Here the disadvantage is the management of more than one
   323    MSPs instead of one, but this circumvents the issue present in the previous
   324    approach.  One could also define one MSP for each division by leveraging an OU
   325    extension of the MSP configuration.
   326  
   327  **3) Separating clients from peers of the same organization.**
   328  
   329  In many cases it is required that the “type” of an identity is retrievable
   330  from the identity itself (e.g. it may be needed that endorsements are
   331  guaranteed to have derived by peers, and not clients or nodes acting solely
   332  as orderers).
   333  
   334  There is limited support for such requirements.
   335  
   336  One way to allow for this separation is to create a separate intermediate
   337  CA for each node type - one for clients and one for peers/orderers; and
   338  configure two different MSPs - one for clients and one for peers/orderers.
   339  Channels this organization should be accessing would need to include
   340  both MSPs, while endorsement policies will leverage only the MSP that
   341  refers to the peers. This would ultimately result in the organization
   342  being mapped to two MSP instances, and would have certain consequences
   343  on the way peers and clients interact.
   344  
   345  Gossip would not be drastically impacted as all peers of the same organization
   346  would still belong to one MSP. Peers can restrict the execution of certain
   347  system chaincodes to local MSP based policies. For
   348  example, peers would only execute “joinChannel” request if the request is
   349  signed by the admin of their local MSP who can only be a client (end-user
   350  should be sitting at the origin of that request). We can go around this
   351  inconsistency if we accept that the only clients to be members of a
   352  peer/orderer MSP would be the administrators of that MSP.
   353  
   354  Another point to be considered with this approach is that peers
   355  authorize event registration requests based on membership of request
   356  originator within their local MSP. Clearly, since the originator of the
   357  request is a client, the request originator is always deemed to belong
   358  to a different MSP than the requested peer and the peer would reject the
   359  request.
   360  
   361  **4) Admin and CA certificates.**
   362  
   363  It is important to set MSP admin certificates to be different than any of the
   364  certificates considered by the MSP for ``root of trust``, or intermediate CAs.
   365  This is a common (security) practice to separate the duties of management of
   366  membership components from the issuing of new certificates, and/or validation of existing ones.
   367  
   368  **5) Blacklisting an intermediate CA.**
   369  
   370  As mentioned in previous sections, reconfiguration of an MSP is achieved by
   371  reconfiguration mechanisms (manual reconfiguration for the local MSP instances,
   372  and via properly constructed ``config_update`` messages for MSP instances of a channel).
   373  Clearly, there are two ways to ensure an intermediate CA considered in an MSP is no longer
   374  considered for that MSP's identity validation:
   375  
   376  1. Reconfigure the MSP to no longer include the certificate of that
   377     intermediate CA in the list of trusted intermediate CA certs. For the
   378     locally configured MSP, this would mean that the certificate of this CA is
   379     removed from the ``intermediatecerts`` folder.
   380  2. Reconfigure the MSP to include a CRL produced by the root of trust
   381     which denounces the mentioned intermediate CA's certificate.
   382  
   383  In the current MSP implementation we only support method (1) as it is simpler
   384  and does not require blacklisting the no longer considered intermediate CA.
   385  
   386  **6) CAs and TLS CAs**
   387  
   388  MSP identities' root CAs and MSP TLS certificates' root CAs (and relative intermediate CAs)
   389  need to be declared in different folders. This is to avoid confusion between
   390  different classes of certificates. It is not forbidden to reuse the same
   391  CAs for both MSP identities and TLS certificates but best practices suggest
   392  to avoid this in production.
   393  
   394  .. Licensed under Creative Commons Attribution 4.0 International License
   395     https://creativecommons.org/licenses/by/4.0/