Two Ways to Generate Crypto Materials in Hyperledger Fabric: Cryptogen and CA Server

Overview

One of the most asked questions on Hyperledger Fabric is about identity. A permissioned blockchain requires that an entity, be it a client, an administrator or a network component, must be first identified and permissioned before accessing a consortium network. Hyperledger Fabric uses several concepts like organization, membership service providers, digital certificate, which makes the understanding of the whole picture a little challenging for new learners. Here in this article again I try to elaborate these concepts through analyzing Test Network, a network example in fabric material, and the two different ways to generate the crypto material for these entities. I hope to give you another perspective on this topic.

Organization and Membership Service Provider

Hyperledger Fabric is always chosen to build a consortium network to address a business problem. The participants are usually business entities in this case. An example is a trade finance platform, where participants are mainly the banks, plus some governance or regulatory bodies. Hyperledger Fabric uses organizations to represent these participating entities. In the trade finance platform, each bank is an organization. A governance body is also another organization. This is how we understand organization from a business perspective.

  • know the identity of the private key owner (through information recorded in the certificate)
  • trust that the signer is the one claimed in the certificate (through verifying CA’s signature on the certificate, with the assumption that CA’s certificate is trusted).
A capture of a transaction showing identity of an entity (endorser) and the signature.
  • signature: produced by that endorser against the message in proposal response payload (collapsed).

Test Network

It is always too abstract if just reading the material without examples. Here we use Test Network from fabric samples as an example. Similar to First Network in previous releases, Test Network comes with a well-designed script in fabric v2.0. It is a three-organization design, with one orderer organization and two peer organizations.

Test Network: Organization and entities inside each organization
  • Network components, either orderers or peers
  • Network users, who represent the actual human or client application acting on the network

A Note about Directory Structure of Crypto Material

For those who have gained some experience in First Network in the previous releases or Test Network in v2.0, you may have noticed that the crypto material is always stored in a fixed directory structure.

crypto material of peer0.org1 is correctly mapped to peer0.org1 containers in docker-compose files

Generating Crypto Material using Cryptogen

Hyperledger Fabric provides a tool that crypto material can be generated with minimum configuration. The tool is bin/cryptogen. Working with a configuration file, the crypto material of Test Network is generated and the result is kept as the directory structure shown above. With that, we can bring up the consortium network with docker compose files.

Directory Structure

We first use ./network.sh script to bring up Test Network and make some observations on the directory structure.

cd test-network
./network.sh up
  • peers/: a directory holding a list of peers under Org1, and each peer has its own crypto material, of both identity and TLS
  • users/: a directory holding a list of network users under Org1, and each peer has its own crypto material, of both identity and TLS
  • tlsca/: a directory holding the TLS CA
  • msp/: it is the material joining a consortium network.
  • connection-org1.yaml and connection-org1.json: these are the connection profile files in different formats. They will be used in client applications.
Crypto material generated using cryptogen tool in Test Network

Configuration File

We have seen the result of cryptogen. Now we take a look at the configuration files, which tell cryptogen how to generate the crypto material shown above.

configuration for Orderer Organization in Test Network
configuration for Org1, a PeerOrganization in Test Network

Use of cryptogen

In the script network.sh, the crypto material is generated in this command.

cryptogen generate --config=<configuration_file> --output=<output_directory>

Discussion

Cryptogen by far is the simplest way for us to generate crypto material for typical network designs. No matter how many orderers we are to deploy (one for Solo, five for Raft, etc) in orderer organization, how many peers needed for each peer organization, or how many client users needed in each organization, we can specify the requirement in the configuration files and generate the material with a simple command.

Generating Crypto Material using CA Server

We see some limitations in using cryptogen. To gain more flexibility and make it more practical, a better way is to bring up a CA Server, and we can generate crypto material for entities according to our network design. This involves more steps, but provides a standard way to either generate crypto material that cryptogen cannot generate, or for future use if more network components and users are needed.

Overview

A CA Server is a software to generate crypto material on request. Inside a CA Server there is a CA, represented by a private secret key and a CA Certificate. Any certificates signed and issued by this CA is verifiable with the CA Certificate (or CA’s public key). CA’s private secret key and CA Certificate is the essence of a CA, while a CA Server is just a software tool to perform this signing.

Directory Structure and Content

As mentioned before, we need the same directory structure in order to match the docker-compose configuration. Therefore the result of using CA needs to be the same as the result after using cryptogen. This involves some name changing and file moving. Instead of repeating everything about the directory structure, here we highlight some difference on the content and process.

