DEV Community: Anushka Agarwal

Step-by-Step Dockerization of a Node.js App Connecting to AWS CloudHSM with PKCS#11 SDK

Anushka Agarwal — Thu, 23 Jan 2025 08:57:16 +0000

Recently, I worked on a Node.js application that required integration with AWS CloudHSM for secure cryptographic operations. After successfully implementing the application, the next challenge was to dockerize it so it could run efficiently in an air-gapped environment. This presented its own set of hurdles, as information on how to combine Docker, Node.js, and AWS CloudHSM using the PKCS#11 SDK was scarce.

To save others the time and effort I invested, I decided to document the process step-by-step in this blog. If you're facing a similar use case, this guide will walk you through how to efficiently dockerize a Node.js application that connects to AWS CloudHSM using the PKCS#11 SDK.

The Challenges of an Air-Gapped Environment

In an air-gapped environment, external internet access is often restricted, which means we can't simply pull down images or install packages directly from the web. In our case, we also needed to integrate the AWS CloudHSM PKCS#11 client, which requires specific dependencies. To overcome this, we started by identifying all the necessary dependencies that needed to be baked into the Docker image.

Step 1: Setting Up the Base Docker Image

We began with an Ubuntu base image (version 20.04) and started by installing a few critical packages, including wget, python3, python3-pip, and curl. These were needed for installing the PKCS#11 SDK and other dependencies.

# Use the Ubuntu image
FROM ubuntu:20.04 AS builder

# Install necessary packages and clean up
RUN apt-get update && apt-get install -y \
    wget \
    python3 \
    python3-pip \
    curl \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

Step 2: Installing Node.js and NPM

Next, we needed Node.js and npm to run our application. Since the environment was air-gapped, we had to manually fetch and install the packages. We added the Node.js 16.x setup script and installed it along with npm.

# Install Node.js and npm
RUN curl -sL https://deb.nodesource.com/setup_16.x | bash - \
    && apt-get install -y nodejs \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

Step 3: Installing AWS CloudHSM PKCS#11 Client

At this point, the main challenge was integrating the AWS CloudHSM PKCS#11 client, which is essential for securely connecting to CloudHSM. We manually downloaded the .deb package for the CloudHSM PKCS#11 client and installed it.

# Install CloudHSM PKCS #11 client
RUN wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Focal/cloudhsm-pkcs11_latest_u20.04_amd64.deb \
    && apt install -y ./cloudhsm-pkcs11_latest_u20.04_amd64.deb \
    && rm -f cloudhsm-pkcs11_latest_u20.04_amd64.deb

Step 4: Setting Up the Application Code

Once we had the dependencies installed, we created a working directory for our Node.js application. We copied over the package.json files to install the required npm dependencies and then copied the rest of the application code into the container. Finally, we built the application.

# Create a work directory
WORKDIR /app

# Copy package.json files and install npm dependencies
COPY package*.json ./
RUN npm cache clean --force \
    && npm install \
    && npm cache clean --force

# Copy the rest of the application code
COPY . .

RUN npm run build

Step 5: Preparing the Final Image

After building the application, we transitioned to the final image stage. At this point, we removed unnecessary files and dependencies that weren't needed for the final container. The CloudHSM PKCS#11 client files were copied from the builder stage, and we also ensured that the correct file permissions were set for the libcloudhsm_pkcs11.so file.

# Prepare application code for the final stage
FROM ubuntu:20.04

# Copy the CloudHSM PKCS #11 client files from the builder stage
COPY --from=builder /opt/cloudhsm /opt/cloudhsm

# Create a work directory
WORKDIR /app

COPY --from=builder /app/dist /app/dist
COPY --from=builder /app/node_modules /app/node_modules
#COPY --from=builder /app/deployment /app/deployment

# Permissions to .so file
# Optional step
RUN chmod -R 777 /opt/cloudhsm/lib
RUN chmod -R 777 /opt/cloudhsm/lib/libcloudhsm_pkcs11.so

RUN apt-get update && apt-get install -y \
    curl \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Install Node.js and npm
RUN curl -sL https://deb.nodesource.com/setup_16.x | bash - \
    && apt-get install -y nodejs \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

Step 6: Running the Application

Finally, you’ll want to run the application. This can be done using a CMD or ENTRYPOINT directive to start your Node.js app within the container. This step depends on how you want to manage your process (whether through a script, direct command, etc.).

The Complete Dockerfile

Here’s the complete Dockerfile that puts everything together:

