Using Fortanix Data Security Manager with Hyperledger Fabric

  • Updated on Sep 23, 2024
  • Published on Jun 14, 2024
  • 5 minute(s) read
Prev

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

4.0 Set Up Fortanix PKCS#11 Client

  1. Get the PKCS#11 DEB package from the link in Section 3.0: References for Setup. This integration is tested with Fortanix DSM version 4.8.2070. 

  2. Use the following command to install the client on the host system.

    sudo dpkg -i <pkg.deb>

  3. 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.

  4. 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

  1. Get the source code for Fabric CA at https://github.com/hyperledger/fabric-ca.

  2. 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.

    NOTE

    To change the OS to Ubuntu, edit the Dockerfile at the location images/fabric-ca/Dockerfile.

    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

  3. Build the container image.

    GO_TAGS=pkcs11 make docker

  4. 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

  1. 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

  1. Create a Fortanix DSM group.  

    Fabric_CreateGroup.png

    Figure 1: Create group

6.3 Create an Application (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”.

Fabric_App.png

Figure 2: Create an app and copy the API key

7.0 Configure and Start the Hyperledger Fabric CA Server

  1. Mount the volume for the PKCS#11 shared object.

    -v /opt/fortanix/pkcs11:/etc/hyperledger/fabric

  2. 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

    This will persist the /etc/hyperledger/fabric-ca-server on the host system.

  3. Run fabric-ca-server to generate the config file from inside the container using the following command:

    fabric-ca-server start -b admin:adminpw

    Press CTRL + X or CRTL+C to exit the program.

  4. Edit the fabric-ca-server-config.yaml file in /etc/hyperledger/fabric-ca-server/ using the following command.

    vi fabric-ca-server-config.yaml

  5. 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

  6. Edit the fortanix_pkcs11.conf file as pointed by the Pin field in the fabric-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 the fortanix_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"

  7. 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.

  8. 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.

  9. Start the CA server using the following command:

    fabric-ca-server start -b admin:adminpw

8.0 Enrolling and Registering a Fabric CA Client

  1. Start the CA server if it is not currently running. This is needed for the Enroll operation.

  2. 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

  3. This will create a client config YAML file in the location /etc/hyperledger/fabric-ca-server.

  4. Edit the bccsp section and copy the server BCCSP configuration for the client.

  5. Run the enroll command to enroll the client.

    fabric-ca-client enroll -u http://admin:adminpw@localhost:7054

  6. 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

  1. 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 or orderer.yaml files.

  2. 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.

Related articles
  • Clients: PKCS#11 Library
    Fortanix Data Security Manager (DSM) > Developer Guide - Developer Operations > Clients > Clients: PKCS#11