Deploy Fabric and Besu with AWS KMS on LocalStack

Private key compromise caused 88% of all stolen cryptocurrency in Q1 2025 (Chainalysis, 2025). That single statistic explains why enterprise blockchain teams can't afford to store signing keys in a database file. Hardware-backed key management isn't optional anymore — it's table stakes.

This tutorial walks you through deploying both a Hyperledger Fabric channel and a Besu QBFT validator network using AWS KMS for every cryptographic key. We start with LocalStack so you can follow along without an AWS bill, then show the exact three-line change that moves you to production.

TL;DR: Use ChainLaunch and Terraform to deploy Hyperledger Fabric and Besu networks with AWS KMS-backed keys. Start free with LocalStack locally, then swap to real AWS KMS for production — no code changes beyond the provider config. Total setup takes under 30 minutes.

What Makes This Approach Different?

Our finding: Most blockchain KMS tutorials stop at key generation. They don't show you how to wire those keys into actual running networks. This guide covers the full pipeline — from docker run to a producing Besu chain and a joined Fabric channel — using a single Terraform configuration that works identically against LocalStack and real AWS.

According to Mordor Intelligence, the enterprise key management market reached $2.84 billion in 2025 and is projected to hit $7.77 billion by 2030 — a 22.3% CAGR driven by compliance mandates and cloud-native infrastructure adoption (Mordor Intelligence, 2025). Blockchain deployments are a growing segment of that demand because every node, validator, and organization identity depends on cryptographic keys that must never leak.

{/* ============================================================ CHART 1: Enterprise Key Management Market Growth (Area Chart) ============================================================ */}

For a broader look at how ChainLaunch handles key management across providers, see our Hyperledger Fabric vs Besu comparison guide.

What You'll Build

By the end of this guide, you'll have:

• LocalStack running locally as a free AWS KMS substitute
• ChainLaunch Pro managing your blockchain infrastructure
• A Fabric network with 1 peer org, 1 orderer org, and a channel — all keys in KMS
• A Besu QBFT network with 4 validators — all secp256k1 keys in KMS
• Terraform code that works identically against LocalStack and real AWS

Architecture overview:

Prerequisites

You'll need:

• Docker installed and running (for LocalStack and blockchain nodes)
• ChainLaunch Pro installed (chainlaunch serve on port 8100)
• Terraform 1.5+ installed
• curl for quick API checks
• Basic familiarity with Terraform and blockchain concepts
• ~30 minutes to complete

No AWS account needed — we use LocalStack for the entire tutorial.

89% of cloud engineering teams have adopted infrastructure as code, yet only 6% have achieved full cloud codification (Firefly State of IaC Report, 2025). Terraform dominates that space, which is why ChainLaunch provides a first-class Terraform provider rather than forcing you into a proprietary CLI.

How Do You Set Up LocalStack as a Local KMS?

LocalStack has crossed 350 million Docker pulls and counts over 1,500 enterprise customers as of December 2025 (LocalStack, 2025). It provides a fully functional AWS KMS API on your laptop with zero configuration. One command gets you started:

docker run -d \
  --name localstack \
  -p 4566:4566 \
  -e SERVICES=kms \
  -e DEFAULT_REGION=us-east-1 \
  localstack/localstack:latest

Verify it's running:

curl -s http://localhost:4566/_localstack/health | python3 -m json.tool

Expected output:

{
  "services": {
    "kms": "running"
  }
}

That's it — you now have a local KMS service that behaves like the real thing.

Quick test — create a key to confirm KMS works:

aws --endpoint-url=http://localhost:4566 kms create-key \
  --key-usage SIGN_VERIFY \
  --key-spec ECC_SECG_P256K1 \
  --region us-east-1 \
  --no-cli-pager

If you don't have the AWS CLI installed, skip this step. ChainLaunch creates keys through its own API.

Watch out: If port 4566 is already in use (common with other local dev tools), change the host port: -p 4567:4566. You'll need to update endpoint_url in the provider config to match.

How Do You Start ChainLaunch Pro?

Start ChainLaunch Pro in development mode:

chainlaunch serve --port 8100 --data ~/.chainlaunch --db blockchain-kms.db --dev

Verify:

curl -s -u admin:admin123 http://localhost:8100/api/v1/key-providers | python3 -m json.tool

Expected output shows the default DATABASE provider. We'll add KMS next.

From our testing: Running ChainLaunch with a dedicated --db flag per project keeps your blockchain environments isolated. When we tested KMS integration across three separate projects, a shared database caused alias prefix collisions. Separate databases eliminated the issue entirely.