# Use the Ubuntu image
FROM ubuntu:20.04 AS builder

# Install necessary packages and clean up
RUN apt-get update && apt-get install -y \
    wget \
    python3 \
    python3-pip \
    curl \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Install Node.js and npm
RUN curl -sL https://deb.nodesource.com/setup_16.x | bash - \
    && apt-get install -y nodejs \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Install CloudHSM PKCS #11 client
RUN wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Focal/cloudhsm-pkcs11_latest_u20.04_amd64.deb \
    && apt install -y ./cloudhsm-pkcs11_latest_u20.04_amd64.deb \
    && rm -f cloudhsm-pkcs11_latest_u20.04_amd64.deb

# Create a work directory
WORKDIR /app

# Copy package.json files and install npm dependencies
COPY package*.json ./
RUN npm cache clean --force \
    && npm install \
    && npm cache clean --force

# Copy the rest of the application code
COPY . .

RUN npm run build

# Prepare application code for the final stage
FROM ubuntu:20.04

# Copy the CloudHSM PKCS #11 client files from the builder stage
COPY --from=builder /opt/cloudhsm /opt/cloudhsm

# Create a work directory
WORKDIR /app

COPY --from=builder /app/dist /app/dist
COPY --from=builder /app/node_modules /app/node_modules
#COPY --from=builder /app/deployment /app/deployment

# Permissions to .so file
RUN chmod -R 777 /opt/cloudhsm/lib
RUN chmod -R 777 /opt/cloudhsm/lib/libcloudhsm_pkcs11.so

RUN apt-get update && apt-get install -y \
    curl \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Install Node.js and npm
RUN curl -sL https://deb.nodesource.com/setup_16.x | bash - \
    && apt-get install -y nodejs \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

Conclusion

By following these steps, you can successfully dockerize a Node.js application that connects to AWS CloudHSM using the PKCS#11 SDK, even in an air-gapped environment. The key was to manually manage dependencies and take advantage of Docker’s multi-stage builds to ensure a clean and efficient final image.

I hope this guide saves you some time and frustration, just as it did for me! If you have any questions or run into issues, feel free to leave a comment or reach out. Happy coding!

Decoding the Challenge: Investigating a Common Deployment Hitch "Error: failed to create deliver client for orderer"

Anushka Agarwal — Fri, 19 Jan 2024 14:33:53 +0000

In the vast realm of blockchain technology, setting up a network can be a complex task. Recently, I faced an issue while deploying a minifabric network on a virtual machine. The error message
"Error: failed to create deliver client for orderer: orderer client failed to connect to 123.456.789.012:5013: failed to create new connection: context deadline exceeded," disrupted what should have been a routine process.

For those familiar with blockchain deployment, encountering errors is expected. However, comprehending and resolving these issues is where the real journey begins. In this blog, I aim to demystify the aforementioned error, sharing the troubleshooting steps that led to its resolution. Join me as we figure out the details of this deployment problem and solve the mystery behind the error that momentarily halted progress.

Troubleshooting steps:

Make sure no other app or service is using the port where minifab is deploying the orderer. In my case, it was port 5013. You can check with any one of these commands

lsof -i :<port_number>
netstat -tlnp | grep <port_number>

If you find another application on the needed port, you can choose a different port range by using the -e flag in the minifab command. Just use

minifab up -e <port_number>

If you are using an old minifab version, try updating the version

docker pull hyperledgerlabs/minifab:latest

The last crucial step that finally fixed the issue was discovering a firewall on the VM causing trouble with communication between the docker containers and the host. The problem was the firewall rules set up using Uncomplicated Firewall (UFW). To tackle this, I examined the firewall's status and rules by using the command

sudo ufw status

It became evident from the output that the firewall was not allowing the port range (5000). To fix this, I added a rule permitting this port range using the command:

ufw allow <start_port_number>:<end_port_number>

I cleaned everything up by these commands

minifab down
minifab cleanup

Then, I brought the network back up. Hooray! Problem solved, and the network was up and running smoothly! XD

Through this shared experience, I want to help others save time fixing common problems. This blog is like a guide to help troubleshoot issues and show the way for people facing similar problems. Let's make it easier for enthusiasts to understand and fix things when setting up their fabric deployments. Together, we can navigate through these challenges more smoothly and enjoy a hassle-free deployment experience.

Happy Learning :)

Deploying Hyperledger Fabric Network on Kubernetes using Falcon

Anushka Agarwal — Thu, 02 Nov 2023 18:36:25 +0000

