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/