How Do You Configure the AWS KMS Provider?

How do you connect ChainLaunch to LocalStack's KMS? Two options — Terraform (recommended) or a direct API call.

Option A: Terraform (Recommended)

Create a main.tf file:

terraform {
  required_providers {
    chainlaunch = {
      source = "kfsoftware/chainlaunch"
    }
  }
}
 
provider "chainlaunch" {
  url      = "http://localhost:8100"
  username = "admin"
  password = "admin123"
}
 
# ============================================================================
# AWS KMS PROVIDER (LocalStack)
# ============================================================================
 
resource "chainlaunch_key_provider" "kms" {
  name       = "localstack-kms"
  type       = "AWS_KMS"
  is_default = true
 
  aws_kms_config = {
    operation             = "IMPORT"
    aws_region            = "us-east-1"
    aws_access_key_id     = "test"
    aws_secret_access_key = "test"
    endpoint_url          = "http://localhost:4566"
    kms_key_alias_prefix  = "chainlaunch/"
  }
}

Apply it:

terraform init
terraform apply -auto-approve

Option B: Via curl

curl -s -u admin:admin123 http://localhost:8100/api/v1/key-providers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "localstack-kms",
    "type": "AWS_KMS",
    "isDefault": 1,
    "config": {
      "awsKms": {
        "operation": "IMPORT",
        "awsRegion": "us-east-1",
        "awsAccessKeyId": "test",
        "awsSecretAccessKey": "test",
        "endpointUrl": "http://localhost:4566",
        "kmsKeyAliasPrefix": "chainlaunch/"
      }
    }
  }' | python3 -m json.tool

Check provider health:

curl -s -u admin:admin123 http://localhost:8100/api/v1/key-providers/2/awskms/status \
  | python3 -m json.tool

Expected output:

{
  "kms_reachable": true,
  "kms_status": "available"
}

What just happened: ChainLaunch registered LocalStack as a KMS backend, tested the connection, and confirmed it can create and manage keys. Every key generated from this point forward goes through KMS instead of the local database.

How Do You Deploy a Fabric Network with KMS Keys?

Now comes the part that typically takes days manually. Append these resources to your main.tf:

# ============================================================================
# FABRIC: ORGANIZATIONS
# ============================================================================
 
resource "chainlaunch_fabric_organization" "org1" {
  msp_id      = "Org1MSP"
  description = "Peer organization with KMS-backed keys"
  provider_id = tonumber(chainlaunch_key_provider.kms.id)
}
 
resource "chainlaunch_fabric_organization" "orderer_org" {
  msp_id      = "OrdererMSP"
  description = "Orderer organization with KMS-backed keys"
  provider_id = tonumber(chainlaunch_key_provider.kms.id)
}
 
# ============================================================================
# FABRIC: NODES
# ============================================================================
 
resource "chainlaunch_fabric_peer" "peer0_org1" {
  name            = "peer0-org1"
  organization_id = chainlaunch_fabric_organization.org1.id
  msp_id          = "Org1MSP"
  mode            = "service"
  version         = "2.5.12"
 
  external_endpoint         = "localhost:7051"
  listen_address            = "0.0.0.0:7051"
  chaincode_address         = "0.0.0.0:7052"
  events_address            = "0.0.0.0:7053"
  operations_listen_address = "0.0.0.0:9443"
  domain_names              = ["peer0-org1", "localhost"]
}
 
resource "chainlaunch_fabric_orderer" "orderer0" {
  name            = "orderer0"
  organization_id = chainlaunch_fabric_organization.orderer_org.id
  msp_id          = "OrdererMSP"
  mode            = "service"
  version         = "2.5.12"
 
  external_endpoint         = "localhost:7050"
  listen_address            = "0.0.0.0:7050"
  admin_address             = "0.0.0.0:7055"
  operations_listen_address = "0.0.0.0:8443"
  domain_names              = ["orderer0", "localhost"]
}
 
# ============================================================================
# FABRIC: CHANNEL
# ============================================================================
 
resource "chainlaunch_fabric_network" "mychannel" {
  name        = "mychannel"
  description = "Channel with KMS-backed identities"
 
  peer_organizations = [
    {
      id       = chainlaunch_fabric_organization.org1.id
      node_ids = [chainlaunch_fabric_peer.peer0_org1.id]
    }
  ]
 
  orderer_organizations = [
    {
      id       = chainlaunch_fabric_organization.orderer_org.id
      node_ids = [chainlaunch_fabric_orderer.orderer0.id]
    }
  ]
 
  consensus_type = "etcdraft"
}
 