Before diving into how to deploy Hyperledger Fabric on Kubernetes we need to understand some basics about Hyperledger Fabric.

What is Hyperledger Fabric

Hyperledger Fabric is an open source enterprise-grade permissioned distributed ledger technology (DLT) platform. Fabric has a very modular and configurable architecture and it is the first DLT platform to support smart contracts authored in general-purpose programming languages.
It is a restricted access blockchain designed to maintain transparency among a network of organizations that lack complete mutual trust.

Network Topology of HLF

Hyperledger Fabric (HLF) is primarily composed of the following key elements:

Certificate Authority (CA)

It plays a vital role in managing digital identities and maintaining the security and integrity of the network by issuing, validating, and managing certificates.
Typically CA nodes form a tree-like topology with Root CA at the top.

Root CA

It is a self-signed instance which issues certificates to all other organisations in the network.

Intermediate Certificate Authority (ICA)

CAs that belong to other organisations, essentially the Intermediate Certificate Authority (ICA) are signed by the Root CA. All the other nodes and users in the network are signed by the ICA.

TLS CA

It issues certificates to orderer and peers to enable the TLS communication in the network.

Orderers

It forms an ordering service which is responsible for keeping the blockchain state consistent and final. Orderers maintain access to the channels and keep a system channel that contains access control lists (ACLs) of organizations that can create channels. They restrict who can configure, read, and write data to particular channels.

Peers

They are the fundamental elements in a HLF Network as they manage ledgers and smart contracts.
Peers take care of proposal, endorsement, validation and commitment of a transaction in the HLF network. A peer belongs to one organization, can belong to multiple channels, and can host multiple ledgers and smart contracts.
They forward smart contract calls to dedicated chaincode containers in the network and update the network state on the basis of smart contract results. They also connect to the orderers to receive new blocks for transactions or can do p2p communication through gossip protocol.

Channels

A HLF channel is a private “subnet” of communication between two or more specific network members, for the purpose of conducting private and confidential transactions. All peers belonging to a channel have access to the same data and smart contracts. There is no access to it outside the channel.

Now, since we have a basic idea about HLF and its key components we can move on to deploying HLF on kubernetes using Falcon.

What is Falcon

Falcon is an open source, hyperledger fabric deployment helper designed to streamline the deployment and management of Hyperledger Fabric based blockchain networks on Kubernetes clusters.
The key features provided by Falcon are:

CA Management (Root CA, TLS CA & Intermediate CAs)
Peer Creation
Orderer Creation
Channel Management
Chaincode Lifecycle Management (Install, Approve, Commit and CC Upgrades)
Cryptographic operations support and certification management
Domain Name support and SNI Based Routing
Ingress resource provisioning
File Registry support for centralised config files
Support for Hyperledger Fabric 2.3+
Multi-zone, Multi-DC, Private Network (On-prem DCs) deployment support.

Steps to deploy a HLF Network on kubernetes cluster

Prerequisites

Deploy nginx ingress with the ingress service exposed by two Nodeports for Ports: 80/TCP, 443/TCP Depending on whether you are deploying on a public cloud or on your infrastructure in a data center, you can deploy an ingress service with a cloud native load-balancer or NodePort to allow access to the Ingress Controller. You can refer to https://platform9.com/learn/v1.0/tutorials/nginix-controller-via-yaml for a detailed explanation on the deployment.
Edit the ingress deployment to enable the ssl passthrough

kubectl edit deployments.apps -n ingress-nginx ingress-nginx-controller

Add Configurable DNS You need to add custom DNS zones that are resolvable from the pods. If you're using CoreDNS, follow this guide to add custom zones on your Kubernetes cluster https://coredns.io/2017/05/08/custom-dns-entries-for-kubernetes/. If deploying to GKE on GCP, you can make use of CloudDNS private zones.
Add the A record(s) that points to the server(s) where the Ingress is listening. It must be a wildcard DNS entry. Eg, If your domain name is my-hlf-domain.com and you have the worker node as 172.100.1.2. Then you need to create a DNS entry *.my-hlf-domain.com to point to above IP. This is a must have configuration and make sure that wildcard DNS queries are resolving properly. If you're in any public cloud platform, then hard coding the worker node IP in the DNS is not a reliable approach since the worker node can be changed at any time. In that case, you can deploy an Internal Cloud LB.
Provision a storageclass that supports dynamic volume provisioning like rook-ceph or standard.

HLF Network

