Hyperledger Fabric – Part 2
September 13, 2018
Author: Akarsh Agarwal
The Hyperledger Fabric project by IBM provides an easy plug-n-play interface for the users to attach their custom Certificate Authority(CA) Server. This has been actively made possible in the newer version of Hyperledger Fabric v1.0 as opposed to v0.6. There is support for this functionality in older versions, but they have been made more easily integrated in the newer release.
This article is about the steps needed to setup your own CA Server and register/enroll new users into your database. The server provides the public/private key pair as a response to enrolling the user into the database. If you need help to configure the requirements to download Hyperledger, check out the first article in this three part tutorial series to learn Hyperledger.
The fabric-ca project can be downloaded from the official gerrit codebase using the following command. This will download the required files into your directory. The directory structure is important for the fabric-ca to work. The picture below is a sample of where to place the fabric-ca directory:
git clone https://gerrit.hyperledger.org/r/fabric-ca
To make the above screenshot more clear, the fabric-ca directory should be placed inside the GOPATH variable of your system. To set the GOPATH locally run the following command:
The directory structure that follows the GOPATH is GOPATH -> src -> github.com -> hyperledger -> fabric-ca. It is recommended that you follow the same directory structure to avoid any errors that might arise during building or compiling the code.
Now, as we have downloaded the files into the required location, we need to build the fabric-ca server and add the path to the executable to have the command available across the system in the terminal. To build the fabric-ca server, go to the root directory of fabric-ca, i.e., inside the fabric-ca directory and run the following command and you should see the screenshow below.
When the above command finishes, the output should be similar to the one shown above. It might take from a few seconds to a minute so be patient. To check whether you have the executable or not, list the contents of the directory “bin” and there should be a new file, in a different color, which is the executable.
Now, that we have the executable, we need to be able to access it from anywhere in the system. To do this we need to append the directory of fabric-ca to the PATH variable in the .bashrc file. The command to edit the .bashrc file is:
sudo nano ~/.bashrc
Next, append the following line at the bottom of the file:
Save the file and close it. Now, we need to refresh the variables to be able to access the fabric-ca command from anywhere. The command to do this is:
To check whether the fabric-ca-server command works or not, just type in the following command and you should see the output below returned to your terminal.
If you see any other output from the one displayed here, maybe there is some error in the installation and you might want to revisit the starting of the tutorial again.
Please ensure that, this documentation is the basic installation of the Fabric-CA service. More tweaking and settings can be found under the section of Fabric-CA Setup, at the official documentation of Hyperledger Fabric.
Fabric-CA Server Setup
The Fabric-CA Server acts as our custom CA to register and enroll new users, as well as existing users into the database. The server sends the key pair, when trying to enroll an already registered user.
To get started, we set-up a new directory for our work environment, so as to not disturb the original files. To create a new directory you can name it whatever you like. Here is what I’ve done below:
For our server to save our files to the current directory, we need to set-up a new environment variable. Call this environment variable FABRIC_CA_SERVER_HOME to follow along with the tutorial. Set this variable to the current directory adding the following lines to the .bashrc file at the end of the file:
I assume that you have set your FABRIC_CA_SERVER_HOME as your current directory, for the rest of the Fabric-CA Server Setup.
We need some configuration files, but first we need a pair of keys for the server to ensure the client is able to contact the right server. We use the following commands to generate the public/private key pair. Here, ca-cert.pem is the public key and ca-key.pem is the private key.
Now that we have our private and public keypair, we run the following command to auto-initialise all the config files and auto-create the keys. In the command, the ‘-b “admin:adminpw” ‘ initialises our bootstrap user for the database. A user which will be used to login the first time we want to start using our system. Now, after you run the command, you shall see the following output:
fabric-ca-server init -b “admin:adminpw”
From the above output, you can make out that we have the keys and the configuration files auto-generated for us by the Fabric-CA. Also, we see another file, fabric-ca-server.db. This file stores all the users that are currently registered with the Fabric-CA server. This is by-default a SQLITE3 database, however you are able to configure the fabric-ca-server-config.yaml file to use either a PostGreSQL or a Mysql database instead.
We have configured all of our files now, but it is important to understand the various fields in the config file before we run our first server. These fields are important and the documentation is given in the config file. The explanation of each field is below.
Config File Variables
- The “port” field defines on which port to run the server. By-default the port is 7054.
- The “debug” field is for logging while working in development environment.
- If your server is run on a HTTPS protocol, the “tls” should be enabled, as we are working on localhost, the default value is always “false”.
- We define the keys to be used by the server for signing the client keys, in the “certfile” and “keyfile” section. This variable is mainly used, when we know that the CA and the server are two different entities, but here, the server is itself the CA, so we put the server’s keys in the ca’s keys.
- Max_enrollments defines how many users can be enrolled using the same password. If is set to 0, it can be infinitely done, but suppose it is set to 1, it will allow a user to enroll only once.
- The next section defines the database we are going to use. By-default, Hyperledger Fabric-CA provides support for 3 types of databases, namely, Sqlite, Postgres and Mysql. You can configure any of the three, but default configuration is “sqlite3” for this tutorial. More can be found about configuring the other two, on the documentation of Hyperledger Fabric.
- The LDAP section we are going to skip and keep the value to the default as it is out of the scope of this tutorial.
- The affiliations section defines the organizations and departments with which your user is going to be associated to classfiy different types of users.
- Signing section is used to define what is the time period for the validity of the client’s signed certificates and what are the other usages of server certificate used in the configuration.
- “CSR” section is used to create “Certificate Signing Request” required to generate CA certificates, so as to put in the default details.
- The last section we have is the “crypto”, which defines what type of algorithm the server should use and other cryptographic terms. This is also left as it is.
Now, that we have all the files required, our server is ready to be initiated. Use the command below to start your server.
fabric-ca-server start -b “admin:adminpw”
If everything goes right, you should see the following output from your terminal.
Now, our localhost Fabric-CA Server is up and running. Congrats for achieving this milestone. Next we shall move onto setting up the Fabric-CA Client, to enable it to communicate it with our localhost.
If you have any doubts or errors, please email firstname.lastname@example.org and we shall get back to you as soon as possible, with a possible solution.
MLG Blockchain is a blockchain development and consulting firm based in Toronto that is focused on building next generation applications using blockchain and smart contract technology. View all our blockchain development tutorials at www.mlgblockchain.com/learn.html.