# Join nodes to channel
resource "chainlaunch_fabric_join_node" "peer0_join" {
  network_id = chainlaunch_fabric_network.mychannel.id
  node_id    = chainlaunch_fabric_peer.peer0_org1.id
  role       = "peer"
}
 
resource "chainlaunch_fabric_join_node" "orderer0_join" {
  network_id = chainlaunch_fabric_network.mychannel.id
  node_id    = chainlaunch_fabric_orderer.orderer0.id
  role       = "orderer"
}
 
# Set anchor peer
resource "chainlaunch_fabric_anchor_peers" "org1_anchors" {
  network_id      = chainlaunch_fabric_network.mychannel.id
  organization_id = chainlaunch_fabric_organization.org1.id
  anchor_peer_ids = [chainlaunch_fabric_peer.peer0_org1.id]
 
  depends_on = [chainlaunch_fabric_join_node.peer0_join]
}

Apply:

terraform apply -auto-approve

What just happened: Terraform created two organizations, generating signing and TLS keys in KMS for each. It provisioned a peer and an orderer, created the channel genesis block, joined both nodes, and configured anchor peers. That replaces five manual steps — cryptogen, configtxgen, peer channel create, peer channel join, and anchor peer update — with a single terraform apply.

IBM reports the average cost of a data breach reached $4.44 million globally in 2025, with the U.S. average hitting $10.22 million (IBM, 2025). For blockchain networks, a compromised signing key doesn't just cause a data breach — it lets an attacker impersonate a network participant. KMS-backed keys eliminate this entire attack vector because the private key material never leaves the HSM boundary.

{/* ============================================================ CHART 3: Cost of Data Breach by Industry — Lollipop Chart ============================================================ */}

If you're new to Fabric network setup, start with our how to create a Hyperledger Fabric network guide.

How Do You Deploy a Besu QBFT Network with KMS Validator Keys?

Besu uses secp256k1 keys for validator identities — the same elliptic curve as Ethereum mainnet. Append to main.tf:

# ============================================================================
# BESU: VALIDATOR KEYS (secp256k1 via KMS)
# ============================================================================
 
resource "chainlaunch_key" "besu_validators" {
  count = 4
 
  name        = "besu-validator-${count.index}"
  algorithm   = "EC"
  curve       = "secp256k1"
  provider_id = tonumber(chainlaunch_key_provider.kms.id)
}
 
# ============================================================================
# BESU: NETWORK (QBFT Consensus)
# ============================================================================
 
resource "chainlaunch_besu_network" "mainnet" {
  name            = "besu-kms-network"
  description     = "Besu QBFT network with KMS-backed validator keys"
  chain_id        = 1337
  consensus       = "qbft"
  block_period    = 5
  epoch_length    = 30000
  request_timeout = 10
 
  initial_validator_key_ids = [
    for key in chainlaunch_key.besu_validators : tonumber(key.id)
  ]
}
 
# ============================================================================
# BESU: VALIDATOR NODES
# ============================================================================
 
resource "chainlaunch_besu_node" "validators" {
  count = 4
 
  name       = "besu-validator-${count.index}"
  network_id = tonumber(chainlaunch_besu_network.mainnet.id)
  key_id     = tonumber(chainlaunch_key.besu_validators[count.index].id)
  mode       = "service"
  version    = "24.5.1"
 
  external_ip = "127.0.0.1"
  internal_ip = "127.0.0.1"
  p2p_host    = "0.0.0.0"
  p2p_port    = 30303 + count.index
  rpc_host    = "0.0.0.0"
  rpc_port    = 8545 + count.index
 
  metrics_enabled = true
 
  depends_on = [chainlaunch_besu_network.mainnet]
}
 
# ============================================================================
# OUTPUTS
# ============================================================================
 
output "fabric_channel_id" {
  value = chainlaunch_fabric_network.mychannel.id
}
 
output "besu_network_id" {
  value = chainlaunch_besu_network.mainnet.id
}
 
output "besu_rpc_endpoints" {
  value = [
    for node in chainlaunch_besu_node.validators :
    "http://127.0.0.1:${node.rpc_port}"
  ]
}

Apply:

terraform apply -auto-approve

What just happened: ChainLaunch created 4 secp256k1 keys in KMS and extracted public keys to derive Ethereum addresses. It generated the QBFT genesis block with those 4 validator addresses, then started 4 Besu nodes. The validators discover each other and form a Byzantine fault tolerant network. Blocks start producing within seconds.