Clone the falcon repository and navigate to the root directory to begin the deployment using the sample example.`

Deploy a filestore server

The filestore server is the nginx deployment with custom rules to support uploading over curl which stores common artifacts like chaincode, collection config file etc.
helm install filestore -n filestore helm-charts/filestore/ -f examples/filestore/values.yaml --create-namespace
You can check if your filestore server is up and running with
kubectl get pods -n filestore
The output should be something like

Deploy Root CA

Create the orderer namespace in which we will deploy the Root CA. Also create a kubernetes secret with user and password as keys for this ROOTCA server.
kubectl create ns orderer
kubectl -n orderer create secret generic rca-secret --from-literal=user=rca-admin --from-literal=password=rcaComplexPassword

Deploy the Root CA Server
helm install root-ca -n orderer helm-charts/fabric-ca -f examples/fabric-ca/root-ca.yaml
This will deploy the root-ca server for you and the server will be available at https://root-ca.my-hlf-domain.com. To verify the server, you can get into any running pod in the cluster and send a curl request as below;
curl https://root-ca.my-hlf-domain.com:<HTTPS-INGRESS-PORT>/cainfo --insecure

Deploy TLS CA

Create a kubernetes secret for the TLSCA and deploy the tls ca server.
kubectl -n orderer create secret generic tlsca-secret --from-literal=user=tls-admin --from-literal=password=TlsComplexPassword
helm install tls-ca -n orderer helm-charts/fabric-ca -f examples/fabric-ca/tls-ca.yaml
This will deploy a tls ca server for you and the server will be available at https://tls-ca.my-hlf-domain.com which can be verified in the same way as root ca by hitting a curl request.

Create Root CA Identitites

helm install rootca-ops -n orderer helm-charts/fabric-ops/ -f examples/fabric-ops/rootca/rootca-identities.yaml
This step will register your initialpeerorg, orderer and org1, org2 identities with the Root CA.
Check the pods and wait for the jobs to successfully get completed.

Create TLS CA Identities

helm install tlsca-ops -n orderer helm-charts/fabric-ops/ -f examples/fabric-ops/tlsca/tlsca-identities.yaml
This step will register your orderer0, orderer1, orderer2 and peer0, peer1, peer2 of initialpeerorg, org1 and org2 with the TLS CA.
Check the pods here as well and wait for the jobs to successfully get completed.

Deploy Orderer ICA

This will deploy the Orderer ICA server which registers itself with Root CA.
Before deploying the Orderer ICA you need to create a secret with same username and password as being used while registering the ica-orderer identity with the root ca.
kubectl -n orderer create secret generic orderer-secret --from-literal=user=ica-orderer --from-literal=password=icaordererSamplePassword
Now we need to apply the helm chart to deploy Orderer ICA.
helm install ica-orderer -n orderer helm-charts/fabric-ca -f examples/fabric-ca/ica-orderer.yaml

Deploy Initial peer org ICA

This will deploy the Initial Peer Org ICA server which registers itself with Root CA.
Similar to Orderer ICA we need to create the namespace and the secret here as well.
kubectl create ns initialpeerorg
kubectl -n initialpeerorg create secret generic initialpeerorg-secret --from-literal=user=ica-initialpeerorg --from-literal=password=initialpeerorgSamplePassword
Now we need to apply the helm chart to deploy the Initial Peer Org ICA.
helm install ica-initialpeerorg -n initialpeerorg helm-charts/fabric-ca -f examples/fabric-ca/ica-initialpeerorg.yaml
Check the init container logs to make sure the authentication and ica enrollment is successful.

Create Orderer identities with ica-orderer

This step will register orderer identities i.e. orderer0, orderer1, orderer2 with the orderer-ica.
helm install orderer-ops -n orderer helm-charts/fabric-ops/ -f examples/fabric-ops/orderer/orderer-identities.yaml

Create Initialpeerorg identities with ica-initialpeerorg

This step will register the initialpeerorg identities i.e admin, peer0, peer1, peer2 identities with the initialpeerorg-ica.
helm install initialpeerorg-ops -n initialpeerorg helm-charts/fabric-ops/ -f examples/fabric-ops/initialpeerorg/identities.yaml

Generate Genesis block & Channel transaction file

This step will create the Genesis block which is the first block in any blockchain based system and a channel transaction file which contains channel name and the consortium which is allowed to use the channel.
helm install cryptogen -n orderer helm-charts/fabric-ops/ -f examples/fabric-ops/orderer/orderer-cryptogen.yaml

Deploy Orderers

This will deploy your network's orderer.
helm install orderer -n orderer helm-charts/fabric-orderer/ -f examples/fabric-orderer/orderer.yaml
Note: Disable metrics in the yaml if you do not have CRDs and ServiceMonitor installed on your kubernetes cluster.

Deploy Peers on Initial peer org

helm install peer -n initialpeerorg helm-charts/fabric-peer/ -f examples/fabric-peer/initialpeerorg/values.yaml
After successful deployment of the Peers, you will get 3 peers in initialpeerorg namespace. Each of these peers will have 1 Init container and 3 app containers (Fabric Peer, Dind & CouchDB). If everything went fine, then you'll see some successful connectivity logs in the peer0-initialpeerorg-0.

Create channel

This step creates a channel named mychannel
helm install channelcreate -n initialpeerorg helm-charts/fabric-ops/ -f examples/fabric-ops/initialpeerorg/channel-create.yaml
You will be able to see similar logs after the successful completion of the job.

Update Anchor peers of Initial peer org

helm install updateanchorpeer -n initialpeerorg helm-charts/fabric-ops/ -f examples/fabric-ops/initialpeerorg/update-anchor-peer.yaml
This updates the anchor peers of the initialpeerorg which enable communication between peers of different organizations and discover all active participants of the channel.

Install chaincode on Initialpeerorg Peers

Before you install chaincode , you need to upload the packaged chaincode file to the filestore under your project directory and give the rwx permission to the file.
kubectl cp <chaincode.tar.gz> filestore/<filestore-pod-name>:/usr/share/nginx/html/yourproject

Change the name of the chaincode tar file accordingly in the install-chaincode.yaml helm values file at Values.cc_tar_file.

To install chaincode run
helm install installchaincode -n initialpeerorg helm-charts/fabric-ops/ -f examples/fabric-ops/initialpeerorg/install-chaincode.yaml
Once your job is completed you can check the logs to assure successful installation

Deploy Org1 Environment

Deploying more organisations has the similar steps as the initialpeerorg as:

Deploy Org1 ICA
Add Org1 to the network

Once the new organisation ica has been deployed successfully we need to add this new org to the network. For that, you need to run the following Job in initialpeerorg. Comment out the org2 section from the Values.organizatons array in the values file examples/fabric-ops/initialpeerorg/configure-org-channel.yaml for now since we have not deployed the Org2 yet.

helm install configorgchannel -n initialpeerorg helm-charts/fabric-ops/ -f examples/fabric-ops/initialpeerorg/configure-org-channel.yaml

Create Org1 identities with ica-org1
Deploy Peers on Org1
Install ChainCode on Org1 Peers
Update Anchor peers of Org1

Similarly you can deploy org2 environment as well.

Approve & Commit Chain Code

Approve & Commit requires collection-config optionally. You can manage it through the variable require_collection_config: "true". If you make it as true, then you must upload a collection config file to the filestore under your project directory.

Sample chaincode lies at examples/files/collection-config.json
Note :- if you're changing the collection-config, then kindly update the sha256sum value under Values.collection_config_file_hash.

Approve Chaincode on Initialpeerorg

Ensure that you have updated the name, version and package id of the chaincode in examples/fabric-ops/initialpeerorg/approve-chaincode.yaml if you have uploaded your own collection-config file:

cc_name

cc_version

cc_package_id

Run the below command to approve chaincode:
helm install approvechaincode -n initialpeerorg helm-charts/fabric-ops/ -f examples/fabric-ops/initialpeerorg/approve-chaincode.yaml
Similarly you need to approve the chaincode from all deployed orgs using their respective approve scripts.

Commit Chaincode on Initialpeerorg

Ensure that you have updated the name, version and package id of the chaincode in examples/fabric-ops/initialpeerorg/commit-chaincode.yaml if you have uploaded your own collection-config file.

cc_name

cc_version

cc_package_id

Run below command to commit the chaincode:
helm install commitchaincode -n initialpeerorg helm-charts/fabric-ops/ -f examples/fabric-ops/initialpeerorg/commit-chaincode.yaml

Voila!!! You have your HLF Network Setup up and running...

To sum up, this comprehensive guide has taken you through a detailed journey, unraveling the essence of Hyperledger Fabric (HLF), its pivotal components, and the powerful tool Falcon.

Remember, diving into the Falcon repository (https://github.com/npci/falcon) can provide deeper insights and support as you venture further into this transformative realm. Embrace the possibilities, implement the steps outlined, and witness the empowerment that Falcon brings to the deployment of Hyperledger Fabric on Kubernetes.

Happy Learning.