Recently I posted articles on how to deploy a Business Network Archive (.bna) file to your IBM Blockchain Platform and how to build a small blockchain application using the IBM BLUEMIX, both of which garnered quite a few positive reviews.
I was flooded with requests for more similar articles on IBM Business models and services, out of which the most common request was for Membership Service Providers (MSP) using IBM Hyperledger.
So in this article, I will give you a direct, yet comprehensive run through on how to setup an MSP channel for your business using the IBM Hyperledger fabric. Plus, I will not just provide details on the channel setup, but will also tell you about the best practices for MSPs.
What is Membership Service Providers (MSP)?
It would be very much recommended and rather sensible for you to understand what an MSP really is and what is does, before learning how to setup an MSP channel for your business.
So a Membership Service Provider (MSP) is quite understandably a component that aims to provide an abstraction of an architecture for membership operations.
These MSPs abstract away all possible protocols cryptographic mechanisms behind issuing and validating certificates and further user authentication. This is a very essential aspect for businesses whose success relies heavy on the membership counts and related subscriptions.
An MSP involves two key aspects for its proper functioning.
- The rules by which Membership identities are governed (Identity validation).
- Membership authentication (Signature generation and verification).
The IBM Hyperledger Fabric is a blockchain network that can be governed by one or more MSPs. This one feature provides seamless modularity of membership operations and also intervention and interoperability across different membership standards and architectures. The IBM Hyperledger is commonly touted as the best, most reliable and most popularly used tool for setup of MSP implementations.
One important prerequisite before setting up the MSP instance is that, its configuration needs to be pre specified locally at each peer and orderer. This is important because it will enable peer and orderer signing. This action will also enable peer, orderer, client identity validation and other respective signature verifications or authentications by and for all channel members.
Here is a direct step by step list down of what needs to be done.
- First and foremost, each MSP requires a name to be specified in order to reference that particular MSP in the network. For example, msp1, org2, and org3.divA, etc. Please clearly understand that this is the name under which the membership rules of an MSP representing a consortium, brand, organization or even an organization division is to be referenced in a channel. This aspect is also commonly referred to as the MSP Identifier or MSP ID. These MSP Identifiers must be unique per MSP instance. In case two MSP instances with the same identifier name are detected at the system channel genesis, the orderer setup is very much likely to fail.
- There is also a feature for default implementation of MSP. If chosen, a set of parameters are required to be specified to allow for identity (Certificate) validation and signature verification. These parameters are deduced and sanctioned by RFC5280, and include the following.
- A list of self-signed or self-attested (X.509) certificates to constitute the “Root of trust” (ROT).
- A list of X.509 certificates that will represent intermediate CAs this provider considers for the respective certificate validation. Moreover, these certificates need to be certified by exactly one of the certificates listed under the ROT.
- A list of X.509 certificates with a corresponding verifiable certificate path to exactly one of the certificates of the ROT. This path certificate will then represent the administrators of the particular MSP. The administrators of these certificates have the authority to request changes like root CAs, intermediate CAs, etc. to this MSP configuration.
- A list of Organizational Units that, valid and recognized members of this MSP must include in their X.509 certificate. This configuration parameter is optional and is used mostly when multiple organizations coincidentally leverage the same root of trust, intermediate CAs, etc.
- A list of certificate revocation lists (CRLs) each corresponding to exactly one of the valid intermediate or root MSP Certificate Authorities. This again is an optional parameter
- A list of self-signed (X.509) certificates to constitute the TLS root of trust. This certification is necessary for the authentication and validation of the TLS certificate.
- A list of X.509 certificates to represent intermediate TLS CAs this provider considers. These certificates are again, optional parameters and need to be certified by exactly one of the certificates in the TLS ROT.
Valid and authorized identities for the MSP instance are required to satisfy the following list conditions:
- Your MSP instance should be in the form of X.509 certificates with a verifiable certificate path to exactly one of the root of trust certificates as mentioned in the points above.
- Your MSP instance should not be included in any CRL.
- It is necessary that your MSP instance lists one or more of the Organizational Units of the MSP configuration in the OU field of their X.509 certificate structure.
If you have any confusion or doubts regarding the validity of identities in the current MSP implementation, then kindly refer to MSP Identity Validity Rules for more information.
You will need to specify the following list of aspects as well for the MSP to enable the node on which it is instantiated to sign or authenticate, in addition to the verification related parameters:
- The signing key used for signing by the node. Please note that currently only ECDSA keys are supported.
- The node’s X.509 certificate that is a valid identity under the verification parameters of this MSP.
Always remember that MSP identities never expire. These can only be revoked by adding them to the appropriate CRLs. However, currently there is no support for enforcing revocation of TLS certificates.
How to generate MSP certificates and their signing keys?
Now that I have given you the basic outline of the important rules and requirements for the initial setup and validation of your MSP instance, let us get right into generating the MSP certificates and signing kes.
To feed the MSP configuration the application can use Openssl, to generate X.509 certificates. Please make a note that there is no support for certificates including RSA keys in the Hyperledger Fabric.
You can use “Cryptogen tool” to get started. Its operation and features is explained in Getting Started.
The Hyperledger Fabric CA can also be used to generate the signing keys and certificates needed to configure and establish an MSP.
MSP setup on the peer & orderer side
Now the next important step is to set up a local MSP for either a peer or an orderer. For this particular action, the administrator should create a folder that contains six subfolders and a file. You can name the folder something like
Here is the list of subfolders that should be created.
- admincerts: This is a folder to include PEM files that should correspond to an administrator certificate.
- cacerts: This is a folder to include PEM files that should correspond to a root CA’s certificate.
- intermediatecerts: This is a folder to include PEM files that correspond to an intermediate CA’s certificate. (Optional)
- yaml: This is a file to include information on the considered OUs. The latter aspects are defined as pairs of <Certificate, OrganizationalUnitIdentifier> entries of a yaml array called OrganizationalUnitIdentifiers. Here the Certificate represents the relative path to the certificate of the root or intermediate certificate authority that should be considered for certifying members of this OU. For example ./cacerts/cacert.pem. An OrganizationalUnitIdentifier represents the actual string as expected to appear in X.509 certificate OU-field. For example “COP”. (Optional)
- crls : This is a folder to include the all the considered CRLs. (Optional)
- keystore: This is a folder to include a PEM file with the node’s signing key. As mentioned earlier in this article, please note that currently RSA keys are not supported.
- signcerts: This is a folder to include a PEM file with the node’s X.509 certificate
- tlscacerts: This is a folder to include each and every PEM files corresponding to a TLS root CA’s certificate. (Optional)
- tlsintermediatecerts: This is a folder to include each and every PEM files corresponding to an intermediate TLS CA’s certificate. (Optional)
While setting up the configuration file of the node, one needs to necessarily specify the path to the mspconfig folder and the MSP Identifier of the node’s MSP. The path to the mspconfig folder should be carefully overridden if needed and should preferably be relative to FABRIC_CFG_PATH and is provided as the value of parameter mspConfigPath for the peer and the parameter LocalMSPDir for the orderer.
Parameters localMspId for the peer and LocalMSPID for the orderer are provided as a value for the identifier of the node’s MSP. These are variables that can be overridden via the environment using the CORE prefix for peer and the ORDERER prefix for the orderer. For example CORE_PEER_LOCALMSPID for the peer and ORDERER_GENERAL_LOCALMSPID for the orderer. One needs to generate and provide the genesis block of the system channel to the orderer for the orderer setup.
The MSP configuration of this block also requires Reconfiguration. Reconfiguration of a “local” MSP can only be done manually and requires the peer or orderer process to be restarted.
Channel MSP setup
Now let’s talk about the most important stage, the genesis of the system. This stage includes final and thorough verification parameters of all the MSPs that appear in the network need to be specified. These are the verification parameters that will be included in the system channel’s genesis block.
If you carefully recall from one of the above sections that, the MSP verification parameters consist of the MSP identifier, the root of trust (ROT) certificates, intermediate CA and admin certificates, CRLs as well as all OU specifications. Now this system genesis block is provided to the orderers at their setup phase. This will then allow the orderers to authenticate channel creation requests.
Please keep in mind that if the latter includes two MSPs with the same identifier, the orderers are at liberty to reject the system genesis block. This would consequently mean that the bootstrapping of the entire network would fail.
It is strongly recommended that the responsibility of the application to ensure that correct MSP configuration information is included in the genesis blocks of a channel prior to instructing one or more of their peers to join the channel. The verification components of only the MSPs that govern a channel should preferably reside in the channel’s genesis block for an application channel.
One can override and configure the channel MSPs by including the verification parameters of MSP in the mspconfig folder with the help of the configtxgen tool when bootstrapping a channel. This is recommended while setting that path in the relevant section in configtx.yaml.
Last but not the least, reconfiguration of an MSP on the channel, including announcements of the certificate revocation lists associated to the CAs of that MSP can be directly achieved through the creation of a config_update object by the owner of one of the administrator certificates of the targeted MSP. The client application managed by the admin would then ultimately announce this update to the channels in which this MSP appears.
Here I have given you an easy to understand, step by step guide to setup an MSP channel. If followed correctly, you can easily setup your MSP channel. If you have any doubts regarding the procedure, drop your queries in the comments below and I shall be happy to help.