1.0 Introduction
This article describes how to integrate Fortanix Data Security Manager (DSM) with Hyperledger Fabric. Hyperledger Fabric allows using HSM to store private keys used for various Fabric operations. It also allows users to configure BCCSP (Blockchain Cryptographic Service Provider) with HSM using the PKCS#11 Standard API. This document describes configuring the PKCS#11 client provided by Fortanix with Hyperledger Fabric.
2.0 Prerequisites
- Set up Go using the official document from https://go.dev/dl/.
- Set up Docker using the official documentation https://docs.docker.com/engine/install/ubuntu.
- Ensure the system has installed the following packages: GIT, OpenSSL, GNU Compiler Collection (GCC), and Make.
- The Fortanix DSM integration with Hyperledger Fabric is tested for the following configurations:
- Fabric-CA 1.5.5
- Fortanix PKCS#11 client 4.8.2070
- Docker version 20.10.17, build 100c701
- Go 1.18.3
- Host OS Ubuntu 20.04.4 LTS (Focal Fossa)
- Container OS Ubuntu 20.04 LTS
3.0 References for Setup
- Refer to https://hyperledger-fabric-ca.readthedocs.io/en/latest/users-guide.html for setting up the Hyperledger Fabric network and other elements.
- For Fortanix DSM PKCS # 11 Library, go to https://support.fortanix.com/hc/en-us/articles/360016160451-Clients-PKCS-11-Library.
- This document covers the integration of Fortanix DSM with Hyperledger Fabric and provides a minimal example of the Hyperledger Fabric setup. Please refer to the official docs for production setup.
4.0 Set Up Fortanix PKCS#11 Client
- Get the PKCS#11 DEB package from the following link (tested with Fortanix DSM version 4.8.2070). https://support.fortanix.com/hc/en-us/sections/4408769080724-PKCS-11
- Use the following command to install the client on the host system.
sudo dpkg -i <pkg.deb>
- The DEB installer copies the Fortanix DSM PKCS#11 shared object file (also called a library or module) to the location
/opt/fortanix/pkcs11/fortanix_pkcs11.so
. - The shared object file is mounted to the docker container as explained in the section “Configure and Start the Hyperledger Fabric CA Server”.
5.0 Build Hyperledger Fabric CA with PKCS#11 Enabled
- Get the source code for Fabric CA at https://github.com/hyperledger/fabric-ca.
- The default Dockerfile of Hyperledger Fabric CA uses Alpine Linux as the base image and for compiling the Fabric CA. The Fortanix DSM PKCS#11 client does not currently support Alpine Linux. Changing the OS to Ubuntu enables you to use the client.
ARG GO_VER
ARG ALPINE_VER
FROM golang:1.18.5-bullseye as builder
ARG GO_LDFLAGS
ARG GO_TAGS
RUN apt update && apt install -y build-essential musl git;
ADD . /build/fabric-ca
WORKDIR /build/fabric-ca
RUN go install -tags "${GO_TAGS}" -ldflags "${GO_LDFLAGS}" \
github.com/hyperledger/fabric-ca/cmd/fabric-ca-server \
&& go install -tags "${GO_TAGS}" -ldflags "${GO_LDFLAGS}" \
github.com/hyperledger/fabric-ca/cmd/fabric-ca-client
FROM ubuntu:20.04
RUN apt update && apt install -y build-essential musl ca-certificates;
ENV FABRIC_CA_HOME /etc/hyperledger/fabric-ca-server
COPY --from=builder /go/bin /usr/local/bin
EXPOSE 7054
CMD fabric-ca-server start -b admin:adminpw - Build the container image.
GO_TAGS=pkcs11 make docker
- The following images will be created.
REPOSITORY TAG IMAGE_UD CREATED SIZE
hyperledger/fabric-ca 1.5.5 b52c013d8c00 6 days ago 434MB
hyperledger/fabric-ca amd64-1.5.5 b52c013d8c00 6 days ago 434MB
hyperledger/fabric-ca latest 6b52c013d8c00 6 days ago 434MB
6.0 Set Up Fortanix DSM - Create Account, Group, and App
This section explains how to create an app and copy its API key to mount the PKCS#11 shared object file to the docker container as described in the section “Configure and Start the Hyperledger Fabric CA Server”.
6.1 Create an Account in Fortanix DSM
- Sign up for an account at https://<FORTANIX_DSM_URL> or https://amer.smartkey.io/#/.
Refer to the Fortanix DSM Getting Started guide for more details.
6.2 Create a Fortanix DSM Group
- Create a Fortanix DSM group.
Figure 1: Create group
6.3 Create an App in Fortanix DSM
Create an app in Fortanix DSM of type REST API and copy the app’s API Key. The API key is used to mount the PKCS#11 shared object file to the docker container as described in the section “Configure and Start the Hyperledger Fabric CA Server”.
Figure 2: Create an app and copy the API key
7.0 Configure and Start the Hyperledger Fabric CA Server
- Mount the volume for the PKCS#11 shared object.
-v /opt/fortanix/pkcs11:/etc/hyperledger/fabric
- Run the following command to create a folder called
server_config
from the current working directory.docker run -it -v ${PWD}/server_config:/etc/hyperledger/fabric-ca-server -v /opt/fortanix/pkcs11:/etc/hyperledger/fabric hyperledger/fabric-ca bash
/etc/hyperledger/fabric-ca-server
on the host system. - Run
fabric-ca-server
to generate the config file from inside the container using the following command:fabric-ca-server start -b admin:adminpw
- Edit the
fabric-ca-server-config.yaml
file in/etc/hyperledger/fabric-ca-server/
using the following command.vi fabric-ca-server-config.yaml
- Add the following to the
bccsp
section of the above file.bccsp:
default: PKCS11
pkcs11:
Library: "/etc/hyperledger/fabric/fortanix_pkcs11.so"
hash: SHA2
security: 256
Label: "Fortanix Token"
Pin: file://etc/hyperledger/fabric/fortanix_pkcs11.conf - Edit the
fortanix_pkcs11.conf
file as pointed by thePin
field in thefabric-ca-server-config.yaml
file. This can be put in the same path as/opt/fortanix/pkcs11
, so mounting-v /opt/fortanix/pkcs11 :/etc/hyperledger/fabric
will also mount thefortanix_pkcs11.conf
file.api_endpoint = "https://<FORTANIX_DSM_URL>" api_key="<API_KEY>" app_id="<APP_UUID>" [log] system = false # Unix only, logs to syslog file = "/var/log/p11.log"
- The
api_endpoint
refers to the instance of Fortanix DSM you set up your account on,api_key
is the API key of the Fortanix DSM app created in section "Create an App in Fortanix DSM",app_id
is the UUID of the same app. Logging can be set using this config file, the paths are in the context of the container. - Delete any keystores in
/etc/hyperledger/fabric-ca-server
such as the MSP directory and the old.pem
file so that new keystores are generated with the HSM when the server is started. - Start the CA server using the following command:
fabric-ca-server start -b admin:adminpw
8.0 Enrolling and Registering a Fabric CA Client
- Start the CA server if it is not currently running. This is needed for the Enroll operation.
- Enroll the client using the credentials used in Step 9 of the previous section “Configure and Start the Hyperledger Fabric CA Server”.
fabric-ca-client enroll -u http://admin:adminpw @localhost:7054
- This will create a client config YAML file in the location
/etc/hyperledger/fabric-ca-server
. - Edit the
bccsp
section and copy the server BCCSP configuration for the client. - Run the
enroll
command to enroll the client.fabric-ca-client enroll -u http://admin:adminpw@localhost:7054
- Register the client using the following syntax:
fabric-ca-client register --id.name ica.example --id.type client --id.secret root --csr.names
C=es,ST=madrid,L=Madrid,O=example.com --csr.cn ica.example -m ica.example --id.attrs '"hf.IntermediateCA=true"' -u
http://localhost:7054 --loglevel debug
9.0 Peers and Ordering Nodes
- To set up peers and ordering nodes with Fortanix DSM, edit the corresponding YAML file for each node. Use the same PKCS#11 bccsp settings to edit either the
core.yaml
ororderer.yaml
files. - Run the same
enroll
commands from respective orderer or peer nodes to enroll it with the Fabric CA server that is using Fortanix DSM.
Refer to the official Hyperledger Fabric Documentation for folder structure and the network setup.
Comments
Please sign in to leave a comment.