Certificate Revocation in Fabric CA Server

Overview

This article shows how to revoke a user in a fabric network such that the user cannot access fabric network and chaincode any more. We first give a high-level walk-through of the process, and later use Test Network to demonstrate the revocation. The script provided in Test Network makes bringing Fabric CA servers much easier and we can use the material to perform the demonstration.

Revisit: Bring Up Test Network with Fabric CA Server

Here we first revisit what happens when we bring up the Test Network with Fabric CA Server. Script gives us everything by this simple command.

./network.sh up createChannel -ca

The details of this process can be summarized in the following steps.

  1. Bring up three Fabric CA Servers, for Org1, Org2 and OrdererOrg, respectively.
  2. For Org1, enrol the bootstrap admin with Fabric CA Client.
  3. Use bootstrap admin to register entities for Org1, including peer0 (peer), org1admin (admin) and user1 (client).
  4. Enroll these entities to obtain all their msp materials. These materials are then used to bring up the network.
  5. Repeat step 2–4 for Org2 and OrdererOrg.
  6. Bring up the peers and orderer, create channel material and join the peers of both orgs to mychannel.
Test Network setup (only Fabric CA Server for Org1 is shown)

As a result, we see the network is ready for use.

To know more about Fabric-CA-Server, we can use Fabric-CA-Client.

export FABRIC_CA_CLIENT_HOME=${PWD}/organizations/peerOrganizations/org1.example.com/fabric-ca-client identity list --tls.certfiles ${PWD}/organizations/fabric-ca/org1/tls-cert.pem
Identities registered in Fabric CA Server for Org1

There are four entities registered in Fabric CA Server of Org1. They are the bootstrap admin, peer0 (peer), org1admin (admin) and user1 (client). A note about the two “admins” in Fabric-CA-Server

  • (bootstrap) admin: This is the admin of Fabric-CA-Server. We use this admin material in Fabric-CA-Client for entity registration (e.g. peer0, org1admin and user1) in Fabric-CA-Server. Later in our demonstration we will use this admin in Fabric-CA-Client to revoke user1.
  • org1admin: This is the admin of Org1 in the consortium network (Test Network). For example, create and update channel, install, approve and commit chaincode, etc. In the certificate it contains OU=admin.

Therefore, don’t mix these two “admins”. It is the bootstrap admin creates org1admin, and when dealing with fabric network, we are using only org1admin while bootstrap admin is not required. We will see both are required when revoking an entity.

Process of Revoking an Entity

This is the quick introduction about revoking an entity (certificate or identity) in the official documentation. In short, we can divide it into two parts.

  1. In Fabric-CA-Server, revoke an entity by its ID. A certificate revocation list (CRL) is created
  2. Update the channel configuration to include the CRL.

Part 1: Revoke an entity in Fabric-CA-Server

This is done by the bootstrap admin in Fabric-CA-Server. The admin has attributes hf.Revoker and hf.GenCRL. These are required when we revoke an entity in Fabric-CA-Server.

The revocation is done through this command.

fabric-ca-client revoke -e user1 --gencrl --tls.certfiles ${PWD}/organizations/fabric-ca/org1/tls-cert.pem

The result is an update on the Fabric-CA-Server database (user1 is marked revoked). The option will create a CRL including this revoked user1. We can separate this into two parts: revoke entities first and later generate CRL. Here we complete these into one command.

Part 1: Revoke user1 in Fabric CA Server of Org1

Part 2: Update channel configuration

The CRL generated in the previous part needs to be included in the channel configuration. This is done through a configuration update. Here we first construct the configuration update transaction, and then have Admin@org1 (org1admin) sign and submit the transaction. When everything works fine, User1@org1 is no longer able to access the chaincode function.

We first take a look at the configuration block fetched from the channel. Inside we find an empty revocation list (line 201).

Revocation_List is inside Org1MSP, currently empty

To revoke an entity, we paste the CRL (encoded in base64) into this list.

Include base64-encoded CRL in revocation_list

With this, we can go through the same process to compute the delta (update) between two configurations, and add the envelope upon the delta before converting it back to a transaction ready for signing. The detail process can be referred to in this example (link).

Note that this update is only relevant to Org1. Therefore only Admin@org1 is needed to sign this update. When this completes, the revocation comes into effect, and we no longer can use User1@org1.

Part 2: Update channel configuration with CRL generated from Fabric CA Server

Demonstration

Part 0: Bring Up Test Network and Deploy SACC

Bring up mychannel and deploy SACC for testing

