Deploying and Using Fabric CA

Fabric CA is the certificate authority for Hyperledger Fabric. It provides the following functions: registering and enrolling users, and issuing and managing digital certificates.

Background

Until now I had always run the CA service by starting a downloaded CA image in a Docker container, and my application accessed the CA server through the interfaces built into the Node SDK. This time I tried deploying the CA service by hand.

Fabric CA consists of a server component and a client component. The CA server (fabric-ca-server) can be thought of as a web service: once you run the binary compiled from the Go code, it listens on a port and handles the requests it receives.

The CA client (fabric-ca-client) is simply a program that sends requests to the CA server. Running the compiled binary with different arguments sends the corresponding HTTP requests to the CA server to carry out a range of operations.

Prerequisites

1. Install Go, configure the GOPATH environment variable, and download and set up Docker
2. Install libtool and libltdl-dev

sudo apt install libtool libltdl-dev

Installing and Starting the CA from the Command Line

1. Download the source from GitHub and compile it directly

go get -u github.com/hyperledger/fabric-ca/cmd/fabric-ca-server
go get -u github.com/hyperledger/fabric-ca/cmd/fabric-ca-client

The go get command fetches the source automatically and compiles it into $GOPATH/bin. On my machine that is ~/go/bin, where the compiled executables fabric-ca-server and fabric-ca-client show up.

Next, initialize and start fabric-ca-server. You need to set a name and password for an admin user

fabric-ca-server init -b admin:adminpw
fabric-ca-server start -b admin:adminpw

This fails with panic: Version is not set for fabric-ca library, which may be related to the version of fabric-ca that was downloaded (the latest at the time was v1.1).

1. Compile it manually
   Since the version downloaded directly from GitHub throws an error, you can compile a specific version of fabric-ca-server yourself.

First, download the fabric-ca source and switch to the corresponding version:

git clone https://github.com/hyperledger/fabric-ca.git
git checkout v1.1.0

Then compile it in the fabric-ca directory

make fabric-ca-server
make fabric-ca-client

This produces fabric-ca-server and fabric-ca-client in the fabric-ca/bin directory. Next, go into the bin directory and initialize the CA server:

fabric-ca-server init -b admin:adminpw                 

Initialization generates the following in the directory:

• msp: contains keystore, the CA server's private key
• ca-cert.pem: the CA server's certificate
• fabric-ca-server.db: SQLite, the embedded database the CA uses by default
• fabric-ca-server-config.yaml: the CA server's config file

Then start the CA server

fabric-ca-server start -b admin:adminpw                 

The CA server starts listening, by default on http://0.0.0.0:7054.

Installing and Starting the CA with a Docker Image

Besides running the CA server program directly, you can also start the CA in a Docker container. The fabric-ca image contains both the fabric-ca-server and fabric-ca-client components.

1. Download the fabric-ca image directly
First, you can pull the fabric-ca image directly from Docker Hub:

docker pull hyperledger/fabric-ca:x86_64-1.1.0

Start the image with the docker-compose.yml file, which is in fabric-ca/docker/server (you need to clone fabric-ca from GitHub). Go into that directory and run:

docker-compose up

This starts the CA container, and pulls the image automatically if it does not exist yet. The CA config file, certificate and private key, database file, and so on are generated in the .../server/fabric-ca-server directory (they are generated inside the CA container and mapped to the host), and the server starts listening on its port.

2. Build the Docker image manually
Besides pulling the fabric-ca image from Docker Hub, you can also build the image from source.
Run the following in the fabric-ca directory:

make docker

This produces four images, fabric-ca, fabric-ca-tool, fabric-ca-peer, and fabric-ca-orderer, saved in fabric-ca/build/image. From there, the CA node is started from the docker-compose.yml file, the same way as above.

Using Fabric CA

There are two ways to access the Fabric CA server: the client tool (fabric-ca-client) and the RESTful API. Under the hood, the client tool is also implemented by calling the server's RESTful API. Here I use the client tool.

First, initialize and start the CA server following the steps above (run fabric-ca-server or start the CA container). If you have already downloaded fabric-ca-client, change to its directory and you can start working (not needed if it is already on your PATH). If the CA server runs in a Docker container and you have not downloaded the client tool, you can test from inside the container (the CA image includes both the server and client components). fabric-ca-client is located in /usr/local/bin and is already on the PATH. To enter the container:

docker exec -it fabric-ca-server bash

Below, I test fabric-ca by running the compiled executables directly. First, start the CA server in one terminal:

fabric-ca-server start -b admin:adminpw

Registering a user takes two steps: register and enroll. Enrollment requires the secret obtained at registration, and registering a user requires a registrar user. So we first enroll the admin user set at startup (the admin's enrollment secret was already set at startup), and then use this admin user to register other users.

Use the CA client in another terminal. Before enrolling, set the environment variable for the directory where certificates are stored.

export FABRIC_CA_CLIENT_HOME=$HOME/ca
fabric-ca-client enroll -u http://admin:adminpw@localhost:7054

A fabric-ca-client-config.yaml config file is now generated in the ~/ca directory, along with an msp directory that holds the admin's certificate and private key. With the admin user successfully enrolled, use admin as the Registrar to register a new user:

fabric-ca-client register --id.name Jim --id.type user --id.affiliation org1.department1 --id.attrs 'hf.Revoker=true,foo=bar'

The client receives a password. Use this enrollment secret to enroll the user:

fabric-ca-client enroll -u http://Jim:IGIMqptUPBRc@localhost:7054 -M $FABRIC_CA_CLIENT_HOME/Jim

The new user is now enrolled and has its own certificate and private key.

Summary

To sum up, there are two ways to deploy the CA service manually:

• The first is to run the compiled executables directly from the command line. You can fetch and compile them automatically with the go get command (the latest version throws an error), or fetch the source manually, switch to the right version, and compile it yourself. Then initialize and start the CA server from the command line;
• The second is to run the fabric-ca image in a Docker container. The image contains the compiled executables. You can download it directly from Docker Hub or build it manually with make docker in the fabric-ca directory, then start the CA container with the docker-compose command.