HashiCorp Vault Integration (Pro)

ChainLaunch Pro Feature

HashiCorp Vault integration requires ChainLaunch Pro. Learn more.

Use HashiCorp Vault as a key management backend for production-grade security. Keys are encrypted and stored in Vault's transit engine — they never exist in plaintext outside Vault.

Two Modes

Mode	Description	Use when
CREATE	ChainLaunch deploys and manages a Vault instance for you (Docker)	Quick setup, development, small teams
IMPORT	Connect to your existing Vault cluster	Production, enterprise, shared Vault

Option 1: Managed Vault (CREATE mode)

ChainLaunch deploys Vault as a Docker container and configures it automatically.

Via API

curl -X POST http://localhost:8100/api/v1/key-providers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vault-managed",
    "type": "VAULT",
    "isDefault": false,
    "vaultConfig": {
      "operation": "CREATE",
      "mode": "docker",
      "network": "bridge",
      "port": 8200,
      "version": "1.20.2"
    }
  }'

ChainLaunch will:

1. Pull the Vault Docker image
2. Start the container on the specified port
3. Initialize and unseal Vault
4. Configure the transit engine
5. Store the root token securely

Via Terraform

resource "chainlaunch_key_provider" "vault" {
  name       = "vault-managed"
  type       = "VAULT"
  is_default = false

  vault_config = {
    operation = "CREATE"
    mode      = "docker"
    network   = "bridge"
    port      = 8200
    version   = "1.20.2"   # Required for CREATE mode
  }
}

Verify Status

curl http://localhost:8100/api/v1/key-providers/{providerId}/vault/status | jq

Expected response:

{
  "vault_reachable": true,
  "vault_initialized": true,
  "sealed": false,
  "container_running": true
}

Option 2: Existing Vault (IMPORT mode)

Connect ChainLaunch to your organization's existing Vault cluster.

Prerequisites

Your Vault instance needs:

1. Transit secrets engine enabled:

   vault secrets enable transit

2. KV v2 secrets engine enabled:

   vault secrets enable -version=2 kv

3. A policy with the required permissions:

   # chainlaunch-policy.hcl
   path "transit/*" {
     capabilities = ["create", "read", "update", "list"]
   }
   
   path "kv/data/chainlaunch/*" {
     capabilities = ["create", "read", "update", "delete", "list"]
   }
   
   path "kv/metadata/chainlaunch/*" {
     capabilities = ["read", "delete", "list"]
   }

   Apply it:

   vault policy write chainlaunch chainlaunch-policy.hcl

4. A token with that policy:

   vault token create -policy=chainlaunch -period=768h

Via API

curl -X POST http://localhost:8100/api/v1/key-providers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vault-production",
    "type": "VAULT",
    "isDefault": true,
    "vaultConfig": {
      "operation": "IMPORT",
      "address": "https://vault.yourcompany.com:8200",
      "token": "hvs.CAESxxxxx",
      "mount": "secret"
    }
  }'

Via Terraform

resource "chainlaunch_key_provider" "vault" {
  name       = "vault-production"
  type       = "VAULT"
  is_default = true

  vault_config = {
    operation = "IMPORT"
    address   = "https://vault.yourcompany.com:8200"
    token     = var.vault_token
    mount     = "secret"
  }
}

variable "vault_token" {
  type      = string
  sensitive = true
}

Use Vault for an Organization

Once the provider is created, assign it to organizations:

Via API

curl -X POST http://localhost:8100/api/v1/organizations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Org1MSP",
    "mspId": "Org1MSP",
    "description": "Production org with Vault keys",
    "providerId": 2
  }'

Via Terraform

resource "chainlaunch_fabric_organization" "org1" {
  msp_id      = "Org1MSP"
  description = "Production org with Vault keys"
  provider_id = tonumber(chainlaunch_key_provider.vault.id)
}

All keys created for this organization (node identity, TLS, CA) will be stored in Vault.

Supported Key Types

Algorithm	Curves	Supported
RSA	2048, 4096	Yes
EC (ECDSA)	P-256, P-384, P-521	Yes
secp256k1	—	No (use AWS KMS or database)
Ed25519	—	No

warning

Vault does not support the secp256k1 curve used by Ethereum/Besu. For Besu validator keys, use the AWS KMS or database provider instead.

Key Rotation

Vault supports automatic key rotation via its transit engine:

# Rotate a transit key
vault write -f transit/keys/chainlaunch-key-123/rotate

# Configure auto-rotation (every 90 days)
vault write transit/keys/chainlaunch-key-123/config auto_rotate_period=2160h

ChainLaunch will automatically use the latest key version for new operations while still being able to decrypt data encrypted with older versions.

High Availability

For production Vault deployments:

• Use Vault's integrated storage (Raft) with 3+ nodes
• Enable auto-unseal with a cloud KMS
• Configure audit devices for compliance
• Use performance replication for multi-region

Troubleshooting

"vault_reachable: false"

• Check the Vault address is accessible from the ChainLaunch server
• Verify firewall rules allow traffic on port 8200
• For managed Vault: check Docker is running and the container is up

"sealed: true"

Vault needs to be unsealed after restart:

vault operator unseal <unseal-key>

For managed Vault (CREATE mode), ChainLaunch handles unsealing automatically.

"permission denied"

The Vault token doesn't have the required policy. Verify:

vault token lookup <token>
vault policy read chainlaunch

Next Steps

• AWS KMS Integration for cloud-native key management
• Key Management for the complete key management overview
• Security Best Practices for production hardening