./network.sh up createChannel -ca./network.sh deployCC -ccn mycc -ccp ../chaincode/sacc/

Set environment variables for org1. Here is mine. You can see the default msp I am using is Admin@org1.

Invoke chaincode SACC.

peer chaincode invoke -o localhost:7050 --ordererTLSHostnameOverride orderer.example.com --tls true --cafile $ORDERER_CA -C mychannel -n mycc --peerAddresses localhost:7051 --tlsRootCertFiles ${PWD}/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt --peerAddresses localhost:9051 --tlsRootCertFiles ${PWD}/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt -c '{"Args":["set","name","Peter"]}'

Query chaincode with User1@org1.

CORE_PEER_MSPCONFIGPATH=/Users/kctam/fabric220/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp peer chaincode query -C mychannel -n mycc -c '{"Args":["get","name"]}'

We get back the right result. User1@org1 as a client can query chaincode function.

User1@org1 can query chaincode function

Part 1: Revoke User1@org1 in Fabric CA

We use a single command to revoke user1 and generate CRL.

export FABRIC_CA_CLIENT_HOME=${PWD}/organizations/peerOrganizations/org1.example.com/fabric-ca-client revoke -e user1 --gencrl --tls.certfiles ${PWD}/organizations/fabric-ca/org1/tls-cert.pem

We see the CRL generated. This is the CRL file.

We need the base64-encoded version of this file for later configuration update.

Part 2: Update channel configuration

First fetch the configuration block from mychannel

peer channel fetch config -c mychannel

Perform the required editing and compute the configuration update transaction. The detail process can be referred to in this example (link).

configtxlator proto_decode --input mychannel_config.block --type common.Block --output mychannel_config.jsonjq .data.data[0].payload.data.config mychannel_config.json > config.jsonjq --arg new $(cat crl_base64) '.channel_group.groups.Application.groups.Org1MSP.values.MSP.value.config.revocation_list? += [$new]' config.json > modified_config.jsonconfigtxlator proto_encode --input config.json --type common.Config --output config.pbconfigtxlator proto_encode --input modified_config.json --type common.Config --output modified_config.pbconfigtxlator compute_update --channel_id mychannel --original config.pb --updated modified_config.pb --output crl_update.pbconfigtxlator proto_decode --input crl_update.pb --type common.ConfigUpdate --output crl_update.jsonecho '{"payload":{"header":{"channel_header":{"channel_id":"mychannel", "type":2}},"data":{"config_update":'$(cat crl_update.json)'}}}' | jq . > crl_update_in_envelope.jsonconfigtxlator proto_encode --input crl_update_in_envelope.json --type common.Envelope --output crl_update_in_envelope.pb

Then sign the update transaction with Admin@org1.

peer channel update -f crl_update_in_envelope.pb -c mychannel -o localhost:7050 --ordererTLSHostnameOverride orderer.example.com --tls true --cafile $ORDERER_CA

With this, the configuration update is complete, and User1@org1 is revoked.

Part 3: Test

Now query chaincode function with both Admin@org1 and User1@org1.

peer chaincode query -C mychannel -n mycc -c '{"Args":["get","name"]}'CORE_PEER_MSPCONFIGPATH=/Users/kctam/fabric220/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp peer chaincode query -C mychannel -n mycc -c '{"Args":["get","name"]}'

The revoked entity User1@org1 cannot access chaincode any more.

Discussion

Always think of the operations of Fabric CA and Fabric network are separate. In normal cases, after Fabric CA generates all the crypto materials and those crypto materials are properly installed in the fabric network, Fabric CA is no longer needed. When revoking an entity, we have to first revoke the entity in Fabric CA and thus the certificate revocation list (CRL) is generated. Then update the channel configuration with this CRL in the fabric network.

In Fabric CA, the bootstrap admin has the rights to revoke certificates and generate the CRL.

In fabric network, it is the organization admin (in our case Admin@org1) having the authorization to perform this revocation configuration update. If the update is signed by either non admin (e.g. User1@org1) or by admin of another organization (Admin@org2), the update fails due to signature policy.

Finally, the configuration update is made on channel level. That is to say, User1@org1 can still work in other channels. Make sure Admin@org1 updates the revocation list in all relevant channels. For example, a new channel newchannel is created and chaincode fabcar is deployed. We can see the User1@org1 can still query chaincode.

User1@org1 can still query chaincode functions in another channel

Summary

I hope this article provides more insight about certificate revocation in Fabric CA. Special thanks to Roland (Bole Roland) as he raised this and made some trials on the 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