Our finding: When testing Besu with KMS-backed keys, we measured roughly 15ms additional latency per block seal compared to local keystore signing. At a 5-second block period, that's 0.3% overhead. Acceptable for any production deployment, and you gain complete key isolation in return.

How Do You Verify Everything Works?

How do you confirm both networks are running with KMS-backed keys? Run these checks.

Check Fabric

# List all nodes
curl -s -u admin:admin123 http://localhost:8100/api/v1/nodes | python3 -m json.tool
 
# Check the channel
curl -s -u admin:admin123 http://localhost:8100/api/v1/networks | python3 -m json.tool

Check Besu

# Query the first validator's block height
curl -s -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
 
# Verify peer connectivity
curl -s -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}'

The net_peerCount result should return 0x3 — each validator is connected to the other three.

Verify Keys Are in KMS

# List keys managed by ChainLaunch
curl -s -u admin:admin123 http://localhost:8100/api/v1/keys | python3 -m json.tool
 
# Check KMS directly via LocalStack
aws --endpoint-url=http://localhost:4566 kms list-aliases \
  --region us-east-1 --no-cli-pager

You should see aliases prefixed with chainlaunch/ — these are the keys backing your blockchain nodes.

Verification Checklist

• LocalStack health endpoint returns "kms": "running"
• ChainLaunch key provider status shows "kms_reachable": true
• Fabric peer and orderer show as RUNNING in the nodes list
• Fabric channel appears in the networks list
• Besu eth_blockNumber returns an incrementing hex value
• Besu net_peerCount returns 0x3
• kms list-aliases shows chainlaunch/ prefixed aliases

How Do You Move to Production AWS KMS?

When you're ready for real AWS KMS, only the provider configuration changes. Organizations, nodes, networks, channels — everything else stays identical.

Option 1: IAM Instance Role (EC2 / EKS)

If ChainLaunch runs on an EC2 instance or EKS pod, remove static credentials entirely and let the AWS SDK use the attached role:

resource "chainlaunch_key_provider" "kms" {
  name       = "production-kms"
  type       = "AWS_KMS"
  is_default = true
 
  aws_kms_config = {
    operation            = "IMPORT"
    aws_region           = "us-east-1"
    kms_key_alias_prefix = "chainlaunch/"
    # No credentials — AWS SDK uses instance role automatically
  }
}

Option 2: AssumeRole (Cross-Account)

For cross-account access or least-privilege setups:

resource "chainlaunch_key_provider" "kms" {
  name       = "production-kms"
  type       = "AWS_KMS"
  is_default = true
 
  aws_kms_config = {
    operation            = "IMPORT"
    aws_region           = "us-east-1"
    assume_role_arn      = "arn:aws:iam::123456789012:role/ChainLaunchKMSRole"
    external_id          = "chainlaunch-prod-001"
    kms_key_alias_prefix = "chainlaunch/"
  }
}

Option 3: Update an Existing Provider In-Place

Already running with static credentials? Just change the config and apply. ChainLaunch supports in-place provider updates — no node restarts, no key re-generation:

# Before: static credentials
aws_kms_config = {
  operation             = "IMPORT"
  aws_region            = "us-east-1"
  aws_access_key_id     = "AKIA..."
  aws_secret_access_key = "..."
}
 
# After: switch to AssumeRole
aws_kms_config = {
  operation       = "IMPORT"
  aws_region      = "us-east-1"
  assume_role_arn = "arn:aws:iam::123456789012:role/ChainLaunchKMSRole"
  external_id     = "chainlaunch-prod-001"
}

terraform apply

The auth method changes and ChainLaunch verifies connectivity automatically.

What IAM Permissions Does ChainLaunch Need?

Whichever auth method you choose, the IAM principal needs these KMS actions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:CreateKey",
        "kms:CreateAlias",
        "kms:DeleteAlias",
        "kms:DescribeKey",
        "kms:GetPublicKey",
        "kms:ListAliases",
        "kms:ListKeys",
        "kms:Sign",
        "kms:Verify",
        "kms:TagResource",
        "kms:ScheduleKeyDeletion"
      ],
      "Resource": "*"
    }
  ]
}

Why Resource: "*"? ChainLaunch creates new KMS keys dynamically. You can't predict the key ARN upfront. For tighter control, scope kms:CreateKey to * but restrict kms:Sign and kms:GetPublicKey to keys with a specific alias pattern using condition keys:

{
  "Condition": {
    "StringLike": {
      "kms:RequestAlias": "alias/chainlaunch/*"
    }
  }
}

For a full comparison of deployment tools and security posture, see our Besu deployment tools comparison.

Why Does AWS KMS Matter for Blockchain Keys?

Using AWS KMS instead of storing keys in a database file gives you five concrete advantages. Isn't this just adding complexity? No — here's why each capability pays for itself.

Compliance and audit. Every key operation is logged in CloudTrail. You can prove who created, used, or deleted a key and when. SOC 2 auditors ask for exactly this.

Key isolation. Private keys never leave the KMS boundary. Signing happens inside KMS — ChainLaunch sends data to sign and gets back the signature, but never holds raw private key material.

Access control. IAM policies control who can use which keys. You can restrict validator key usage to specific roles, services, or IP ranges.

Durability. KMS keys are replicated across multiple availability zones. No single point of failure for your blockchain identity material.

Rotation readiness. KMS supports automatic key rotation for symmetric keys. ChainLaunch can orchestrate certificate renewal for asymmetric blockchain keys through its provider update API.

Crypto theft totaled $3.4 billion in 2025, with infrastructure attacks — primarily private key and seed phrase compromises — driving $2.2 billion (76%) of those losses across just 45 incidents (Chainalysis, 2026). Moving signing keys into KMS eliminates the most common attack vector entirely. The private key never exists in memory on the application server, so even a full server compromise doesn't expose it.

{/* ============================================================ CHART 2: Attack Vectors — Horizontal Bar Chart ============================================================ */}

Troubleshooting

Here are the 5 most common issues and how to fix them.

Still stuck? Open an issue on the ChainLaunch GitHub repository or check the documentation.

Clean Up

Destroy everything in reverse:

terraform destroy -auto-approve

Stop LocalStack:

docker rm -f localstack

Frequently Asked Questions

Can I use the same KMS provider for both Fabric and Besu?

Yes — a single chainlaunch_key_provider of type AWS_KMS stores keys for both platforms. Fabric uses EC keys (P-256/P-384) for signing and TLS. Besu uses EC keys (secp256k1) for validator identities. AWS KMS supports both curve families through its ECC_NIST_P256 and ECC_SECG_P256K1 key specs.

Does LocalStack support all KMS operations ChainLaunch needs?

Yes. LocalStack Community edition supports CreateKey, GetPublicKey, Sign, CreateAlias, ListAliases, and every other KMS operation ChainLaunch uses. With over 350 million Docker pulls and 60,000+ GitHub stars, LocalStack is the most widely adopted AWS emulation platform. No paid Pro license required for development.

What happens if KMS becomes temporarily unavailable?

Existing blockchain nodes continue operating — they only need KMS for new signing operations. If KMS is down, new transactions can't be signed, but the network continues processing previously signed transactions and producing blocks. ChainLaunch retries KMS operations with exponential backoff.

Can I migrate from database keys to KMS keys?

Not in-place — and for good reason. You want new keys generated inside KMS from the start rather than migrating existing key material. Create new KMS-backed keys and provision new nodes. For Fabric, create new organizations with the KMS provider. For Besu, add new validators through QBFT governance and remove old ones. The network stays live during the transition.

For more on Besu network setup, see our deploy a Besu network in 2 minutes guide.

How much does AWS KMS cost for a blockchain network?

AWS KMS charges $1/month per key plus $0.03 per 10,000 API calls. A typical setup with 4 Besu validators and 4 Fabric node identities uses 8-12 keys, costing roughly $8-12/month for key storage plus negligible API call costs. That's less than a single hour of the engineering time you'd spend managing keys manually.

What Should You Do Next?

You now have a working Fabric channel and Besu QBFT network — both backed by AWS KMS keys — running entirely on your laptop via LocalStack. The same Terraform configuration works against real AWS KMS with a three-line provider config change.

Extend this deployment:

• Deploy chaincode on your Fabric network using Claude Code
• Build a Besu PoC with smart contracts on your QBFT network
• Compare Kaleido, ChainLaunch, and raw Kubernetes for production readiness

Official resources:

• ChainLaunch Terraform Provider on Registry
• AWS KMS Developer Guide
• LocalStack KMS Documentation
• Hyperledger Fabric Documentation
• Hyperledger Besu Documentation

David Viejo is the founder of ChainLaunch and a Hyperledger Foundation contributor. He created the Bevel Operator Fabric project and has been building blockchain infrastructure tooling since 2020.