cd test-network
./network.sh up -ca
Crypto material generated using Fabric CA Server in Test Network

Fabric-CA Server

We have seen the result. Now we can take a look on the CA Server side, and locate the material inside CA Server.

The Org1 portion of docker-compose-ca.yaml configuration file
Material inside Fabric-CA Server, being mapped to localhost for inspection.
  • ca-cert.pem: the CA Certificate for Org1
  • tls-cert.pem: the TLS server certificate for CA Server, used when accessing the CA Server with TLS
  • fabric-ca-server.db: the database of the Fabric CA Server, recording the user registration and certificate issuance
  • IssuerPublicKey and IssuerRevocationPublicKey: the names are self-explanatory.

The Process in Detail

We follow the process executed in network.sh script. Here is the overall flow of generating crypto material using CA Server. For an organization,

  1. Use Fabric-CA Client to enroll a CA Admin.
  2. With the CA Admin, use Fabric-CA Client to register and enroll every entity (peer, orderer, user, etc) one by one to the Fabric-CA Server.
  3. Move the result material to the directory structure.
cd test-network
./network.sh down
# if you see permission error in removing some directories, perform the following
sudo rm -r organizations/fabric-ca/org1/msp/
sudo rm -r organizations/fabric-ca/org2/msp/
sudo rm -r organizations/fabric-ca/ordererOrg/msp/
IMAGE_TAG=latest docker-compose -f docker/docker-compose-ca.yaml up -d
mkdir -p organizations/peerOrganizations/org1.example.com/export PATH=$PATH:/home/ubuntu/fabric-samples/bin
export FABRIC_CA_CLIENT_HOME=${PWD}/organizations/peerOrganizations/org1.example.com/
fabric-ca-client enroll -u https://admin:adminpw@localhost:7054 --caname ca-org1 --tls.certfiles ${PWD}/organizations/fabric-ca/org1/tls-cert.pem
  • the CA name is ca-org1
  • the correct TLS server certificate for CA Server
NodeOUs:
Enable: true
ClientOUIdentifier:
Certificate: cacerts/localhost-7054-ca-org1.pem
OrganizationalUnitIdentifier: client
PeerOUIdentifier:
Certificate: cacerts/localhost-7054-ca-org1.pem
OrganizationalUnitIdentifier: peer
AdminOUIdentifier:
Certificate: cacerts/localhost-7054-ca-org1.pem
OrganizationalUnitIdentifier: admin
OrdererOUIdentifier:
Certificate: cacerts/localhost-7054-ca-org1.pem
OrganizationalUnitIdentifier: orderer
fabric-ca-client register --caname ca-org1 --id.name peer0 --id.secret peer0pw --id.type peer --id.attrs '"hf.Registrar.Roles=peer"' --tls.certfiles ${PWD}/organizations/fabric-ca/org1/tls-cert.pem
  • id.secret: peer0pw, this is the secret to be used when enrol this entity
  • id.type: peer, here is where we specify the type of this entity. The correct OU identifier will be set according to the config.yaml above.
  • id.attrs: “hf.Registrar.Roles=peer”
fabric-ca-client enroll -u https://peer0:peer0pw@localhost:7054 --caname ca-org1 -M ${PWD}/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/msp --csr.hosts peer0.org1.example.com --tls.certfiles ${PWD}/organizations/fabric-ca/org1/tls-cert.pem
  • the MSP location (local directory) to store the crypto material received
  • the host in the default CSR (in fabric-ca-client.yaml) is changed to peer0.org1.example.com. This is to override the default setting.
fabric-ca-client enroll -u https://peer0:peer0pw@localhost:7054 --caname ca-org1 -M ${PWD}/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls --enrollment.profile tls --csr.hosts peer0.org1.example.com --csr.hosts localhost --tls.certfiles ${PWD}/organizations/fabric-ca/org1/tls-cert.pem

Summary

In this article, we use Test Network to show the two different ways of generation crypto material for a consortium network. While cryptogen is a fast and easy way with minimum configuration to bring up a workable network, it has certain limitations and therefore is always considered for testing purposes. A more practical way for production is to bring up a CA server and generate the material according to one’s need in a consortium network. In the Test Network, we see how Fabric-CA Server is used as the CA Server, and how to use Fabric-CA Client to perform the whole process.

Visit http://www.ledgertech.biz/kcarticles.html for all my works. Reach me on https://www.linkedin.com/in/ktam1/ or follow me @kctheservant in Twitter.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store